controller-cli

Name: controller-cli
Author: keep-starknet-strange

81stars25forks

How to install controller-cli?

keep-starknet-strange/starknet-agentic/controller-cli

$npx -y skills add keep-starknet-strange/starknet-agentic --skill controller-cli

Installs into the current project.

Summary

Guidance for installing and operating the Cartridge Controller CLI (controller) to create human-approved sessions and execute Starknet transactions with JSON output, explicit network selection, scoped policies, paymaster control, and error recovery.

Files · 1

View on GitHub

SKILL.md

1	# Cartridge Controller CLI
2
3	Use this skill when you need to run the Cartridge Controller CLI (`controller-cli`) to create a scoped session (human-approved) and then execute Starknet transactions via that session.
4
5	## When to Use
6
7	- Operating Cartridge Controller sessions with explicit network and least-privilege policies.
8	- Running `controller` or `controller_safe.py` for human-approved Starknet transactions.
9
10	## When NOT to Use
11
12	- General Starknet scripting that does not rely on Cartridge Controller.
13	- Contract authoring, testing, deployment, or security audit workflows.
14
15	Related modules: [skills catalog](../README.md).
16
17	## Non-Negotiable Rules
18
19	- Always pass `--json` and treat outputs as JSON.
20	- Always be explicit about network. Never rely on defaults:
21	- `--chain-id SN_MAIN\|SN_SEPOLIA`, or
22	- `--rpc-url <explicit url>`.
23	- `controller register` requires human browser authorization. Do not automate/bypass it.
24	- Use least-privilege policies only. Do not add token transfer permissions unless explicitly requested.
25	- Transaction links: use Voyager only:
26	- Mainnet: `https://voyager.online/tx/0x...`
27	- Sepolia: `https://sepolia.voyager.online/tx/0x...`
28
29	## Quick Start
30
31	```bash
32	curl -fsSL https://raw.githubusercontent.com/cartridge-gg/controller-cli/main/install.sh \| bash
33	export PATH="$PATH:$HOME/.local/bin"
34	controller --version
35	```
36
37	## Safer Wrapper (Recommended)
38
39	This skill includes a small wrapper that enforces the rules above and normalizes output:
40
41	```bash
42	python3 scripts/controller_safe.py status
43	python3 scripts/controller_safe.py register --preset loot-survivor --chain-id SN_MAIN
44	python3 scripts/controller_safe.py execute 0xCONTRACT entrypoint 0xCALLDATA --rpc-url https://api.cartridge.gg/x/starknet/sepolia
45	```
46
47	Behavior:
48	- Adds `--json` if missing.
49	- Refuses to run `call\|execute\|register\|transaction` without `--chain-id` or `--rpc-url`.
50	- Parses stdout as JSON.
51	- If `.status == "error"`, prints `error_code`, `message`, `recovery_hint` and exits non-zero.
52
53	## Deterministic Workflow
54
55	### 1) Generate Keypair
56
57	```bash
58	controller generate --json
59	```
60
61	The private key is stored locally (typically `~/.config/controller-cli/`).
62
63	### 2) Check Session Status
64
65	```bash
66	controller status --json
67	```
68
69	Common states:
70	- `no_session` (no keypair)
71	- `keypair_only` (needs registration)
72	- `active` (registered and not expired)
73
74	### 3) Register Session (Human Approval Required)
75
76	Requirement: a human must approve in a browser.
77
78	Option A (preferred): preset policies:
79
80	```bash
81	controller register --preset loot-survivor --chain-id SN_MAIN --json
82	```
83
84	Option B: least-privilege policy file:
85
86	```bash
87	controller register --file policy.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
88	```
89
90	Authorization output includes `short_url` and/or `authorization_url`:
91	- Display `short_url` if present; otherwise display `authorization_url`.
92	- Ask the user to open it and approve.
93	- The CLI blocks until approved or timeout (typically ~6 minutes).
94
95	### 4) Execute Transaction
96
97	Single call (positional args: contract, entrypoint, calldata):
98
99	```bash
100	controller execute 0xCONTRACT transfer 0xRECIPIENT,0xAMOUNT_LOW,0xAMOUNT_HIGH \
101	--rpc-url https://api.cartridge.gg/x/starknet/sepolia \
102	--json
103	```
104
105	Multiple calls from file:
106
107	```bash
108	controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
109	```
110
111	Optional confirmation wait:
112
113	```bash
114	controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --wait --timeout 300 --json
115	```
116
117	### 5) Read-Only Call (No Session Needed)
118
119	```bash
120	controller call 0xCONTRACT balance_of 0xADDRESS --chain-id SN_SEPOLIA --json
121	```
122
123	### 6) Transaction Status
124
125	```bash
126	controller transaction 0xTX_HASH --chain-id SN_SEPOLIA --wait --timeout 300 --json
127	```
128
129	### 7) Lookup Usernames / Addresses
130
131	```bash
132	controller lookup --usernames alice,bob --json
133	controller lookup --addresses 0x123...,0x456... --json
134	```
135
136	## Network Selection
137
138	Always be explicit about network.
139
140	Supported networks:
141
142	\| Chain ID \| RPC URL \|
143	\| --- \| --- \|
144	\| `SN_MAIN` \| `https://api.cartridge.gg/x/starknet/mainnet` \|
145	\| `SN_SEPOLIA` \| `https://api.cartridge.gg/x/starknet/sepolia` \|
146
147	Priority order:
148	1. `--rpc-url` flag
149	2. Stored session RPC URL (from registration)
150	3. Config default (lowest)
151
152	If network is ambiguous:
153	1. Run `controller status --json`
154	2. Match

People who liked this also viewed

6 picks

Type

controller-cli

81stars25forks

View on GitHub

How to install controller-cli?

keep-starknet-strange/starknet-agentic/controller-cli

$npx -y skills add keep-starknet-strange/starknet-agentic --skill controller-cli

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cartridge Controller CLI
2
3	Use this skill when you need to run the Cartridge Controller CLI (`controller-cli`) to create a scoped session (human-approved) and then execute Starknet transactions via that session.
4
5	## When to Use
6
7	- Operating Cartridge Controller sessions with explicit network and least-privilege policies.
8	- Running `controller` or `controller_safe.py` for human-approved Starknet transactions.
9
10	## When NOT to Use
11
12	- General Starknet scripting that does not rely on Cartridge Controller.
13	- Contract authoring, testing, deployment, or security audit workflows.
14
15	Related modules: [skills catalog](../README.md).
16
17	## Non-Negotiable Rules
18
19	- Always pass `--json` and treat outputs as JSON.
20	- Always be explicit about network. Never rely on defaults:
21	- `--chain-id SN_MAIN\|SN_SEPOLIA`, or
22	- `--rpc-url <explicit url>`.
23	- `controller register` requires human browser authorization. Do not automate/bypass it.
24	- Use least-privilege policies only. Do not add token transfer permissions unless explicitly requested.
25	- Transaction links: use Voyager only:
26	- Mainnet: `https://voyager.online/tx/0x...`
27	- Sepolia: `https://sepolia.voyager.online/tx/0x...`
28
29	## Quick Start
30
31	```bash
32	curl -fsSL https://raw.githubusercontent.com/cartridge-gg/controller-cli/main/install.sh \| bash
33	export PATH="$PATH:$HOME/.local/bin"
34	controller --version
35	```
36
37	## Safer Wrapper (Recommended)
38
39	This skill includes a small wrapper that enforces the rules above and normalizes output:
40
41	```bash
42	python3 scripts/controller_safe.py status
43	python3 scripts/controller_safe.py register --preset loot-survivor --chain-id SN_MAIN
44	python3 scripts/controller_safe.py execute 0xCONTRACT entrypoint 0xCALLDATA --rpc-url https://api.cartridge.gg/x/starknet/sepolia
45	```
46
47	Behavior:
48	- Adds `--json` if missing.
49	- Refuses to run `call\|execute\|register\|transaction` without `--chain-id` or `--rpc-url`.
50	- Parses stdout as JSON.
51	- If `.status == "error"`, prints `error_code`, `message`, `recovery_hint` and exits non-zero.
52
53	## Deterministic Workflow
54
55	### 1) Generate Keypair
56
57	```bash
58	controller generate --json
59	```
60
61	The private key is stored locally (typically `~/.config/controller-cli/`).
62
63	### 2) Check Session Status
64
65	```bash
66	controller status --json
67	```
68
69	Common states:
70	- `no_session` (no keypair)
71	- `keypair_only` (needs registration)
72	- `active` (registered and not expired)
73
74	### 3) Register Session (Human Approval Required)
75
76	Requirement: a human must approve in a browser.
77
78	Option A (preferred): preset policies:
79
80	```bash
81	controller register --preset loot-survivor --chain-id SN_MAIN --json
82	```
83
84	Option B: least-privilege policy file:
85
86	```bash
87	controller register --file policy.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
88	```
89
90	Authorization output includes `short_url` and/or `authorization_url`:
91	- Display `short_url` if present; otherwise display `authorization_url`.
92	- Ask the user to open it and approve.
93	- The CLI blocks until approved or timeout (typically ~6 minutes).
94
95	### 4) Execute Transaction
96
97	Single call (positional args: contract, entrypoint, calldata):
98
99	```bash
100	controller execute 0xCONTRACT transfer 0xRECIPIENT,0xAMOUNT_LOW,0xAMOUNT_HIGH \
101	--rpc-url https://api.cartridge.gg/x/starknet/sepolia \
102	--json
103	```
104
105	Multiple calls from file:
106
107	```bash
108	controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
109	```
110
111	Optional confirmation wait:
112
113	```bash
114	controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --wait --timeout 300 --json
115	```
116
117	### 5) Read-Only Call (No Session Needed)
118
119	```bash
120	controller call 0xCONTRACT balance_of 0xADDRESS --chain-id SN_SEPOLIA --json
121	```
122
123	### 6) Transaction Status
124
125	```bash
126	controller transaction 0xTX_HASH --chain-id SN_SEPOLIA --wait --timeout 300 --json
127	```
128
129	### 7) Lookup Usernames / Addresses
130
131	```bash
132	controller lookup --usernames alice,bob --json
133	controller lookup --addresses 0x123...,0x456... --json
134	```
135
136	## Network Selection
137
138	Always be explicit about network.
139
140	Supported networks:
141
142	\| Chain ID \| RPC URL \|
143	\| --- \| --- \|
144	\| `SN_MAIN` \| `https://api.cartridge.gg/x/starknet/mainnet` \|
145	\| `SN_SEPOLIA` \| `https://api.cartridge.gg/x/starknet/sepolia` \|
146
147	Priority order:
148	1. `--rpc-url` flag
149	2. Stored session RPC URL (from registration)
150	3. Config default (lowest)
151
152	If network is ambiguous:
153	1. Run `controller status --json`
154	2. Match

People who liked this also viewed

6 picks

Type