CLI

twinbay wraps the same API the console uses. Source and per-command reference live in panoratech/twinbay-cli.

The CLI is pre-production. Pin a release in CI rather than tracking latest.

Install

curl -fsSL https://raw.githubusercontent.com/panoratech/twinbay-cli/main/scripts/install.sh | bash

iwr -useb https://raw.githubusercontent.com/panoratech/twinbay-cli/main/scripts/install.ps1 | iex

go install github.com/panoratech/twinbay-cli/cmd/twinbay@latest

Binaries for each platform are on the releases page. Check the install with twinbay version.

Authenticate

The CLI sends an organization API key. Mint one in the console under API keys, or with twinbay api-keys create --name ci.

twinbay auth login     # prompts, then stores the key in your OS keychain
twinbay whoami         # shows each setting and where it came from
twinbay auth logout    # clears stored credentials

Values resolve in this order:

Flags: twinbay --organization-api-key <key> <command>
Environment: CLI_TWINBAY_ORGANIZATION_API_KEY
The OS keychain, written by twinbay auth login or twinbay configure
~/.config/twinbay/config.yaml

macOS Keychain, GNOME Keyring or KWallet, and Windows Credential Locker hold the secret. Without a keychain the CLI falls back to the config file. In CI, set the environment variable from your secret store. twinbay configure sets credentials and global preferences together, and twinbay whoami masks credential values while naming their source as [flag], [env], [keyring], [config] or [unset].

A run, end to end

SANDBOX=$(twinbay sandboxes create \
  --name checkout-tests \
  --twins '[{"twin":"resend"}]' \
  --prompt "one segment with a delivered and a hard-bounce recipient" \
  --jq '.id' | tr -d '"')

TWIN=$(twinbay sandboxes get --sandbox-id "$SANDBOX" --jq '.twins[0].id' | tr -d '"')

# Poll until the twin serves
until [ "$(twinbay sandboxes get --sandbox-id "$SANDBOX" --jq '.twins[0].state')" = '"ready"' ]; do
  sleep 2
done

BASE_URL=$(twinbay sandboxes get --sandbox-id "$SANDBOX" --jq '.twins[0].url' | tr -d '"')
API_KEY=$(twinbay sandboxes twins credential \
  --sandbox-id "$SANDBOX" --sandbox-twin-id "$TWIN" --jq '.api_key' | tr -d '"')

# Your suite reads the base URL and key it should point the provider SDK at
TWIN_BASE_URL=$BASE_URL TWIN_API_KEY=$API_KEY pytest

twinbay sandboxes logs list --sandbox-id "$SANDBOX" --output-format table

Commands

Group	Commands
`twins`	`list`, `get`
`sandboxes`	`list`, `create`, `get`
`sandboxes twins`	`start`, `stop`, `credential`, `advance`
`sandboxes twins records`	`list`, `update`
`sandboxes templates`	`list`, `delete`
`sandboxes logs`	`list`, `get`
`api-keys`	`create`, `list`, `revoke`
`organizations`	`list`, `create`, `ensure-default`, `read-current`, `rename-current`
`users`	`read-me`
Session	`auth login`, `auth logout`, `auth whoami`, `configure`, `whoami`
Local	`explore`, `version`

twinbay explore opens an interactive browser over every command, its description and its flags, and runs the one you pick. Run twinbay <group> <command> --help for flags. Path parameters are flags: --sandbox-id, --sandbox-twin-id, --resource, --external-id. Body fields are flags too, so sandboxes create takes --name, --prompt, --twins, --template and --save-as-template, and sandboxes twins advance takes --at.

Request bodies

Commands that send a body accept three inputs. Individual flags win over --body, which wins over stdin.

twinbay sandboxes create --body '{"name":"nightly","twins":[{"twin":"resend"}]}'
twinbay sandboxes create < sandbox.json
twinbay sandboxes create --body "$(cat sandbox.json)" --name override

--twins takes the JSON array the API takes, so a curated scenario rides along with the slug:

twinbay sandboxes create --name nightly \
  --twins '[{"twin":"resend","scenario_template":"hard-bounce"},{"twin":"linear"}]'

Record bodies go in --body-param, keeping --body free for the whole request:

twinbay sandboxes twins records update \
  --sandbox-id "$SANDBOX" --sandbox-twin-id "$TWIN" \
  --resource emails --external-id 4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
  --body-param '{"last_event":"bounced"}'

Output

--output-format (-o) picks the rendering: pretty (default), json, yaml, table, and toon for Token-Oriented Object Notation, which costs 30 to 60 percent fewer tokens than JSON when a response goes into a prompt.

twinbay sandboxes list --output-format table
twinbay sandboxes logs list --sandbox-id "$SANDBOX" --output-format toon
twinbay sandboxes get --sandbox-id "$SANDBOX" --jq '.twins[] | {twin_slug, state, url}'

--jq (-q) applies a jq expression and always prints JSON, overriding --output-format. Under --all, output streams as it arrives: NDJSON for json, ----separated documents for yaml. Colors follow --color auto|always|never, plus NO_COLOR and FORCE_COLOR.

Inside a coding agent

--agent-mode returns structured errors and defaults the output to TOON. The CLI turns it on by itself when it detects an agent environment such as CLAUDE_CODE or CURSOR_AGENT, so an agent gets compact output without being told; pass --agent-mode=false to opt out. Add --no-interactive to shut off prompting, TUI forms and the explorer auto-launch in any non-tty context. For an agent that speaks MCP, the MCP server is the shorter path: the same operations arrive as tools, and the user signs in rather than passing a key.

Scripting

--dry-run prints the request the CLI would send to stderr and makes no network call. Exit code 0 means success and 1 means failure, with data on stdout and errors on stderr.

twinbay sandboxes create --name nightly --twins '[{"twin":"resend"}]' --dry-run

Also on every command: --debug (-d) for request and response diagnostics on stderr, --include-headers to keep response headers in the output, --header (-H) to add a request header, --timeout 30s, --server-url to point at another deployment, and --usage to print the command schema as KDL.

Shell completion

source <(twinbay completion bash)   # or zsh, fish, powershell

Getting Started

Concepts

Interfaces

Install

Authenticate

A run, end to end

Commands

Request bodies

Output

Inside a coding agent

Scripting

Shell completion

​Install

​Authenticate

​A run, end to end

​Commands

​Request bodies

​Output

​Inside a coding agent

​Scripting

​Shell completion

Install

Authenticate

A run, end to end

Commands

Request bodies

Output

Inside a coding agent

Scripting

Shell completion