controller-cli

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.