Quick Start

npm i -g suzi-cli              # Install globally
suzi login                     # Authenticate via browser
suzi create my-agent --ai claude   # Scaffold an agent with AI assistance
suzi deploy ./my-agent/agent.ts    # Validate and deploy
suzi agents activate <id>      # Go live

What You Can Do

• AI-Assisted Agent Creation — scaffold agents with Claude Code or Codex via suzi create --ai
• 100+ Protocol Actions — trade on Polymarket, Hyperliquid, Solana DEXes, and more
• Deploy & Activate in Seconds — validate > deploy > activate pipeline
• Real-Time Portfolio Tracking — balances and positions across chains
• Flexible Triggers — manual, cron, and event-driven execution
• Agent Sharing — shareable links with custom slugs for collaboration
• Built-In Learning — automatic command history, error capture, and context memory

Installation

Prerequisites: Node.js 22+

npm i -g suzi-cli
suzi --version

Authentication

suzi login       # Opens browser for OAuth sign-in
suzi whoami      # Show current user and active account
suzi logout      # Clear stored credentials

Creating Agents

Use suzi create to scaffold an agent directory with AI assistance:

suzi create my-agent --ai claude    # Uses Claude Code
suzi create my-agent --ai codex     # Uses Codex
suzi create my-agent                # Scaffold only, no AI

Agent files must default-export a defineAgent() call. The file is self-contained — no imports allowed (the runtime provides defineAgent, on, resource, config, requirement as globals).

export default defineAgent({
  meta: {
    name: 'My Agent',
    version: '0.1.0',
  },
  triggers: {
    manual: on.suzi.manual(async (ctx, input) => {
      await ctx.actions.suzi.log({ message: 'Hello from my agent!' });
      return { ok: true };
    }),
  },
});

Validate & Deploy

suzi validate ./agent.ts                    # Check for errors without deploying
suzi deploy ./agent.ts                      # Deploy a new agent
suzi deploy ./agent.ts --activate           # Deploy and activate immediately
suzi deploy ./agent.ts --update <agentId>   # Push a new version to an existing agent

If no file is specified, both commands auto-detect agent.ts, src/agent.ts, or index.ts in the current directory.

Managing Agents

suzi agents                     # List all agents
suzi agents view <id>           # View agent details, triggers, and resources
suzi agents activate <id>       # Activate an agent
suzi agents deactivate <id>     # Deactivate an agent
suzi agents execute <id> [trigger]  # Manually fire a trigger
suzi agents logs <id>           # View logs (flags: -n <count>, --level <level>)
suzi agents delete <id>         # Delete an agent (flag: -f to skip confirmation)

Portfolio & Transactions

suzi portfolio                  # Spot balances and open positions across chains
suzi txns                       # Recent transactions (default: 15)
suzi txns -n 30                 # More rows
suzi txns --protocol polymarket # Filter by protocol
suzi txns --agent <id>          # Filter by agent
suzi txns --type order          # Filter by type (order, cancel, transfer, swap, bridge, liquidity)

Discover Actions & Triggers

suzi list-tools                           # Protocols overview
suzi list-tools --verbose                 # All actions per protocol
suzi list-tools --protocol polymarket     # Actions for one protocol
suzi list-tools --protocol polymarket --schema place_order  # JSON schema for an action
suzi list-tools reload                    # Refresh cached action list

suzi list-triggers                        # All triggers
suzi list-triggers --verbose              # With config fields and examples
suzi list-triggers --protocol polymarket  # Triggers for one protocol
suzi list-triggers --protocol polymarket --schema price_move  # Trigger schema

Accounts & Wallets

suzi accounts                # List accounts (interactive switcher)
suzi accounts show           # Show wallet addresses for active account
suzi accounts fund           # Display deposit addresses and QR codes
suzi accounts create <name>  # Create a new account
suzi accounts switch <name>  # Switch active account
suzi accounts rename <name> <newName>  # Rename an account
suzi accounts delete <name>  # Delete an account (flag: -f)

Environment Variables

Set secrets and config that your agents can read at runtime:

suzi env                     # Interactive menu
suzi env list                # List variable names (flag: -a <agentId> for agent-scoped)
suzi env set <KEY>           # Set a variable (prompts for value, masked input)
suzi env set <KEY> --agent <id>  # Scope to a specific agent
suzi env remove <KEY>        # Remove a variable

Key naming rules: must start with an uppercase letter, allowed characters A-Z, 0-9, _ (e.g. POLYMARKET_API_KEY).

Agent Sharing

suzi share create [agentId]               # Create a shareable link
suzi share create [agentId] -s my-slug    # With a custom slug
suzi share list                           # List your shared agents
suzi share update <agentId> --slug <slug> # Publish a new version
suzi share revoke <snapshotId>            # Revoke a shared snapshot

suzi import <slug>                        # Clone a shared agent into your account

Memory & Learning

Suzi automatically captures command history, errors, and context to improve your workflow:

suzi memory                  # Summary of stored memory
suzi memory learnings        # View recent learnings (flag: -n <count>)
suzi memory log [date]       # Daily activity log (default: today)
suzi memory context          # View active context
suzi memory export           # Export all memory to stdout
suzi memory edit             # Open learnings in $EDITOR
suzi memory clear            # Clear all learnings (flag: -f)

All Commands

| Command | Description | |---------|-------------| | login | Sign in via browser (OAuth) | | logout | Sign out and clear credentials | | whoami | Show current user and account | | create [dir] | Scaffold agent with AI assistance | | validate [file] | Validate agent file | | deploy [file] | Deploy agent to platform | | agents | List and manage agents | | portfolio | View balances and positions | | txns | Transaction history | | tx-confirm <agentId> | Transaction confirmation details | | list-tools | Browse protocols and actions | | list-triggers | Browse available triggers | | accounts | Manage accounts and wallets | | env | Manage environment variables | | share | Share and publish agents | | import <slug> | Clone a shared agent | | preferences | View and manage settings | | skills | Install Suzi skills for local AI assistants | | subagents | Manage agent.md templates | | memory | View learnings and activity logs | | suggest | Interactive command suggestions | | init | Generate SUZI.md project config | | install-hooks | Install Claude Code hooks | | feedback | Send feedback to the Suzi team |

Use With AI Assistants

Suzi is designed to work with Claude Code, Codex, and Agents-compatible skill directories. Inside your agent directory:

Build a Suzi trading agent that:
- monitors Polymarket markets for price moves
- places limit orders when confidence > 70%
- uses a manual trigger to start
- logs every decision
- no imports in agent.ts

Then validate and deploy:

suzi validate ./agent.ts && suzi deploy ./agent.ts --activate

Use suzi skills add --all to install Suzi skills into the default local skill directories:

• ~/.claude/skills
• ~/.codex/skills
• ~/.agents/skills

Development

From the monorepo root:

pnpm -F suzi-cli dev     # Watch mode with tsx
pnpm -F suzi-cli build   # TypeScript compilation
pnpm -F suzi-cli lint    # ESLint check

Troubleshooting

| Problem | Fix | |---------|-----| | Not authenticated | Run suzi login | | Don't know what actions exist | Run suzi list-tools --verbose | | Don't know what triggers exist | Run suzi list-triggers --verbose | | Agent failed | Run suzi agents logs <id> --level error | | Stale action cache | Run suzi list-tools reload |

Source of Truth

This README is a guide. For exact, up-to-date behavior, use CLI output:

suzi --help
suzi <command> --help
suzi list-tools --verbose
suzi list-triggers --verbose

If this README and CLI output differ, trust the CLI.