@upstash/box-cli

REPL-first CLI for Upstash Box — create and interact with sandboxed AI coding agents from the terminal.

Installation

npm install -g @upstash/box-cli

Or run directly from the monorepo:

pnpm build
node packages/cli/dist/index.js --help

Authentication

Provide your Upstash Box API token via the --token flag or the UPSTASH_BOX_API_KEY environment variable:

export UPSTASH_BOX_API_KEY=box_...

Direct SSH

Boxes can also be reached directly over SSH:

ssh <box-id>@us-east-1.box.upstash.com

Use your Box API key as the SSH password.

Commands

box create

Create a new box and enter an interactive REPL.

# Uses Upstash-managed key by default (no --agent-api-key needed)
box create --agent-harness claude-code --agent-model anthropic/claude-sonnet-4-5

# Use a key stored in the Upstash console
box create --agent-harness claude-code --agent-model anthropic/claude-sonnet-4-5 --agent-api-key stored

# Pass a direct API key
box create \
  --agent-harness claude-code \
  --agent-model anthropic/claude-sonnet-4-5 \
  --agent-api-key $CLAUDE_KEY \
  --runtime node \
  --git-token $GITHUB_TOKEN \
  --git-user-name "John Doe" \
  --git-user-email "[email protected]" \
  --env NODE_ENV=production \
  --env DEBUG=true

| Flag | Description | Default | | ------------------ | ------------------------------------------------------------------------------------------- | ----------------------------- | | --token | Upstash Box API token | | | --runtime | Runtime environment (node, python, golang, ruby, rust) | | | --agent-model | Agent model identifier | | | --agent-harness | Agent harness (claude-code, codex, opencode) | required with --agent-model | | --agent-provider | Deprecated alias for --agent-harness | | | --agent-runner | Deprecated alias for --agent-harness | | | --agent-api-key | Agent API key — omit for Upstash-managed key, stored for a saved key, or a direct API key | Upstash | | --git-token | GitHub personal access token | | | --git-user-name | Git user.name set globally in the box container | Upstash Box | | --git-user-email | Git user.email set globally in the box container | [email protected] | | --env KEY=VAL | Environment variable (repeatable) | |

box connect [box-id]

Connect to an existing box and enter the REPL. If no box ID is given, connects to the most recent box.

box connect box_abc123
box connect  # connects to most recent

box from-snapshot <snapshot-id>

Create a new box from a snapshot and enter the REPL. Accepts the same flags as create.

box from-snapshot snap_abc123 --agent-model anthropic/claude-sonnet-4-5 --agent-harness claude-code
box from-snapshot snap_abc123 --agent-model anthropic/claude-sonnet-4-5 --agent-harness claude-code --agent-api-key $CLAUDE_KEY

box list

List all boxes.

box list

box get <box-id>

Print box details as JSON.

box get box_abc123

box init-demo

Scaffold a standalone demo project that uses the @upstash/box SDK. Creates a directory with a ready-to-run TypeScript script, .env file, and README.

box init-demo \
  --token $UPSTASH_BOX_API_KEY \
  --agent-harness claude-code \
  --agent-model anthropic/claude-sonnet-4-5 \
  --runtime node \
  --git-token $GITHUB_TOKEN \
  --directory my-demo

| Flag | Description | Default | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------- | | --token | Upstash Box API token | | | --agent-harness | Agent harness (claude-code, codex, opencode) | required with --agent-model | | --agent-model | Agent model identifier | | | --agent-api-key | Agent API key — omit for Upstash-managed key, stored for a saved key, or a direct API key | Upstash | | --runtime | Runtime environment | node | | --git-token | GitHub personal access token | | | --directory | Output directory | box-demo |

After scaffolding, the command offers to run the demo immediately. The generated project includes:

• main.ts — demo script that creates a box, writes/reads files, executes commands, and cleans up
• .env — pre-filled environment variables
• README.md — usage documentation

Interactive REPL

After create, connect, or from-snapshot, you enter an interactive REPL session:

Connected to box box_abc123
Type a prompt to run the agent, or use commands: run, exec, files, git, snapshot, pause, delete, exit

box_abc123> Fix the bug in auth.ts

REPL commands

Any text entered is sent to the agent by default. You can also use explicit commands (with or without a / prefix):

| Command | Description | | ------------------------------ | ---------------------------------------------- | | run <prompt> | Run the agent with a prompt (streaming output) | | exec <command> | Execute a shell command in the box | | files read <path> | Read a file | | files write <path> <content> | Write a file | | files list [path] | List files in a directory | | files upload <local> <dest> | Upload a local file | | files download [path] | Download files from the box | | git clone <repo> [branch] | Clone a repository | | git diff | Show git diff | | git create-pr <title> | Create a pull request | | snapshot [name] | Save a snapshot of the current state | | model | Change the agent model (interactive picker) | | model <provider> <model> | Change the agent model directly | | pause | Pause the box and exit | | delete | Delete the box and exit | | exit | Exit the REPL (box keeps running) |

Examples

box_abc123> Add error handling to the payment service
box_abc123> exec npm test
box_abc123> files list src/
box_abc123> git diff
box_abc123> snapshot before-refactor
box_abc123> exit

License

MIT