Skip to main content
controller-cli 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.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/keep-starknet-strange/starknet-agentic --skill controller-cliThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... name controller-cli description 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. license Apache-2.0 metadata {"author":"keep-starknet-strange","version":"1.0.0","org":"keep-starknet-strange"} compatibility controller-cli >=0.1.x, Python 3.8+ keywords ["starknet","cartridge","controller","controller-cli","session","paymaster","voyager"] allowed-tools ["Bash","Read","Write","Grep"] user-invocable true
Cartridge Controller CLI
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.
When to Use
Operating Cartridge Controller sessions with explicit network and least-privilege policies.
Running controller or controller_safe.py for human-approved Starknet transactions.
When NOT to Use
General Starknet scripting that does not rely on Cartridge Controller.
Contract authoring, testing, deployment, or security audit workflows.
Related modules: skills catalog .
Non-Negotiable Rules
Always pass --json and treat outputs as JSON.
Always be explicit about network. Never rely on defaults:
--chain-id SN_MAIN|SN_SEPOLIA, or--rpc-url <explicit url>.
controller register requires human browser authorization. Do not automate/bypass it.Use least-privilege policies only. Do not add token transfer permissions unless explicitly requested.
Transaction links: use Voyager only:
Mainnet: https://voyager.online/tx/0x...
Sepolia: https://sepolia.voyager.online/tx/0x...
Quick Start
curl -fsSL https://raw.githubusercontent.com/cartridge-gg/controller-cli/main/install.sh | bash
export PATH="$PATH :$HOME /.local/bin"
controller --version
Safer Wrapper (Recommended)
This skill includes a small wrapper that enforces the rules above and normalizes output:
python3 scripts/controller_safe.py status
python3 scripts/controller_safe.py register --preset loot-survivor --chain-id SN_MAIN
python3 scripts/controller_safe.py execute 0xCONTRACT entrypoint 0xCALLDATA --rpc-url https://api.cartridge.gg/x/starknet/sepolia
Behavior:
Adds --json if missing.
Refuses to run call|execute|register|transaction without --chain-id or --rpc-url.
Parses stdout as JSON.
If .status == "error", prints error_code, message, recovery_hint and exits non-zero.
Deterministic Workflow
1) Generate Keypair controller generate --json
The private key is stored locally (typically ~/.config/controller-cli/).
2) Check Session Status
no_session (no keypair)keypair_only (needs registration)active (registered and not expired)
3) Register Session (Human Approval Required) Requirement: a human must approve in a browser.
Option A (preferred): preset policies:
controller register --preset loot-survivor --chain-id SN_MAIN --json
Option B: least-privilege policy file:
controller register --file policy.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
Authorization output includes short_url and/or authorization_url:
Display short_url if present; otherwise display authorization_url.
Ask the user to open it and approve.
The CLI blocks until approved or timeout (typically ~6 minutes).
4) Execute Transaction Single call (positional args: contract, entrypoint, calldata):
controller execute 0xCONTRACT transfer 0xRECIPIENT,0xAMOUNT_LOW,0xAMOUNT_HIGH \
--rpc-url https://api.cartridge.gg/x/starknet/sepolia \
--json
Multiple calls from file:
controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --json
Optional confirmation wait:
controller execute --file calls.json --rpc-url https://api.cartridge.gg/x/starknet/sepolia --wait --timeout 300 --json
5) Read-Only Call (No Session Needed) controller call 0xCONTRACT balance_of 0xADDRESS --chain-id SN_SEPOLIA --json
6) Transaction Status controller transaction 0xTX_HASH --chain-id SN_SEPOLIA --wait --timeout 300 --json
7) Lookup Usernames / Addresses controller lookup --usernames alice,bob --json
controller lookup --addresses 0x123...,0x456... --json
Network Selection Always be explicit about network.
Chain ID RPC URL SN_MAINhttps://api.cartridge.gg/x/starknet/mainnetSN_SEPOLIAhttps://api.cartridge.gg/x/starknet/sepolia
--rpc-url flagStored session RPC URL (from registration)
Config default (lowest)
Run controller status --json
Match the session chain_id, or ask the user
Paymaster Control Default behavior uses the paymaster (free execution). If the paymaster is unavailable, the transaction fails (no silent fallback).
To self-pay with user funds:
controller execute ... --no-paymaster --json
Amount Encoding (u256) Many ERC20-style amounts are u256 split into (low, high) u128 limbs.
For values that fit in u128 (most cases): set high = 0x0.
Example calldata:
0xRECIPIENT,0x64,0x0
Error Handling {
"status" : "error" ,
"error_code" : "ErrorType" ,
"message" : "..." ,
"recovery_hint" : "..."
}
Always branch on error_code and follow recovery_hint.
NoSession: run controller generate --jsonSessionExpired: re-run controller register ... --jsonManualExecutionRequired: policy does not authorize the call; tighten/adjust policy and re-registerCallbackTimeout: user did not approve quickly enough; re-run register and retry
Input Validation Addresses must be 0x-prefixed hex.
python3 scripts/validate_hex_address.py 0xabc...
More from this repository Routes Starknet agent, wallet, DeFi, identity, SDK, and Cairo contract work to the smallest focused skill module.
SNIP-36 virtual block proving on Starknet. Trigger on "virtual block", "SNIP-36", "off-chain proof", "anonymous vote", "heavy computation off-chain", "prove a transaction". Covers Cairo virtual contract, proof server, starknet.js integration, and on-chain verification.
Security audit of Cairo/Starknet code. Trigger on "audit", "check this contract", "review for security". Modes - default (full repo), deep (+ adversarial reasoning), or specific filenames.
Related occupations SOC
Based on SOC occupation classification
