@cavos/cli

Cavos CLI is the ultimate toolkit for AI Agents to interact with Starknet (Mainnet). It provides a session-key based wallet interface designed for both human manual use and autonomous agent execution.

Features

• Session Management: Securely import and manage session keys.
• Wallet Operations: Transfer tones, check balances, approve spenders.
• Contract Interaction: Call view functions, execute transactions, and simulate execution.
• AI-Native Tools:
  • Introspection: Fetch contract ABIs (cavos contract get-abi) so agents know how to call functions.
  • Monitoring: distinct transaction status checks (cavos tx status).
  • Events: Listen to on-chain events (cavos events list).
• structured JSON Output: All commands support --json for easy parsing by LLMs.

Installation

For Humans (Global Install)

npm install -g @cavos/cli

For Agents / Scripts (On the fly)

npx @cavos/cli <command>

Setup

Before acting, you need a session token. You can generate one from your Cavos Dashboard.

1. Import Session:

   cavos session import "eyJhbG..."

2. Verify Status:

   cavos whoami

Usage

Basic Commands

Check Balance:

cavos balance
# OR specific token
cavos balance --token STRK

Transfer Funds:

# Send 10 STRK
cavos transfer --to 0xRecipient --amount 10 --token STRK

Approve Spender:

# Approve a DEX to spend 100 STRK
cavos approve --spender 0xRouter --amount 100 --token STRK

Advanced Contract Interaction

Read-Only Call:

cavos call --contract 0xContract --entrypoint balance_of --calldata "0xUser"

Execute Transaction:

cavos execute --contract 0xSwap --entrypoint swap --calldata "100,0"

Simulate Execution (Dry Run):

cavos simulate --contract 0xSwap --entrypoint swap --calldata "100,0"

AI Agent Features (Phase 2)

These commands are designed to help AI agents understand the environment and debug their own actions.

1. Introspection (Get ABI): Agents can discover available functions on any contract.

cavos contract get-abi --address 0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d

Returns a clean JSON ABI.

2. Transaction Monitoring: Check why a transaction failed or if it's confirmed.

cavos tx status --hash 0xTxHash

Returns execution status, finality, and revert reason if failed.

3. Event Listening: Monitor the chain for specific events (e.g., "Transfer").

cavos events list --contract 0xToken --keys 0xEventHash

Integration with LLMs

You can feed the output of cavos tools list directly to OpenAI's function calling API to give your agent full control over the CLI.

cavos tools list

All commands output structured JSON when using the --json flag:

cavos whoami --json

Output:

{
  "status": "ok",
  "mode": "disk",
  "address": "0x123...",
  "deployed": true,
  "session": {
    "registered": true,
    "expired": false,
    "can_renew": true
  }
}

License

MIT