Controller CLI

Manage Cartridge Controller sessions and execute Starknet transactions through a secure human-in-the-loop workflow.

Prerequisites

Controller CLI must be installed:

curl -fsSL https://raw.githubusercontent.com/cartridge-gg/controller-cli/main/install.sh | bash

Session Workflow

Sessions use keypair-based auth where humans authorize specific contracts/methods via browser, then the agent executes transactions within those constraints.

1. Check status — controller status --json
2. Generate keypair (if needed) — controller generate --json
3. Create policy file — Define allowed contracts and methods
4. Register session — controller register --file policy.json --json (user must authorize via browser URL)
5. Execute transactions — controller execute <contract> <entrypoint> <calldata> --json

Commands

Status & Setup

controller status --json          # Check session status and expiration
controller generate --json        # Generate new session keypair
controller clear --yes            # Clear all session data

Register Session

controller register --file policy.json --json

Outputs an authorization URL. Display it to the user and wait — the command polls for up to 6 minutes until the user authorizes in their browser.

Execute Transaction

Single call (positional args):

controller execute <contract> <entrypoint> <calldata> [--wait] [--timeout <secs>] --json

Multiple calls from file:

controller execute --file calls.json [--wait] --json

Read-Only Call (no session required)

controller call <contract> <entrypoint> <calldata> --chain-id SN_SEPOLIA --json
controller call --file calls.json --chain-id SN_SEPOLIA --json

Transaction Status

controller transaction <hash> --chain-id SN_SEPOLIA [--wait] --json

Username/Address Lookup

controller lookup --usernames shinobi,sensei --json
controller lookup --addresses 0x123...,0x456... --json

Calldata Format

• Values are comma-separated, hex with 0x prefix by default
• Decimal values: use u256:100 prefix for automatic u256 encoding
• String values: use str:hello prefix for automatic felt encoding
• U256 manual encoding: split into low,high — e.g., 100 tokens = 0x64,0x0

Policy File Format

See references/policy-examples.md for complete examples.

{
  "contracts": {
    "<contract_address>": {
      "name": "Contract Name",
      "methods": [
        { "name": "transfer", "entrypoint": "transfer", "description": "Transfer tokens" }
      ]
    }
  }
}

Multi-Call File Format

{
  "calls": [
    {
      "contractAddress": "<contract_address>",
      "entrypoint": "transfer",
      "calldata": ["0xRECIPIENT", "0x64", "0x0"]
    }
  ]
}

Common Contracts (Sepolia)

Error Handling

Important Notes

• Always use --json flag for machine-readable output
• Sessions expire — always check status before transactions
• Human authorization is required for all sessions (cannot be bypassed)
• Sepolia transactions are automatically subsidized (no gas needed)
• Contract addresses must be 32-byte hex with 0x prefix