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

ENVIRONMENT=$(twinbay environments create \
  --name=checkout-tests \
  --twins='[{"twin":"resend"}]' \
  -o json | jq -r '.id')

TWIN=$(twinbay environments retrieve --environment-id="$ENVIRONMENT" -o json | jq -r '.twins[0].id')

# One request that answers once the twin serves, instead of a polling loop
BASE_URL=$(twinbay environment-twins retrieve \
  --environment-id="$ENVIRONMENT" --environment-twin-id="$TWIN" \
  --wait-for=ready --timeout=180s -o json | jq -r '.url')

API_KEY=$(twinbay environment-twins collect-credential \
  --environment-id="$ENVIRONMENT" --environment-twin-id="$TWIN" -o json | jq -r '.api_key')

# 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 environment-logs list --environment-id="$ENVIRONMENT" --output-format=table

--wait-for=ready holds the answer until the twin serves, for up to two minutes, and answers with whatever state it found if the wait runs out — hence the raised --timeout. Reading a value with -o json | jq -r rather than --jq is what keeps the quotes off it; see Output.

Commands

Every command is twinbay <resource> <operation>, and a read of one object is always retrieve.

Resource	Operations
`twins`	`list`, `retrieve`
`environments`	`list`, `create`, `retrieve`
`environment-twins`	`retrieve`, `start`, `stop`, `collect-credential`, `advance`
`environment-records`	`list`, `update`
`scenarios`	`list`, `create`, `retrieve`, `update`, `delete`
`seeds`	`create`, `list`, `retrieve`, `delete`, `list-suggestions`
`environment-logs`	`list`, `retrieve`
`api-keys`	`create`, `list`, `revoke`
`organizations`	`list`, `create`, `retrieve`, `update`
`users`	`retrieve`
Session	`auth login`, `auth logout`, `auth whoami`, `configure`, `whoami`
Local	`explore`, `version`

twins is the catalogue of twin types; environment-twins is an instance of one inside an environment. seeds create answers before the data exists, so read the seed until it is ready and then pass its id as a twin’s seed when you create an environment. organizations retrieve and organizations update act on the organization your credential acts in, which is the only one it can address. revoke rather than delete for API keys, because a revoked key stays listed: it can still be named in a log, and its token can never be minted again. twinbay explore opens an interactive browser over every command, its description and its flags, and runs the one you pick. Run twinbay <resource> <operation> --help for flags. Path parameters are flags: --environment-id, --environment-twin-id, --resource, --external-id, --scenario-id. Body fields are flags too, so environments create takes --name, --twins, --scenario and --save-as-scenario, and environment-twins advance takes --at.

Request bodies

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

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

--twins takes the JSON array the API takes, one entry per provider:

twinbay environments create --name=nightly \
  --twins='[{"twin":"resend"},{"twin":"linear"}]'

Save a scenario without provisioning an environment, then start a run from it:

SCENARIO=$(twinbay scenarios create --name=checkout \
  --twins='["resend","linear"]' -o json | jq -r '.id')

twinbay environments create --name=nightly --scenario="$SCENARIO"
twinbay scenarios retrieve --scenario-id="$SCENARIO"
twinbay scenarios update --scenario-id="$SCENARIO" --name=checkout-ci

scenarios create requires --name and --twins. scenarios update accepts either or both; --twins replaces the saved list. Entries can be twin slugs or objects with twin and an optional existing seed ID. Scenarios do not accept seed-generation descriptions. Use --save-as-scenario on environments create to save a direct twin selection for reuse. A record’s own fields go in --fields, keeping --body free for the whole request:

twinbay environment-records update \
  --environment-id="$ENVIRONMENT" --environment-twin-id="$TWIN" \
  --resource=emails --external-id=4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
  --fields='{"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 environments list --output-format=table
twinbay environment-logs list --environment-id="$ENVIRONMENT" --output-format=toon
twinbay environments retrieve --environment-id="$ENVIRONMENT" --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. For a machine that should always answer in JSON, set the default once rather than per command — output-format: json in ~/.config/twinbay/config.yaml, or CLI_TWINBAY_OUTPUT_FORMAT=json in CI:

~/.config/twinbay/config.yaml

output-format: json

A flag still wins over it, so -o table reads a listing by eye without editing anything back. Pipe through jq -r rather than --jq to read one value into a shell variable: --jq prints JSON, so a string comes back quoted, while -o json | jq -r '.id' prints the value itself. 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 environments 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

Request a twin

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