CLI Reference

Comprehensive reference for the current Suzi command-line interface — agents, direct execution, automation, debugging, and local tooling.

The Suzi CLI (suzi) is the primary surface for the platform. It now centers on a smaller public command model: create or resume agent sessions, deploy and manage agents, run protocol actions directly, inspect portfolio and activity, and automate everything with structured JSON output.

Install via npm:

npm install -g suzi-cli

Global Behavior

Option	Description
`-V, --version`	Output the version number.
`-h, --help`	Display help for any command.
`--no-input`	Disable interactive prompts. Commands fail with explicit guidance instead of waiting for input.

--json is not a single global switch. It is available on many individual commands and is the canonical machine output mode for automation, CI, and LLM-driven workflows.

Running suzi with no arguments opens a structured landing screen with quick-start, portfolio, discovery, debugging, and settings commands.

Machine-Friendly Usage

The current CLI is designed to be scriptable:

Start discovery with suzi --help --json
Use suzi <command> --json --no-input for machine consumption
Prefer suzi run <protocol.action> --help to inspect action-specific inputs and examples
Use suzi skills sync if a local Suzi skill is missing from ~/.agents/skills

Structured Errors

JSON responses use stable error codes and distinct exit codes.

Error code	Exit code	Meaning
`AUTH_REQUIRED`	`2`	Login or session refresh is required.
`VALIDATION_FAILED`	`3`	Input shape, flags, or schema validation failed.
`INPUT_REQUIRED`	`3`	A prompt would have been needed, but `--no-input` or a non-interactive context prevented it.
`NOT_FOUND`	`4`	The requested resource or command target was not found.
`NETWORK_ERROR`	`5`	The CLI could not reach the API or another remote dependency.
`RATE_LIMITED`	`6`	A rate limit was hit.
`INTERNAL_ERROR`	`1`	Any other failure.

Authentication

Authenticates the CLI with your Suzi account. Browser login uses Google OAuth through the Suzi web app. Headless login exchanges SUZI_SANDBOX_REFRESH_TOKEN for a normal CLI session.

After a successful interactive login, the CLI:

stores tokens and account metadata in ~/.suzi/config.json
prompts for your default AI provider
installs Suzi skills into the shared Suzi store at ~/.suzi/skills
links those canonical skills into supported local clients such as ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills
installs Claude Code hooks for context injection
shows wallet funding details for the active account

The post-login path is explicit: authenticate, sync skills and hooks, fund the active account if needed, and continue with suzi start when you are ready to create an agent.

Flag	Description
`--headless`	Authenticate non-interactively from `SUZI_SANDBOX_REFRESH_TOKEN`.
`--invite <code>`	Invite code for new account signups.
`--api-url <url>`	Override the API base URL.
`--web-url <url>`	Override the web app URL.

suzi login

export SUZI_SANDBOX_REFRESH_TOKEN="your_refresh_token"
suzi login --headless

`suzi logout`

Signs out and clears stored credentials.

suzi logout

`suzi whoami`

Shows the current authenticated user and active account. --json is supported and is the canonical way to verify auth state in scripts.

suzi whoami
suzi whoami --json

Accounts

Each account is a named pair of wallets (SVM and EVM). The CLI keeps the local active account aligned with the server-reported active account when possible.

`suzi accounts`

Running suzi accounts with no subcommand shows the current accounts list and, in interactive mode, acts as an account switcher.

Subcommand	Description
`list`	List all accounts.
`show`	Show wallet addresses for the active account. Supports `--json`.
`fund`	Show deposit instructions and QR codes for the active account.
`switch <name>`	Switch the active account.
`create <name>`	Create a new account.
`rename <name> <newName>`	Rename an account.
`delete <name>`	Delete an account. Use `-f` to skip confirmation.

suzi accounts
suzi accounts show --json
suzi accounts create pm-trading
suzi accounts switch pm-trading
suzi accounts fund

Agent Management

`suzi agents` and `suzi agents list`

Lists your deployed agents. suzi agents defaults to the same behavior as suzi agents list.

suzi agents
suzi agents list --json

`suzi agents view [id]`

Shows detailed agent information, including metadata, triggers, resources, and allocated wallets when activated.

suzi agents view my-trader

`suzi agents code [id]`

Displays the currently deployed source code for an agent.

suzi agents code my-trader

`suzi agents delete [id]`

Deletes an agent. Use -f to skip confirmation.

suzi agents delete my-trader -f

Deploy, Validate, and Operate

`suzi agents deploy [file]`

Deploys an agent from a TypeScript file. If no file is given, the CLI auto-discovers agent.ts, src/agent.ts, index.ts, or src/index.ts.

Flag	Description
`--update <agentId>`	Update an existing agent instead of creating a new one.
`--activate`	Activate immediately after deployment.
`--json`	Output structured JSON.

suzi agents deploy
suzi agents deploy ./agent.ts --activate
suzi agents deploy ./agent.ts --update abc123

`suzi agents validate [file]`

Validates an agent file without deploying it.

suzi agents validate ./agent.ts

`suzi agents activate [id]`

Activates a deployed agent and registers its triggers.

suzi agents activate my-trader

`suzi agents deactivate [id]`

Stops a running agent. The agent remains deployed and can be reactivated later.

suzi agents deactivate my-trader

`suzi agents execute [id] [trigger]`

Manually fires a trigger on an agent. If the trigger is omitted, the CLI auto-selects the only trigger or shows an interactive picker when several exist.

suzi agents execute my-trader
suzi agents execute my-trader rebalance

`suzi agents logs [id]`

Shows the agent's own log output.

Flag	Description
`-n, --limit <n>`	Number of entries to return.
`--level <level>`	Filter by `info`, `warn`, `error`, or `debug`.
`--since <datetime>`	Filter by time.
`--json`	Output structured JSON.

suzi agents logs my-trader --level error -n 50

`suzi agents runs [id]`

Shows agent trigger executions from the agent surface.

suzi agents runs my-trader --status failed

Agent Config and Store

`suzi agents config`

Manage typed config values declared in agent code.

Subcommand	Description
`get [id]`	Fetch config schema and current values.
`set [args...]`	Update one or more values using `key=value` pairs.

suzi agents config get my-trader
suzi agents config set my-trader maxBet=50 minOdds=0.6

`suzi agents store`

Manage an agent's persistent key-value store.

Subcommand	Description
`list [id]`	List all store keys.
`get <idOrKey> [key]`	Get a specific store value.
`set <args...>`	Set a value. The payload is JSON-parsed.
`delete <idOrKey> [key]`	Delete a store key.

suzi agents store list my-trader
suzi agents store get my-trader lastOrderId
suzi agents store set my-trader maxExposure 1000

Agent History, Versioning, and Forks

The CLI now exposes agent history and fork workflows directly.

Command	Description
`suzi agents history [id]`	Show commit history.
`suzi agents diff [id] [sha]`	Show the patch for a specific commit.
`suzi agents version [id] [sha]`	Show source code at a specific commit.
`suzi agents checkout [id] [sha]`	Revert the agent to a previous commit.
`suzi agents fork [id]`	Create your own fork of an agent.
`suzi agents upstream [id]`	Check whether the upstream agent has new commits.
`suzi agents pull [id]`	Pull upstream changes into a fork, with conflict reporting when necessary.
`suzi agents forks [id]`	List all forks for an agent.

If sha is omitted for diff, version, or checkout, the CLI offers an interactive picker. In non-interactive mode, pass the commit SHA explicitly.

suzi agents history my-trader
suzi agents diff my-trader 4fd2c8a
suzi agents version my-trader 4fd2c8a
suzi agents checkout my-trader 4fd2c8a
suzi agents fork public-agent
suzi agents upstream my-fork
suzi agents pull my-fork

Share deployed agents and manage existing shared snapshots.

Subcommand	Description
`create [agentId]`	Create a shareable link.
`list` / `ls`	List your shared agents.
`update <agentId>`	Publish a new shared version.
`revoke <snapshotId>`	Revoke a shared snapshot.

suzi share create supports:

Flag	Description
`-s, --slug <slug>`	Custom share slug.
`-e, --expires <days>`	Expiry in days.
`-t, --telegram`	Create a Telegram-oriented share link.

suzi share create my-trader --slug market-maker --expires 30
suzi share list
suzi share update my-trader --slug market-maker
suzi share revoke snapshot_123

`suzi import <slug>`

Clone a shared agent into your account.

suzi import market-maker

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

Direct Action Execution and Discovery

`suzi run [action]`

Executes a protocol action directly.

Input styles

suzi run supports three input styles:

--param value
bare param value
--params '{...}'

Use --json for JSON output. Use --params for JSON input.

Built-in validation

Before sending the request, the CLI validates:

missing required fields
invalid types
unknown parameters
accidental misuse of --json as an input flag
conflicting input styles such as --params together with individual args

Action-specific help

suzi run <protocol.action> --help shows:

parameter names
types and constraints
required vs optional fields
concrete examples

suzi run polymarket.deposit --help

Examples

# Canonical JSON body + JSON output
suzi run polymarket.deposit --params '{"amount":1}' --json

# Individual flags
suzi run polymarket.deposit --amount 1

# Bare key/value pairs
suzi run polymarket.deposit amount 1

# Preview the payload without executing
suzi run polymarket.deposit --amount 1 --dry-run

`suzi list-actions` (alias: `actions`)

Lists protocols and actions. It supports a positional protocol shorthand:

suzi list-actions polymarket

Flag	Description
`[protocol]`	Positional shorthand for `--protocol`.
`--protocol <name>`	Filter by protocol.
`--verbose`	Show actions per protocol.
`--schema <actions>`	Output action schema for one action, multiple comma-separated actions, or `all`.
`--json`	Output structured JSON with total and visible counts.

Examples:

suzi list-actions
suzi list-actions polymarket
suzi list-actions --protocol polymarket --schema deposit
suzi list-actions --protocol polymarket --schema all
suzi list-actions --schema polymarket.deposit,solana.get_native_balance
suzi list-actions reload

The local actions cache refreshes every 5 minutes by default.

`suzi list-triggers` (alias: `triggers`)

Lists available triggers. It also supports a positional protocol shorthand.

Flag	Description
`[protocol]`	Positional shorthand for `--protocol`.
`--protocol <name>`	Filter by protocol.
`--verbose`	Show config fields, outputs, and examples.
`--schema <trigger>`	Output the schema for a specific trigger. Requires `--protocol`.
`--json`	Output structured JSON with total and visible counts.

suzi list-triggers
suzi list-triggers hyperliquid
suzi list-triggers --protocol polymarket --schema price_move

Portfolio and Activity

`suzi portfolio`

Shows the full account portfolio, or an agent-attributed summary when --agent is used. Summary output defaults to open positions and active orders.

Flag	Description
`--json`	Canonical raw snapshot output.
`--all-balances`	Include low-value balances, positions, and orders.
`--svm-wallet <address>`	Override SVM wallet address.
`--evm-wallet <address>`	Override EVM wallet address.
`--agent [agentIdOrName]`	Filter to a specific agent. Omit the value to pick interactively.
`-p, --protocol <protocol>`	Filter protocol-specific agent summary sections.

suzi portfolio
suzi portfolio --json
suzi portfolio --agent my-trader --protocol polymarket

`suzi portfolio orders`

Shows account-level or agent-attributed orders. Defaults to active orders; use --status inactive to view filled, cancelled, or expired rows. --include fills adds fills to the response.

suzi portfolio orders --protocol polymarket --status active
suzi portfolio orders --agent my-trader --include fills

`suzi portfolio positions`

Shows account-level or agent-attributed positions. Defaults to open positions; use --status closed to view closed rows.

suzi portfolio positions --protocol hyperliquid --status open
suzi portfolio positions --protocol polymarket --status closed
suzi portfolio positions --agent my-trader

`suzi portfolio snapshots`

Shows historical portfolio snapshots.

Flag	Description
`--since <datetime>`	ISO-8601 lower bound.
`--until <datetime>`	ISO-8601 upper bound.
`-n, --limit <n>`	Number of rows, default `168`, max `1000`.
`--order <dir>`	Must be `newest` or `oldest`.
`--json`	Output structured JSON.

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

`suzi transactions` (alias: `txns`)

Shows recent transactions across the active account.

Flag	Description
`-n, --limit <n>`	Number of transactions to return.
`--type <type>`	Filter by `order`, `cancel`, `transfer`, `swap`, `bridge`, or `liquidity`.
`--protocol <name>`	Filter by protocol.
`--agent <id>`	Filter by agent.
`--cursor <id>`	Pagination cursor.
`--json`	Output structured JSON.

suzi txns
suzi txns --type swap --agent my-trader

Environment Variables

`suzi env`

Running suzi env with no subcommand opens an interactive menu in TTY mode and otherwise prints the current variables plus direct-command guidance.

Variables can be user-scoped or agent-scoped. Names must start with an uppercase letter and may contain only A-Z, 0-9, and _.

Subcommand	Description
`list`	List environment variable names. Use `--reveal` to decrypt values.
`set <key>`	Set a variable. Use `--value` for non-interactive usage.
`remove <key>`	Remove a variable. Use `--force` in non-interactive usage.

Flag	Description
`--agent <id>`	Scope to a specific agent.
`--reveal`	Decrypt and print values on `list`.
`--value <value>`	Required for `env set` in non-interactive contexts.
`--force`	Skip confirmation on `env remove`.

suzi env
suzi env list --reveal
suzi env set OPENAI_API_KEY --value sk-example
suzi env set WEBHOOK_URL --agent my-trader --value https://example.com/hook
suzi env remove WEBHOOK_URL --agent my-trader --force

Observability and Debugging

The debug namespace exposes backend-facing views that go beyond the self-reported agent logs in suzi agents logs.

Command	Description
`suzi debug logs [agentId]`	View Datadog logs.
`suzi debug aggregate [agentId]`	Aggregate Datadog log counts, optionally grouped.
`suzi debug db-logs [agentId]`	View agent logs stored in the database.
`suzi debug executions [agentId]`	View action execution records, with inputs, outputs, and errors.
`suzi debug runs [agentId]`	View run-level execution summaries from the database.

Examples

suzi debug logs my-trader --status error --time-range now-1d
suzi debug aggregate my-trader --group-by status
suzi debug db-logs my-trader --run-id run_123
suzi debug executions my-trader --status failed
suzi debug runs my-trader --status failed

`suzi debug runs` status modes

suzi debug runs --status failed uses logical failure filtering by default:

effective mode treats degraded outcomes as failures
raw mode only shows lifecycle failures

suzi debug runs my-trader --status failed --status-mode raw

AI and Local Tooling

`suzi start [dir]`

Starts an AI-assisted agent editing session with Claude Code or Codex.

What it does:

scaffolds agent.ts unless --no-scaffold is used
creates AGENTS.md if needed
tracks the session in ~/.suzi/sessions.json
uses a project lock file to prevent concurrent edits
can clone an existing deployed agent locally with --id

Flag	Description
`--ai <provider>`	Choose `claude` or `codex`.
`--set-default <provider>`	Persist the default provider for future sessions.
`--id <agentId>`	Clone a deployed agent by ID and edit it locally.
`--no-scaffold`	Skip `agent.ts` template creation.
`--force`	Ignore an existing session lock and start fresh.

suzi start
suzi start --ai codex
suzi start --id abc123
suzi start --set-default claude

`suzi resume`

Resume a recent AI session. Without --id, the CLI shows a picker of recent sessions.

suzi resume
suzi resume --id session_abc123

`suzi skills`

Manage Suzi skills for local AI assistants.

Skills are installed once into ~/.suzi/skills and then symlinked into supported local clients.

Subcommand	Description
(default)	List available skills.
`show <name>`	Show a skill and optionally print full file contents.
`add [name]`	Install one skill or `--all` skills into the shared store and link clients.
`sync`	Force-refresh the skill registry, update the shared store, and relink all clients.

suzi skills
suzi skills add suzi-guide
suzi skills add --all
suzi skills sync

`suzi install-hooks`

Installs Claude Code hooks for automatic Suzi context injection.

Flag	Description
`--preferences`	Also create a starter `~/.suzi/preferences.md`.

suzi install-hooks

`suzi init`

Generates a project-level SUZI.md file in the current working directory.

suzi init

username
api-url

suzi preferences set username alice
suzi preferences set api-url http://localhost:3001

`suzi preferences telegram`

Generates a Telegram connection link. In non-interactive mode, the CLI prints the URL without prompting to open a browser.

suzi preferences telegram

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

`suzi update`

Checks npm for the latest CLI version and can optionally install it.

Flag	Description
`--check`	Check only.
`-y, --yes`	Update immediately without a prompt.
`--manager <manager>`	Choose `npm`, `pnpm`, `yarn`, or `bun`.
`--no-prompt`	Print the update command but do not run it.

suzi update --check
suzi update -y

`suzi feedback`

Sends feedback directly to the Suzi team and includes recent CLI history for context.

In non-interactive mode, both of these are required:

--category <bug|feature|general>
--message <message>

suzi feedback --category bug --message "run --params validation should show the offending field"

Changelog

Current Release

suzi run is the direct action-execution surface, with action-specific --help, schema-aware validation, --params, and --dry-run
top-level discovery is machine-friendly through suzi --help --json and per-command --json --no-input
suzi list-actions and suzi list-triggers support positional protocol shorthands
skills install into ~/.suzi/skills and are linked into supported local AI clients
the default suzi screen is organized around quick-start, portfolio, discovery, debugging, and settings

For exact behavior, trust the live CLI output:

suzi --help
suzi --help --json
suzi <command> --help

On this page