# CLI Reference

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

## Installation

Download the latest release from the [Chaser dashboard](https://chaser.sh/dashboard) or build from source.

## Configuration

Set credentials via environment variables or flags:

```bash
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:

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

## Commands

### Sessions

```bash
# 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 <session_id>
chaser shell <session_id> -c "ls -la"

# 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

```bash
# 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

# 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

```bash
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
```

### Port forwarding

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

### Jobs

```bash
# 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

```bash
# 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

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

Keys are bound to the account selected at creation time.

### Webhooks

```bash
# 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

```bash
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.