controller-cli

name	controller-cli
description	Execute Starknet transactions using Cartridge Controller sessions with human-authorized policies. Use when the user wants to execute Starknet smart contract transactions, transfer tokens on Starknet, interact with gaming contracts, query contract state, check token balances, look up Cartridge usernames/addresses, or manage session-based authentication.

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 session status --json
2. Authorize session (if needed) — controller session auth --file policy.json --json (generates keypair + user must authorize via browser URL)
3. Execute transactions — controller execute <contract> <entrypoint> <calldata> --json

Commands

Session Management

controller session auth --file policy.json --json    # Generate keypair and authorize a new session
controller session auth --preset loot-survivor --json # Use a preset policy
controller session status --json                      # Check session status and expiration
controller session list --json                        # List all active sessions
controller session list --limit 20 --page 2 --json   # Paginated session list
controller session clear --yes                        # Clear all session data

The session auth command generates a keypair, outputs an authorization URL, and 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

Transaction Receipt

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

Returns full receipt: execution status, fee, events, messages, and execution resources.

Token Balances

controller balance --json                    # All non-zero token balances
controller balance eth --json                # Specific token balance
controller balance --chain-id SN_MAIN --json # Query mainnet balances

Built-in tokens: ETH, STRK, USDC, USD.e, LORDS, SURVIVOR, WBTC. Add custom tokens via controller config set token.<SYMBOL> <address>.

Account Username

controller username --json    # Display username for active session account

Username/Address Lookup

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

Configuration

controller config set <key> <value>    # Set a config value
controller config get <key> --json     # Get a config value
controller config list --json          # List all config values

Valid keys: rpc-url, keychain-url, api-url, storage-path, json-output, colors, callback-timeout, token.<symbol>.

Marketplace

Buy NFTs from the Arcade marketplace.

# Check if an order is valid
controller marketplace info \
  --order-id 42 \
  --collection 0x123...abc \
  --token-id 1 \
  --chain-id SN_MAIN --json

# Purchase from a listing
controller marketplace buy \
  --order-id 42 \
  --collection 0x123...abc \
  --token-id 1 \
  --chain-id SN_MAIN \
  --wait --json

Options:

• --order-id: Marketplace order ID
• --collection: NFT collection address
• --token-id: Token ID to purchase
• --asset-id: Asset ID for ERC1155 (default: 0)
• --quantity: Amount to buy (default: 1)
• --no-royalties: Skip creator royalties

Required session policies: execute on marketplace contract, approve on payment token.

Calldata Format

• Values are comma-separated
• Hex: 0x64 (standard hex felt)
• Decimal: 100 (auto-converted)
• u256: prefix: u256:1000000000000000000 (auto-splits into low/high 128-bit felts)
• str: prefix: str:hello (Cairo short string encoding)
• bytearray: prefix: bytearray:hello (Cairo ByteArray multi-felt serialization)
• bytearray: quoted: bytearray:"hello world" (ByteArray with spaces, quotes stripped)
• bytearray: raw bytes: bytearray:[0x48,0x65,0x6c,0x6c,0x6f] (ByteArray from raw byte values)
• Manual u256: 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)

Token	Address
ETH	0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7
STRK	0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d

Error Handling

Error	Cause	Fix
NoSession	No keypair found	Run controller session auth --file policy.json
SessionExpired	Session expired	Run controller session auth --file policy.json
ManualExecutionRequired	No authorized session	Authorize session with appropriate policies
PolicyViolation	Transaction not in allowed policies	Authorize new session with expanded policies

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