Back to agents docs
Quickstart · CLI

@orrery/cli

A small Node CLI that wraps the Orrery x402 surface for shells, agent toolchains, CI jobs, and quick research. JSON-first by default — pipes into jq, fzf, and standard Unix plumbing.

Install

npm install -g @orrery/cli
# or — no install
npx @orrery/cli --help

First three commands

# 1. Probe the live catalog (free, no payment).
orrery health

# 2. Today's brief — pretty-print for humans.
orrery brief --pretty

# 3. Find a market by free text, then drill in.
orrery search "bitcoin" --limit 5
orrery snapshot will-bitcoin-reach-150k-in-2026
orrery why     will-bitcoin-reach-150k-in-2026
orrery risk    will-bitcoin-reach-150k-in-2026

Pipes + jq

Default output is the raw JSON envelope so the CLI plays nice with the standard shell toolchain.

# Top mover slug → why-it-moved → resolution-risk in one shell line.
TOP=$(orrery brief | jq -r '.data.biggest_moves[0].slug')
orrery why  "$TOP" --pretty
orrery risk "$TOP" --pretty

# Just the slugs of crypto markets that moved up ≥5pp in 24h.
orrery movers --category Crypto --direction up --limit 10 \
  | jq -r '.data.movers[] | select(.delta_24h_pp >= 5) | .slug'

# Get a wallet's profile dimensions.
orrery wallet 0x... | jq '.data | {activity_score, performance_confidence, copy_risk_score}'

All commands

18
  • orrery healthfree · inventory + upstream health
  • orrery brief$0.01 · daily brief
  • orrery movers$0.005 · biggest 24h movers
  • orrery snapshot <slug>$0.005 · per-market snapshot
  • orrery why <slug>$0.02 · why did it move
  • orrery risk <slug>$0.01 · resolution risk
  • orrery event <slug>$0.03 · event cluster
  • orrery events$0.005 · events discovery
  • orrery signals$0.01 · live signals feed
  • orrery signals-kind <kind>$0.01 · signals one kind
  • orrery search <query>$0.005 · free-text search
  • orrery whales$0.005 · raw whale feed
  • orrery wallet <0x>$0.02 · wallet score
  • orrery category <slug>$0.02 · category dashboard
  • orrery backtest <kind>$0.02 · backtest verdict
  • orrery share-card <slug>$0.03 · share artefact
  • orrery watchlist-summary$0.05 · composite watchlist
  • orrery portfolio-risk$0.05 · portfolio risk

Configuration

ORRERY_BASE_URL
defaults to https://orrery.me. Override for staging or a self-hosted proxy.
ORRERY_X_PAYMENT
x402 settlement proof. Sent as the X-PAYMENT header on every request. Optional during preview.

Exit codes

Designed for scripting — codes map onto the HTTP status of the underlying x402 call so a CI job can branch on the outcome.

  • 0 — OK (HTTP 2xx)
  • 1 — generic error (network, parse, unknown command)
  • 2 — HTTP 402 — payment required
  • 3 — HTTP 429 — rate-limited
  • 4 — HTTP 404 — not found

Source / next steps

Orrery for AI agents — CLI quickstart | Orrery