Developer Tools

CLI Reference

View as Markdown

The chaser CLI is a thin client over the public Chaser API.

Installation

Download the latest release from the Chaser dashboard or build from source.

curl -fsSL https://get.chaser.sh | sh installs chaser and the chaser-sh compatibility shim.

The recommended local-first shell surface is chaser dev shell. The shim accepts common shell entry patterns such as -c, -lc, -ic, -ilc, stdin scripts via -s, and local script paths for tools that insist on driving a shell via SHELL, bash, or zsh.

Configuration

Set credentials via environment variables or flags:

$export CHASER_API_URL="https://api.chaser.sh"
$export CHASER_API_KEY="sk_your_key_here"
$export CHASER_ACCOUNT="personal"  # or an organization name

Or pass them as flags:

$chaser --api-url "$CHASER_API_URL" --api-key "$CHASER_API_KEY" --account personal <command>

Commands

Local Project Mode

$# Start project mode from the current repository/directory
$chaser dev
$
$# Explicit shell form
$chaser dev shell
$
$# Inspect current project sync state
$chaser dev status
$
$# Review sandbox-originated edits
$chaser dev log
$
$# Revert the most recent reversible sandbox-originated change
$chaser dev undo
$
$# Run environment checks and runtime diagnostics
$chaser dev doctor
$
$# Force a disposable sandbox instead of the project workspace
$chaser dev shell --ephemeral

chaser dev keeps the local project authoritative and mirrors it into a remote sandbox workspace with sync, conflict capture, and rollback metadata under .chaser/.

Sessions

$# Create sessions
$chaser browser --ephemeral --json
$chaser browser --workspace my-browser --json
$chaser sandbox --ephemeral --json
$chaser sandbox --workspace my-sandbox --json
$chaser sandbox --ephemeral --image ghcr.io/example/dev:latest --json
$
$# Interactive shell
$chaser shell
$chaser shell -c "ls -la"
$chaser shell --ephemeral -c "node -v"
$chaser shell <session_id>
$
$# List and inspect
$chaser sessions list --format table
$chaser sessions list --format json --type sandbox
$chaser sessions info <session_id> --json
$
$# Runtime diagnostic
$chaser sessions self-test <session_id> --json
$
$# Terminate
$chaser sessions terminate <session_id>
$chaser sessions bulk-terminate --all --json

Workspaces

$# Create
$chaser workspaces create --session-type sandbox --name dev --json
$chaser workspaces create --session-type sandbox --name dev --image ghcr.io/example/dev:latest --json
$chaser workspaces create --session-type sandbox --name base --template --json
$chaser workspaces create --clone-from base --name feature --json
$
$# List and manage
$chaser workspaces list --format table
$chaser workspaces label <workspace> new-name
$chaser workspaces label <workspace> --clear
$chaser workspaces template set <workspace>
$chaser workspaces template set <workspace> --disable
$chaser workspaces default show
$chaser workspaces default set dev --sandbox
$chaser workspaces default clear --browser
$
$# Snapshots
$chaser workspaces snapshots create <workspace> --name checkpoint --json
$chaser workspaces snapshots list <workspace> --json
$chaser workspaces snapshots restore <workspace> checkpoint --force --json
$chaser workspaces snapshots delete <workspace> checkpoint --json
$
$# Delete
$chaser workspaces delete <workspace> --force
$chaser workspaces bulk-delete --all --json

File transfer

$chaser upload <session_id> ./local-file /workspace/remote-file
$chaser download <session_id> /workspace/remote-file ./local-file
$chaser teleport <session_id> --local ./my-app --remote /workspace

Use chaser dev instead of manual upload or teleport when you want an ongoing local-first sync relationship with rollback support.

Targetless chaser shell, chaser sandbox, chaser browser, and POST /v1/exec all follow the same resolution rules:

  • Free tier auto-runs ephemerally.
  • Paid accounts use the saved default workspace for the requested session type.
  • If a paid account has no default yet, Chaser creates one automatically on first use.
  • --ephemeral always bypasses defaults.

Port forwarding

$chaser forward <session_id> <guest_port> [local_port] [--open] [--wait <seconds>]

Jobs

$# Execute
$chaser jobs exec --workspace dev "npm test" --wait --json
$chaser jobs exec --ephemeral --image ghcr.io/example/dev:latest "echo hi" --wait --json
$
$# Scrape
$chaser jobs scrape <browser_session_id> --url "https://example.com" --wait --json
$
$# List and inspect
$chaser jobs kinds --json

Accounts

$# List accounts
$chaser accounts list --json
$chaser accounts current --json
$
$# Organizations
$chaser accounts create-org --name "Acme Engineering" --json
$
$# Members (on active organization account)
$chaser --account "Acme Engineering" accounts members list --json
$chaser --account "Acme Engineering" accounts members add --email user@example.com --role admin --json
$chaser --account "Acme Engineering" accounts members update <user_id> --role member --json
$chaser --account "Acme Engineering" accounts members remove <user_id> --json
$
$# Service accounts
$chaser --account "Acme Engineering" accounts service-accounts list --json
$chaser --account "Acme Engineering" accounts service-accounts create --name deploy-bot --json
$chaser --account "Acme Engineering" accounts service-accounts keys create <sa_id> \
>  --name key-name --scope sessions.read --scope exec.write --json
$chaser --account "Acme Engineering" accounts service-accounts keys revoke <sa_id> <key_id> --json

API keys

$chaser keys create --name automation --scope sessions.read --scope exec.write --json

Keys are bound to the account selected at creation time.

Webhooks

$# Create
$chaser --account "Acme Engineering" webhooks create \
>  --url https://example.com/webhooks \
>  --event session.created --event session.terminated --json
$
$# Deliveries
$chaser --account "Acme Engineering" webhooks deliveries list --status failed --json
$chaser --account "Acme Engineering" webhooks deliveries replay <delivery_id> --json
$chaser --account "Acme Engineering" webhooks deliveries discard <delivery_id> --json

SSH

$chaser ssh <session_id> --addr 127.0.0.1:2222 --mode human

Output formats

Most commands support --json for machine-readable output and --format table for human-readable tables. Use --help at any command depth for full syntax.