Skip to main content
Full reference for every miramarket-cli command. For installation and a first walkthrough, see CLI. For the strategy JSON format and correctness rules, see /agent-strategy-guide.md. Every command supports --json for machine-readable output. In --json mode, stdout carries exactly one JSON object and nothing else — no banners, color, or spinner frames — except strategies watch --events, noted below. Piping to a non-TTY also disables color and spinners automatically.

Envelope and exit codes

Every command that supports --json emits the same envelope shape on both success and failure:
On failure, ok is false and the envelope also carries a human-readable error and a machine-readable code:
Prefer branching on code over parsing error text — error wording can change, code is the stable contract. code values include NOT_AUTHENTICATED, VALIDATION_ERROR, INPUT_ERROR, SERVER_ERROR, PARSE_ERROR, STRATEGY_NOT_FOUND, REGION_RESTRICTED, WALLET_NOT_DELEGATED, WATCH_TIMEOUT, INVALID_STRATEGY_STATE, NO_ACTIVE_RUN, LOCKED_NODE_EDIT, UNSUPPORTED_FIELD, RUN_EDIT_REJECTED, and more — this set grows over time, so don’t treat it as closed.

Sign-in commands

miramarket-cli login [--force]

Authenticates via an OAuth device flow: prints a short code and a verification link, you approve it in any browser (doesn’t need to be the same device — useful over SSH or on a headless machine), and the CLI finishes automatically once approved. A valid cached session short-circuits this by default; pass --force to sign in again (for example, to switch accounts). Signing in starts a session but does not by itself make the account trade-ready — see account setup under Account commands below.

miramarket-cli logout

Clears the cached session on this machine.

miramarket-cli auth status [--json]

Reports whether a valid session is cached. Always exits 0 — this is a diagnostic, read the payload:

Account commands

A signed-in session is not the same as a trade-ready account — Polymarket orders and live strategy runs also require accepting the platform’s Terms/Privacy/Risk Disclosure and having a delegated deposit wallet with the necessary on-chain approvals.

miramarket-cli account status [--json]

Diagnoses trade-readiness across auth, API reachability, region availability, policy acceptance, wallet delegation, and capital. Always exits 0 — ok:true means “the check ran,” not “everything passed.” Read ready and blockers[]:
If humanRequired is true on a blocker (not authenticated, wallet not delegated, policies not accepted, region-restricted), surface requiredAction and stop — an agent should never attempt to work around these. Blocker codes: NOT_AUTHENTICATED, API_UNREACHABLE, REGION_RESTRICTED, POLICIES_NOT_ACCEPTED, WALLET_NOT_DELEGATED, WALLET_CHECK_FAILED.

miramarket-cli account setup [--json]

Idempotent — attaches the wallet-level policy and bootstraps the deposit wallet’s on-chain approvals; safe to re-run any time. Cannot complete onboarding by itself: wallet delegation only happens in a browser during sign-in, and this command never accepts policies on your behalf. It reports exactly what’s still needed and points at account accept-policies or a browser sign-in.

miramarket-cli account policies [--json]

Read-only. Shows the current Terms/Privacy/Risk Disclosure versions, your acceptance status, and canonical URLs.

miramarket-cli account accept-policies

Records legal acceptance of the current Terms, Privacy Policy, and Risk Disclosure. This is a human-only action — it requires typing I accept in an interactive terminal (or, for a human scripting their own machine, pinning the exact current document versions with --i-have-read-and-accept --terms-version=... --privacy-version=... --risk-version=...). An AI agent should never call this on a user’s behalf.

miramarket-cli account capital [--json]

Shows capital currently locked by active strategy runs and pending withdrawal holds — the gap between gross wallet balance and what’s actually spendable.

miramarket-cli account withdraw --recipient <address> [--amount <usd>] --confirm [--json]

Withdraws spendable USDC to an external address. Omit --amount to withdraw all spendable cash. Requesting more than spendable cash is rejected before anything is moved.
Exit codes: 0 ok, 3 auth error, 4 server error (a failed transfer releases its hold automatically), 5 bad input.

Strategy authoring commands

See /agent-strategy-guide.md for the JSON format itself and the rules for building a strategy that behaves correctly, not just one that passes validate.

miramarket-cli schema [--format=ts|json|markdown]

Prints the strategy schema — ts for TypeScript types, json for a JSON Schema document, markdown for a prose authoring guide with worked examples.

miramarket-cli strategies generate [prompt] [flags]

Text-to-strategy. Describe what the strategy should do in plain English and get authoring JSON back, built by the same assistant that powers the visual builder. Requires authentication. Nothing is validated or posted on your behalf: run validate, preview, and post on the result exactly as you would for a hand-written file. result is one of four values. ok is true for all of them, because each is a real outcome rather than a failure:
  • strategy — built. strategyPath or strategy, plus markets[] (what it trades, with the price the generator saw), stats, notices[], unmatched[], changeSummary[] (edits only), and nextCommands[]. A non-empty unmatched means something the prompt named was substituted or left out; read it before posting. A tokenized stock comes back as a BASE_STOCKS leg with PRICE_USD conditions in dollars, ready to post.
  • market_selection — the request was ambiguous between several markets. candidates[] is numbered (choice) and the question is saved locally under selectionId. When resumable is true, answer with strategies generate --choose <marketId|choice> --selection <selectionId> on the next call; at an interactive terminal the choice is prompted for in place instead. When resumable is false the question cannot be answered with a choice (the request was an edit, or it named several markets) and reason says so; re-run with a prompt that names the market precisely. Any new prompt discards the saved question.
  • clarification — nothing was built; question says what is missing. Re-run with a prompt that answers it.
  • answer — the prompt was a question rather than a build request; answer is the reply.
Exit codes: 0 for every result, 3 auth error, 4 generation failed, 5 bad input (code says which).

miramarket-cli validate <file> [--json]

Validates a strategy JSON file’s structure. Exit 0 valid, 2 validation errors, 5 bad input (missing file, malformed JSON).

miramarket-cli preview <file> [--json]

Summarizes a strategy without contacting the server — node/edge counts, required principal, and warnings[] for anything that will be silently dropped or misbehave at import.

miramarket-cli edit <file> [flags]

Updates fields in a local strategy JSON file. Edits apply in memory and the result is fully re-validated before writing — if validation fails, the source file is left untouched and the output reports the errors. edit never contacts the server; to change a strategy you have already posted, use strategies pull and strategies update.

miramarket-cli post <file> [flags]

Validates and posts a strategy, then starts a run (unless --no-start). A live (non-demo) post runs a Polymarket market-health check first; demo posts skip it.
Exit codes: 0 ok, 2 validation error, 3 auth error, 4 server error, 5 bad input.

Market data commands

None of these require authentication.

Tokenized stock commands

Tokenized stocks on Base (AAPLc, TSLAc, NVDAc, and others) are real equities wrapped as tokens. They are not prediction markets: a strategy buys and sells them as token swaps, and a condition watches them by share price in dollars. markets search never finds them, so these commands exist instead. None require authentication.
Two prices appear, and they mean different things. priceUsd is the pool price, what a swap actually pays, and what a position is sized from. oraclePriceUsd is the reference price of the underlying share, what a PRICE_USD condition watches; the gap between them is poolPremiumBps. Both are dollars per share, never a 0–1 probability. A large oracleAgeSeconds outside US market hours is expected, not a fault.
stocks history charts the pool price (priceSource names it), not the reference price. stale: true means fresh history was unavailable and the last good reading was returned. stocks show and stocks history exit 5 for a company that is not in the registry, and, distinctly, for one that is listed but has no pool to trade in yet (COINc, CRCLc, INTCc). portfolio reports stock holdings separately from cash (stockPositions, stockValueUsd), because a share has to be sold before a strategy can spend the proceeds. Tokenized stocks are geo-restricted: where they are not offered, posting a live strategy that buys one is refused with “Tokenized stocks are not available in your region”. account status --json shows the region check under checks.geo.

Trading and portfolio commands

miramarket-cli trade [flags]

Places a CLOB limit order directly — for manual/tactical orders, not strategy automation (use post under Strategy authoring commands for that). Requires authentication and --confirm.
Exit codes: 0 ok, 3 auth error, 4 server error, 5 bad input.

Strategy management commands

strategies watch <strategyId> [flags]

Editing a running strategy

strategies pull and strategies update round-trip a strategy that is already running. Only the future part of the graph can change: nodes the run has executed or is waiting on are locked, and so are root_node_id and initial_principal_usd. Drafts and finished strategies cannot be edited in place — post a new strategy instead.

strategies pull <strategyId> [--out <file>] [--json]

Writes the strategy as authoring JSON (embedded in the envelope, or to --out) and reports which nodes you may touch: Nodes keep their node_id across the round trip, so nodes[i] positions from pull are stable for --set.

strategies update <strategyId> [file] [--set <path>=<value>] [--unset <path>] [--json]

Uploads either a file (usually one written by pull --out) or the posted graph with dot-path edits applied directly, then saves it. Before anything is sent, the CLI checks the locks and validates the result; the server repeats the checks and additionally rejects edges rewired into the executed past. An ABSOLUTE_TIME condition whose trigger time has already passed is accepted only if you leave it, its decision group, and the actions it gates exactly as pulled; change anything it gates and you must also give it a future time.

Bridging commands

Move USDC between Base and Polygon, or swap Polygon USDC to USDC.e, before trading. All require authentication (the wallet address is resolved from your session). --direction is one of base-to-polygon, polygon-to-base, polygon-usdc-to-usdce, polygon-usdce-to-usdc. The last two are same-chain swaps on Polygon, which have no bridge to poll. By default bridge execute waits: ok: true means a cross-chain transfer filled, or a same-chain swap confirmed on-chain. It exits 4 in three cases, and none of them is a reason to run bridge execute again, because the transaction is already on-chain and a retry would move the funds a second time:
  • BRIDGE_FAILED: the cross-chain bridge failed. The envelope says whether the funds were refunded on the origin chain.
  • BRIDGE_PENDING: the cross-chain transfer is still in flight after the polling window. Poll it with bridge status <txHash> --chain-id <chainId> using the values in the envelope.
  • SWAP_UNCONFIRMED: a same-chain swap on Polygon was submitted but not confirmed within the wait window. There is no bridge to poll. Look up the txHash from the envelope on a Polygon block explorer, or run balance --chain polygon until the USDC and USDC.e balances reflect the swap.
A strategy funds itself. Posting one that needs USDC on the other chain bridges on demand, so a manual bridge is only for moving funds ahead of time or for withdrawing.

miramarket-cli status

Shows local CLI state: auth, last strategy worked on, last post result, remaining required actions.

Environment variables

Session lifetime

The cached access token lasts 15 minutes, but the CLI also caches a 30-day refresh token (rotated on every use) and silently redeems it at the start of every command — there’s no re-login to babysit, on a laptop or an unattended server alike. If the refresh token itself expires or is revoked, the next command reports NOT_AUTHENTICATED and you run miramarket-cli login again.