CLI

Install & Auth

The CLI is usually run with npx. It stores credentials in ~/.an/credentials, or you can pass an API key with the API_KEY_21ST environment variable.

npx @21st-sdk/cli login

# non-interactive
API_KEY_21ST=an_sk_... npx @21st-sdk/cli login --api-key $API_KEY_21ST

Project Layout

The current deploy structure is one agent per folder under agents/. The primary entrypoint is agents/<slug>/index.ts or agents/<slug>/index.js.

agents/
  my-agent/
    index.ts    # or index.js
    template/
      ...

package.json

Use one folder per deployable agent. See Build & Deploy for the full project structure.

Deploy

Deploy scans the agents/ directory, bundles each detected agent, uploads it, and prints a link to the Agents dashboard. Use --agent <slug> to deploy a single agent.

# deploy every agent under agents/
npx @21st-sdk/cli deploy

# deploy only one agent
npx @21st-sdk/cli deploy --agent my-agent

Multi-Environment Deploys

By default, the agent name matches its folder name. Use --name <slug> to deploy the same source code under a different name. Each name creates a separate agent with its own deployments, environment variables, and sandboxes - so you can run staging and production side by side from the same codebase.

# deploy the same source code as a different agent
npx @21st-sdk/cli deploy --agent my-agent --name my-agent-staging

# in CI/CD - deploy to different environments from the same branch
npx @21st-sdk/cli deploy --agent my-agent --name my-agent-dev      # dev
npx @21st-sdk/cli deploy --agent my-agent --name my-agent-staging   # staging
npx @21st-sdk/cli deploy --agent my-agent --name my-agent-prod      # production

This is useful in CI/CD pipelines where you want to deploy different versions from one source - for example, deploying to staging on every push and to production on release. Each environment's env vars are managed independently via an env set <name>.

Environment Variables

Use the CLI to list configured environment variable keys, set one key with the legacy syntax, set one or more keys with KEY=VALUE, or remove a single key for a deployed agent.

# list configured keys
npx @21st-sdk/cli env list my-agent

# set or update one key
npx @21st-sdk/cli env set my-agent OPENAI_API_KEY sk-live-...

# set or update multiple keys
npx @21st-sdk/cli env set my-agent OPENAI_API_KEY=sk-live-... ANTHROPIC_API_KEY=sk-ant-...

# quote values with spaces the usual shell way
npx @21st-sdk/cli env set my-agent SYSTEM_PROMPT="hello world"

# remove one key
npx @21st-sdk/cli env remove my-agent OPENAI_API_KEY

The list command only returns keys, not secret values.

Logs

The CLI can list recent chat sessions, inspect a chat, or fetch one specific thread directly.

# list chats
npx @21st-sdk/cli logs my-agent

# inspect one chat
npx @21st-sdk/cli logs my-agent <chat-id>

# inspect one thread
npx @21st-sdk/cli logs my-agent <chat-id> <thread-id>

# machine-readable output
npx @21st-sdk/cli logs my-agent --json

Filtering & Pagination

The logs list supports status filtering, search, date filtering, and cursor-based pagination.

npx @21st-sdk/cli logs my-agent --status active --limit 20
npx @21st-sdk/cli logs my-agent --status active --limit 20 --cursor <nextCursor>

CLI Environment Variables

What's next