The rystic CLI

Installation is the walkthrough. CLI flag reference lists every command and flag, generated from command help. Docker covers running without a local CLI: image defaults, Compose overrides and environment variables.

Install

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…                        # an API key from /account/api-keys (+ docker login)
rystic login --token-stdin < key.txt      # the same, kept out of shell history
rystic login ./rystic-license.json        # Enterprise: activate a license file (+ docker login)

1. The CLI is the downloader, not the product — anyone can install it. Simulator binaries and images need an API key or, on Enterprise, a license.
2. macOS and Linux; Windows zip on request. RYSTIC_BIN overrides where it lands.
3. login rys_… stores the key at $RYSTIC_HOME/token, readable by you only, and never prints it. login <file> verifies a license offline and parks it in $RYSTIC_HOME. Either runs docker login registry.rystic.ai when a runtime answers; --no-docker skips that half. Plans and API keys covers both.
4. After a license login, on a terminal and with $CI unset, login offers a numbered menu of simulators to start, each exactly as rystic run <product> -d --scenario <its quickstart scenario>; a busy port retries once on a free one. --no-start skips the offer, and so does any non-terminal or CI run.

Commands

rystic help <command> prints a command’s flags on stdout. An older CLI prints them on stderr; rystic help <command> 2>&1 works on either.

--json prints {schema_version, command, status, data, warnings, error}. Only run, ps, restart, up, status, list, version, config, report, docs and scenario save take it; the rest refuse it (exit 2).

Simulator-specific commands

These only apply to a simulator whose manifest declares the feature — today the Kalshi simulator. rystic features lists what the installed build supports.

run

rystic run stripe-twin                                # serves :8080, streams events
rystic run stripe-twin -d --name a --port 0           # detach on a free port
rystic run stripe-twin --scenario design_studio       # boot into a named scenario
rystic run stripe-twin --seed ./scenario.json         # seed file, applied before the first request
rystic run stripe-twin --runner docker -d             # as a container, from registry.rystic.ai
rystic run stripe-twin -- --events=all                # args after -- go to the simulator

1. CLI flags can appear before or after the product name; anything after -- goes to the simulator.
2. Default port 8080; a busy port is exit 9; --port 0 picks a free one.
3. --runner docker needs a container runtime. The image comes from the registry, or is built locally from a pulled Linux archive when image_source=archive or the registry is unreachable. See Docker.
4. Replay (--tapes, --tape, --copies, --speed) and --live are Kalshi features: Replay, Live mode.
5. On Free and Pro, run hands the simulator your API key and the simulator checks in with Rystic while it serves. -v prints one line per check-in. On Free, --network exits naming the faults feature the plan lacks: Boot inputs.

up, down, export — the stack file

# rystic.yaml — every key is a run flag; the service name is the instance name
version: 1
project: demo
services:
  payments: {product: stripe-twin, port: 0, scenario: design_studio}
  reviews:  {product: github-pulls-twin, port: 0, seed: ./seeds/repo.json}
  exchange: {product: kalshi-twin, runner: docker, port: 0, scenario: thin_book}

File paths are relative to the stack file. On Free, a service may set no network. Kalshi-only keys (tapes, tape, copies, live and the live_* family) are listed on the Kalshi page. The Docker builder writes this file for you.

rystic up -d                       # one identity line per service
rystic ps --project demo
rystic down
rystic export compose -o ./deploy  # digest-pinned compose + .env.example
rystic export antithesis -o ./anti --tenant <t> --gcp-project <p>

A stack file never carries a key or license. A malformed one is refused naming the file, service and key. export warns when a tape: cannot be expressed in Compose.

ps, stop, logs, status, tail

rystic ps                    # NAME PRODUCT VERSION RUNNER URL MODEL LICENSEE UPTIME STATUS
rystic stop a b              # or --all
rystic logs -f a
rystic status                # --offline skips the network

status prints the registry line — registry.rystic.ai · logged in · reachable. A token: line shows the API key masked (rys_AAAA…), where it came from, and the organization and plan the site reports; --offline prints not checked instead. A license file adds a license: line. With neither, it prints credential: none and the rystic login line to run. --json carries both as token and license, never the key itself.

rystic tail -addr http://localhost:53124            # a detached instance on another port
rystic tail -events all                             # public market data too

tail reads the simulator’s GET /_rystic/events stream. -addr defaults to http://localhost:8080.

doctor

rystic doctor stripe-twin

The pre-demo check, no boot: the CLI and its home, configuration, the install, signing-key agreement, simulator data, container runtime, registry login — and, for a simulator with a live feed, the exchange key and where it came from. Exits 0 when no line shows ✗.

doctor checks the credential the installed build runs on. On an API key:

✓ api key                rys_AAAA… · from /Users/you/.rystic/token · org <org> · <plan> plan · www.rystic.ai answered

✗ api key plan means the plan does not include that product; a refused key is ✗ api key with the exit-11 sentence, and doctor exits 11. If the site does not answer, the line is a ! warning and the simulator checks the key when it starts. With a license file, doctor checks the license instead and reports any stored key as api key (not in use), a warning at most. rystic check <product> boots the installed build once to prove it.

docs

rystic docs                          # numbered index: the site's pages, then each installed simulator's HOWTO and SCENARIOS
rystic docs agent-quick-start        # one page as Markdown
rystic docs cli#exit-codes           # one section
rystic docs stripe-twin              # the installed HOWTO.md, plus the live routes of each running instance
rystic docs kalshi-twin scenarios    # the installed SCENARIOS.md
rystic docs search rate limit        # every section holding all the terms, as <topic>#<anchor>
rystic docs -online cli              # read the live site instead of the built-in snapshot

The site’s pages are a snapshot built into the CLI when it was released, so rystic docs works offline and needs no key; a page added since needs -online. A product’s short name works too (rystic docs stripe); with nothing installed it falls back to the site’s page for that simulator. -json prints the envelope, -n caps search results. An unknown topic, section or SCENARIOS.md exits 5 and says what to try instead. Stripe ships no SCENARIOS.md.

list, pull, update

rystic list                                # PRODUCT LATEST INSTALLED RUNNING SUMMARY (on an API key or a license file)
rystic pull -version <x.y.z> stripe-twin   # omit for latest
rystic update                              # the CLI and every installed simulator
rystic update -check                       # report only; exit 10 if newer ones exist

pull installs into $RYSTIC_HOME/twins/<product>/<version>, checksum-verified, marked current. -os linux -arch amd64 fetches another platform’s build (the air-gap Docker path).

config

rystic config                       # every setting, its value and where it came from
rystic config set runner docker     # flag > env > config.json > built-in

config set token is refused: edit config.json or use rystic login.

Files and environment

Everything lives under $RYSTIC_HOME (default ~/.rystic): installed simulators, the current marker per product, token (the API key login stored) or the active license, config.json (once you config set something), and run/ — one record per instance.

RYSTIC_TOKEN, RYSTIC_LEASE_URL, RYSTIC_REGISTER_WAIT, RYSTIC_LEASE_CACHE and RYSTIC_LEASE_VERBOSE reach the simulator, including a --runner docker container, when they are set.

The simulator binary also reads these variables. With the default image command, rystic run inherits them or sets them from the corresponding CLI flags:

Control plane and plans lists every simulator variable, its default and which ones a plan gates.

Kalshi-only variables — RYSTIC_LIVE*, KALSHI_KEY_ID, KALSHI_PRIVATE_KEY_*, KALSHI_CAPTURE_DIR — are on the Kalshi page.

Exit codes

Stable — script against them.

A simulator stopped by its lease (monthly limit, spend cap, revoked key) exits 1 with the reason on stderr, and a foreground run hands that back.

Next

1. Docker — pull, compose, CI.
2. Simulators — one page per API: Anthropic, Clerk, Dropbox, GitHub, Gmail, Google Drive, Kalshi, Linear, Lob, Notion, Okta, PayPal, Resend, S3, Shopify Storefront, Slack, Stripe and Word.
3. Control plane and plans — every /_rystic route and the plan that serves it.

What leaves your machine

On Free and Pro, the simulator checks in with https://lease.rystic.ai while it runs: at start, every 30 seconds, and on exit, carrying your API key and the 30-second windows in which it was in use. Never your requests, their contents, your data or your hostname. Plans and API keys lists every field. An Enterprise simulator makes no outbound calls. (One exception, Enterprise included: the Kalshi simulator’s replayed-market metadata fetch, documented on its page.)

The CLI itself calls Rystic only in these cases:

rystic docs without -online, ps, logs, stop, features, config and help stay on the machine.

A live feed adds the source API itself: the CLI dials it from your machine — see Kalshi → Live mode.