CLI Reference

The Suzi CLI (suzi) is the primary tool for managing the agent lifecycle, monitoring performance, and interacting with the Suzi platform. It supports both interactive development and automated headless execution.

Install via npm:

npm install -g suzi-cli

Global Options

Authentication

suzi login

Authenticates the CLI with your Suzi account. Opens your default browser to sign in with Google. Once authenticated, the CLI stores your access and refresh tokens locally at ~/.suzi/config.json.

After a successful login, the CLI automatically:

• Installs Suzi skills into the default local skill directories (~/.claude/skills, ~/.codex/skills, and ~/.agents/skills)
• Sets up shell hooks for context injection
• Prompts you to choose a default AI provider
• Displays your wallet deposit address with a QR code for funding

# Standard login (opens browser)
suzi login

# Headless login for CI/CD or sandboxed environments
export SUZI_SANDBOX_REFRESH_TOKEN="your_refresh_token"
suzi login --headless

Anyone with a valid SUZI_SANDBOX_REFRESH_TOKEN can seed a CLI session — the token is exchanged with the backend for an access token that authenticates all subsequent commands.

suzi logout

Signs out and clears stored credentials (access token, refresh token, and user data) from ~/.suzi/config.json. Your active account selection is preserved, so logging back in reconnects you to the same account.

suzi logout

suzi whoami

Displays the current authenticated user, active account ID, and associated wallet addresses (SVM and EVM). Useful for verifying your session is valid. LLMs and automated tools can use this command to check whether the CLI is authenticated before running other commands.

suzi whoami

Accounts

Each account is a named pair of wallets (SVM and EVM). You can create separate accounts for different purposes — for example, one for trading on prediction markets, another for providing liquidity, and so on. This makes it easier to track balances, positions, and agent activity in isolation.

suzi accounts

# List all accounts
suzi accounts list

# Create a new account for prediction market trading
suzi accounts create pm-trading

# Switch to it
suzi accounts switch pm-trading

# Show deposit addresses with QR codes
suzi accounts fund

Agent Management

suzi agents list

Lists all your deployed agents with their ID, title, status, and creation date.

suzi agents list

suzi agents view [id]

Shows detailed information about an agent. You can pass an agent ID, ID prefix, or name (case-insensitive). If the match is ambiguous, an interactive picker is shown.

Displays:

• ID, status, description and created/updated timestamps
• Agent spec — version, declared triggers, and resource requirements
• Wallet resources — allocated SVM and EVM addresses (if activated)

# View by name
suzi agents view my-trader

# View by ID prefix
suzi agents view abc12

suzi agents code [id]

Displays the deployed source code of an agent.

suzi agents code my-trader

suzi agents delete [id]

Permanently deletes an agent. Asks for confirmation before proceeding.

suzi agents delete my-trader

Deploy & Validate

suzi agents deploy [file]

Deploys a TypeScript agent file to the Suzi platform. If no file is specified, the CLI looks for a default agent file in the current directory, checking in order: agent.ts, src/agent.ts, index.ts, src/index.ts.

The file must contain a defineAgent() call. The CLI extracts meta.name and meta.description from the agent definition to set the agent's title and description on the platform.

# Deploy from current directory (auto-detects agent file)
suzi agents deploy

# Deploy a specific file
suzi agents deploy ./my-agent.ts

# Update an existing agent and activate it
suzi agents deploy ./my-agent.ts --update abc123 --activate

suzi agents validate [file]

Validates an agent file without deploying it. Sends the code to the API for full validation, including trigger schema checks. Uses the same file resolution as deploy if no file is specified.

suzi agents validate ./my-agent.ts

Activation & Execution

suzi agents activate [id]

Activates a deployed agent — this is the "start button." A deployed agent is just code on the platform; activating it makes it live. Once active, the agent subscribes to all its declared triggers (cron schedules, event listeners, etc.) and will begin executing when those triggers fire.

suzi agents activate my-trader

suzi agents deactivate [id]

Stops a running agent and unsubscribes from all its triggers. The agent's code and configuration remain on the platform — you can reactivate it at any time.

suzi agents deactivate my-trader

suzi agents execute [id] [trigger]

Manually fires a specific trigger on an agent. The trigger argument is the key name from the agent's triggers object (e.g. manual, rebalance, check_prices).

If no trigger is specified:

• Single trigger — auto-selected
• Multiple triggers — interactive picker is shown

# Auto-selects the only trigger
suzi agents execute my-trader

# Fire a specific trigger by name
suzi agents execute my-trader rebalance

Agent Logs

suzi agents logs [id]

Shows logs emitted by the agent's own code — calls to ctx.log(), ctx.warn(), ctx.error() inside trigger handlers and lifecycle hooks. The agent decides what to log and when.

# Show last 20 logs
suzi agents logs my-trader

# Show only errors, last 50
suzi agents logs my-trader --level error -n 50

Agent Config & Store

suzi agents config get [id]

Displays the configuration schema and current values for an agent. These are the config fields declared in the agent's defineAgent() definition — typed settings (number, string, boolean) with defaults, min/max constraints, and descriptions.

suzi agents config get my-trader

suzi agents config set [args...]

Updates configuration values for an agent using key=value pairs. Config values act as variables inside agent code — accessible via ctx.config.get('key') — and can be changed without redeploying. If the agent is active, Suzi automatically deactivates, applies the update, and reactivates it.

# Set a single config value
suzi agents config set my-trader maxBet=50

# Set multiple values at once
suzi agents config set my-trader maxBet=50 minOdds=0.6

suzi agents store

Manage an agent's persistent key-value store. The store acts as a local database for the agent — it can read and write data that persists across runs. Agents use this to track state like positions, last processed orders, counters, or any data that needs to survive between trigger executions.

Config vs Store: Config values are parameters you set before the agent runs (like maxBet=50). Store is data the agent itself writes during execution (like lastOrderId, totalPnl).

# List all stored keys
suzi agents store list my-trader

# Check a specific value
suzi agents store get my-trader lastOrderId

# Manually set a value (JSON-parsed)
suzi agents store set my-trader maxExposure 1000

Sharing & Import

suzi share create [agentId]

Creates a shareable link for an agent. When someone uses the link, the agent (including its code) is cloned into their account as a new agent. If no agent ID is provided, an interactive picker is shown.

# Create a share link with a custom slug
suzi share create my-trader --slug market-maker --expires 30

# Generate a Telegram share link
suzi share create my-trader --telegram

For the Telegram-first workflow, see Claw: Share & Import.

suzi share list

Lists all share links you've created, with their slugs, clone counts, and expiry status.

suzi share update <agentId>

Update the slug or expiry on an existing share.

suzi share revoke <snapshotId>

Disables a share link. Anyone who already cloned the agent keeps their copy, but the link stops working for new users.

suzi import <slug>

Imports a shared agent by its slug. Shows a preview of the agent (title, description, version, clone count, and required resources) before cloning it into your account.

This is also used by the Telegram bot (@suziclawbot) — when a user opens a share link in Telegram, the bot runs import behind the scenes and passes the agent info to the LLM.

suzi import market-maker

For the user-facing Telegram flow around this, see Claw: Share & Import.

Action Execution & Discovery

suzi agents run <action>

Executes a protocol action directly from the CLI. The action name must be in protocol.action_name format. This is the main way to run one-off actions — testing before writing agent code, or performing quick operations without deploying an agent.

Parameters can be passed as --key value flags (kebab-case is auto-converted to camelCase) or as a JSON string.

# Pass params as flags
suzi agents run polymarket.get_market_price --token-id 0x123

# Pass params as JSON
suzi agents run polymarket.place_order --json '{"tokenId":"0x123","side":"buy","size":"10"}'

# Preview what would be sent
suzi agents run polymarket.place_order --token-id 0x123 --side buy --dry-run

If the action name doesn't match any known action, the CLI suggests similar names.

suzi list-actions (alias: actions)

Lists all available protocol actions. Results are cached locally for performance.

# List all protocols and their action counts
suzi actions

# Show all Polymarket actions with full signatures
suzi actions --protocol polymarket --verbose

# Get the JSON schema for a specific action
suzi actions --schema polymarket.place_order

Use suzi list-actions reload to force-refresh the local cache from the API.

suzi list-triggers (alias: triggers)

Lists all available event triggers that agents can subscribe to.

suzi triggers --protocol polymarket --verbose

Portfolio & Finance

suzi portfolio

Displays a complete overview of your account — balances, open positions, and USD values across all protocols and chains (SVM and EVM).

suzi portfolio

# Include small balances
suzi portfolio --all-balances

suzi portfolio snapshots

View historical portfolio snapshots over time.

suzi portfolio snapshots --since 2026-03-01 --limit 50

suzi orders [agentId]

View orders, fills, and positions placed by an agent through protocol actions. If no agent ID is given, an interactive picker is shown.

The default view shows all three (orders, fills, and positions) together.

# Show everything for an agent
suzi orders my-trader

# Show only open orders on Polymarket
suzi orders list my-trader --protocol polymarket --status open

suzi transactions (alias: txns)

View all on-chain transactions going through the Suzi platform — not limited to agents. Covers orders, swaps, bridges, transfers, and more across your account.

# Show recent transactions
suzi txns

# Show only swaps for a specific agent
suzi txns --type swap --agent my-trader

Environment Variables

suzi env

Manage environment variables. These are used to store user-provided keys and secrets — for example, your Claude OAuth token, third-party API keys for use with the HTTP action, or any credentials agents need at runtime. Variables are encrypted at rest and accessible inside agent code via ctx.env.MY_API_KEY.

Variables can be scoped to your account (available to all agents) or to a specific agent.

Running suzi env with no subcommand opens an interactive menu.

Variable names must be uppercase with underscores (e.g. MY_API_KEY).

# Set an account-level API key
suzi env set OPENAI_API_KEY

# Set a variable scoped to a specific agent
suzi env set WEBHOOK_URL --agent my-trader

# List all variables (masked)
suzi env list

# List with decrypted values
suzi env list --reveal

Observability & Debugging

The debug namespace gives you deep backend observability. While suzi agents logs shows what the agent self-reported (via ctx.log()), the debug commands show the full picture from Datadog and the database — including backend errors, execution internals, and infrastructure issues that the agent code itself may not be aware of. All logs are attributed by agent ID.

suzi debug logs [agentId]

Fetch raw Datadog logs for an agent.

# Last hour of errors
suzi debug logs my-trader --status error

# Last 24 hours, custom query
suzi debug logs my-trader --time-range now-1d --query "timeout"

suzi debug aggregate [agentId]

Aggregates Datadog log counts, optionally grouped by a field. Instead of individual log lines, you get totals — useful for pattern recognition like "how often is my agent erroring?"

suzi debug aggregate my-trader --group-by status --time-range now-1h

suzi debug db-logs [agentId]

Same data source as suzi agents logs (self-reported ctx.log() calls from the database) but with more control:

• Filter by --run-id to isolate logs from a single execution run
• Server-side cursor pagination (--cursor) for scrolling through large volumes
• Higher default limit (50 vs 20)
• Shows Run ID column so you can correlate logs to specific runs

# Isolate logs from a single run
suzi debug db-logs my-trader --run-id abc123

suzi debug executions [agentId]

Shows every action your agent called and what happened — from the action_executions table. Each row shows the action name, status, run ID, and error (if any). For failed executions, the full input and output are displayed so you can see exactly what the agent tried and what came back.

Use this when an agent logged "placing order" but nothing happened — check executions to see if the action was actually called and why it failed.

suzi debug executions my-trader --status failed

suzi debug runs [agentId]

The highest-level view — each row is one complete agent invocation. Shows when it started, which trigger fired, how many action executions succeeded or failed, and the overall outcome.

Key columns:

• Status: running, completed, failed — the lifecycle state.
• Outcome: success, degraded, failed — the logical result. An agent can "complete" but have a "degraded" outcome if some actions failed.
• Exec Fails: ratio like 2/5 meaning 2 of 5 action executions failed.
• Trigger: which trigger fired (manual, cron, event name).

suzi debug runs my-trader --status failed

AI & Tooling Integration

suzi start [dir]

Launches an AI-assisted coding session using Claude Code or Codex. Opens a session in the specified directory (or current directory) where you can build an agent interactively with AI help.

Session locking: Creates a .suzi-lock file to prevent concurrent modifications. If you return to a directory with an active session, the CLI will offer to resume it. Use --force to bypass the lock and start fresh.

# Start a new session
suzi start

# Start with Codex
suzi start --ai codex

# Clone an existing agent and edit it
suzi start --id abc123

# Set Claude as default provider
suzi start --set-default claude

suzi resume

Reconnects to an active AI session, preserving the full conversation context. Use --id <sessionId> to target a specific session, or run without arguments for an interactive picker.

suzi resume
suzi resume --id session_abc123

suzi skills

Manage Suzi skills. Skills are installed locally and provide specialized context and capabilities during AI sessions.

# List available skills
suzi skills

# Install a skill
suzi skills add suzi-guide

# Install to a custom directory instead of the default targets
suzi skills add suzi-guide --dir ./tmp/skills

# Reinstall all skills
suzi skills sync

suzi install-hooks

Installs pre-made Claude Code hooks that inject dynamic Suzi context into every session automatically. This gives Claude Code awareness of your agents, account state, and available actions without you having to explain it each time.

suzi install-hooks

Preferences

suzi preferences

View and manage user settings.

# Set a custom API URL (for local development)
suzi preferences set api-url http://localhost:3001

# Connect Telegram
suzi preferences telegram

For the full Telegram setup flow, see Claw: Getting Started.

Utilities

suzi update

Check for and install CLI updates.

# Check for updates
suzi update --check

# Update immediately
suzi update -y

suzi feedback

Submit feedback directly to the Suzi team — bug reports, feature requests, or general comments. Includes recent CLI context automatically for better debugging.

suzi feedback