--- title: Command reference description: Every OpenSwap command, flag, output mode, exit code, and environment variable, explained in plain English on one page. order: 2 version: 0.1.0 --- # Command reference Every OpenSwap command on one page. If you're new, start with the [Quickstart](https://leokit.dev/cli/docs/quickstart) — this page is for looking things up. A note on examples: placeholders are written in angle brackets, like `` or `
`. Replace them with real values — never paste a placeholder into a command that moves money. ## How output works OpenSwap adapts its output to where it's running. In a normal terminal you get the interactive experience. Piped into another program, it switches to clean, stable text automatically. For scripts and bots there are explicit modes: | Flag | What you get | | --- | --- | | *(nothing, in a terminal)* | Interactive mode with prompts | | *(nothing, piped)* | Plain text, tab-separated, no prompts ever | | `--plain` | The same stable plain text, explicitly | | `--json` | Exactly one JSON result object on stdout | | `--jsonl` | One JSON object per line (for streaming commands) | | `--no-input` | Never prompt; missing input becomes an error | | `--no-color` | No colors (the `NO_COLOR` env var works too) | The JSON result always has the same shape: `{schema_version, command, ok, data | error, warnings, meta}`. Errors include a machine-readable `code`, a human `message`, whether the problem is `retryable`, an honest `funds_may_have_moved` flag, and `actions` — safe next commands to run. ## Exit codes These are frozen — you can script against them and they will not change: `0` success · `1` internal error · `2` bad usage · `3` auth/config problem · `4` no route found or policy said no · `5` temporary upstream problem (retry) · `6` signer problem · `7` broadcast problem · `130` you pressed Ctrl-C. ## Everyday commands ### `openswap` Run with nothing else, it opens the menu: pick a pair, watch routes stream in, trade. ### `openswap quote -a -f -t ` Compare prices across every route. Read-only and free — no wallet involved. Routes are sorted by what you'd actually receive, and fees are shown honestly: if a provider doesn't price a fee, it says *not priced* instead of pretending it's zero. Useful extras: `--slippage-bps ` to set your slippage tolerance, `--refresh` to refetch the asset list. ### `openswap swap -a -f -t ` The full swap, start to finish: compare routes, lock one, get a deposit address and QR, pay from any wallet, and track to delivery. In scripts, you must be explicit: `--to-address`, `--refund-address`, and `--yes` are all required, because creating a deposit address is a real action. `--dry-run` rehearses everything without creating anything. `--protocol ` preselects a route. ### `openswap status [id] [--watch]` and `openswap resume [id]` Check on a swap, or watch it live until it finishes. With no id, they use your latest swap. A swap ends as `success`, `failed`, `refunded`, or — if a deposit was never paid — `deposit_expired`. ### `openswap history` Every swap you've made from this machine, newest first. Pick one to see full details and live tracking. ### `openswap assets list` and `openswap assets search ` Browse or search the 7,000+ supported assets. `--chain ` filters to one chain; results are cached for a day. ### `openswap balances
--chains A,B,C` Check what an address holds across several chains at once. ## Keys and configuration ### `openswap auth login | status | logout` Store your own API key in the operating system's keychain, see which key is active, or remove it. The key is typed in privately — never passed as a flag, never written to a file. For CI, set `OPENSWAP_API_KEY` instead. See [Keys, fees & founding keys](https://leokit.dev/cli/docs/keys-and-fees). ### `openswap config list | get | set` Non-secret settings only. Anything that looks like a secret is refused — secrets belong in the keychain or environment. ### `openswap doctor` A health check: runtime, terminal capabilities, credential validity, API reachability, and storage. Run it first when something seems off. ## Practice and automation ### `openswap tour` A guided two-minute walkthrough with real prices and a simulated payment. Nothing is saved and nothing real can move. ### `openswap test …` The sandbox. `on`/`off` toggles it, `pay` simulates paying a deposit, `fund` sets a pretend balance, `scenario` picks a default outcome, `reset` starts a fresh simulated world. Full guide: [Test mode](https://leokit.dev/cli/docs/test-mode). ### `openswap watch -a -f -t --jsonl` A live price feed: quotes stream continuously as JSON lines. Built for bots. `--once` exits after the first full round. ### `openswap bot init | check | run` Policy-gated automation: `init` builds your policy file interactively, `check` tests a trade against it with zero side effects, `run` executes (simulating first by default). Full guide: [Bots & automation](https://leokit.dev/cli/docs/bots). ### `openswap wallet setup | status` The optional signing wallet, used only for routes that can't work with a deposit address. Setup recommends creating a fresh dedicated wallet rather than importing your main one. ### `openswap agent setup | status | docs` For AI agents: `setup` installs the Claude Code skill, `docs` prints the complete machine contract. See [For AI agents](https://leokit.dev/cli/docs/agents). ### `openswap receipts list | show | export ` The raw receipt store — durable local records of every swap. `export` prints a receipt as JSON, handy for support. See [Receipts & data on disk](https://leokit.dev/cli/docs/receipts). ### `openswap feedback` Send a bug or idea straight to the team. It shows you exactly what diagnostic info would be included and asks before sending anything. ## Environment variables | Variable | What it does | | --- | --- | | `OPENSWAP_API_KEY` (or `LEOKIT_API_KEY`) | Your API key, for CI and bots. Lookup order: environment → keychain → built-in community key | | `OPENSWAP_TEST_MODE` | `1` forces the sandbox on, `0` forces it off | | `OPENSWAP_TEST_TIMESCALE` | Speeds up simulated swaps (CI and agents) | | `OPENSWAP_TEST_SEED` | Makes simulated outcomes reproducible | | `OPENSWAP_EVM_PRIVATE_KEY` | Bot signer hot key (prefer the keystore) | | `OPENSWAP_EVM_KEYSTORE` + `OPENSWAP_EVM_KEYSTORE_PASSWORD` | Encrypted keystore signer for bots | | `OPENSWAP_EVM_RPC_URL` | Your own RPC endpoint for the signing lane | | `NO_COLOR` | Disables colors everywhere | ## Which platforms work? macOS and Linux are fully supported. On Windows, run it under WSL — the native Windows credential store isn't wired up yet, so use the `OPENSWAP_API_KEY` environment variable there. ## Our compatibility promise Scripts you write today keep working: JSON fields are only ever added, never changed in place; exit codes are frozen; renamed commands get a deprecation window with warnings first.