SELAT CLI

The SELAT CLI is the terminal operator surface for SELAT agent payments: bootstrap a wallet, fund a Gateway balance, and discover, rank, and pay x402 services from a terminal or scripted workflow. This guide covers the selat command only; it does not install or configure the Router SDK for application code. It ships as the @selat-ai/selat-cli package, which installs the selat command.

selat is the high-level CLI. Under the hood it shells out to the lower-level @selat-ai/selat-pay payer and the Circle CLI — you install only @selat-ai/selat-cli, and selat init checks for the rest and tells you how to fix anything missing.

When to use it

You want to test a paid endpoint manually.
You want a shell-based flow for operators or CI.
You want an agent-friendly command layer without writing a custom client first.

For a TypeScript application integration, use the separate SELAT Router SDK documentation. Do not combine its package installation or signer setup with this terminal workflow.

Install

npm install -g @selat-ai/selat-cli

Verify the install:

selat --version
selat --help

Prerequisites

selat init checks these for you and tells you how to fix anything missing, but for reference the CLI needs:

Node.js 18 or newer
The Circle CLI (@circle-fin/cli) — wallet creation, MPC-backed signing, and Gateway deposits
The discovery skill (@selat-ai/selat-discovery) — the federated catalog and intent ranking that powers selat search and selat run. Ships as a dependency of the CLI; init verifies it.

Get started

The canonical first-run flow is init → fund → arm a budget → run, with selat search as the free preview of what run would pick.

Bootstrap your setup

selat init is idempotent — safe to re-run. It checks prerequisites, walks you through Circle Agent Wallet login (one email + one OTP), ensures agent wallets exist, and writes your config.

selat init

If you have no spendable USDC, init points you to selat fund.

Fund your Gateway balance

Top up the Gateway balance your payments draw from. fund previews the deposit and requires an explicit confirmation before moving anything ($0.50 minimum deposit). Prefer to buy with a card instead? selat fund --onramp mints a Circle Onramp browser-widget link — no deposit happens on the CLI side.

selat fund --chain base --amount 2

Discover and rank — for free

Describe what you want in plain language. search runs the same discovery and ranking as run, but stops before payment — no wallet, no spend.

selat search "summarize the latest news on gold prices"

Arm a session budget

Paid calls (run, skill run, compare --pay, verify --pay) refuse to execute until a session budget is armed. This is a separate, required gate from the wallet’s own Circle spending policy.

selat budget start --amount 5

Pay for the best match

run discovers matching x402 services, ranks them, and pays for the best one in a single pipe — capped at $1.10 per call by default.

selat run "summarize the latest news on gold prices"

Before depositing more than ~$20, set spending caps with selat setup-policy. If anything looks off, selat doctor diagnoses your setup in one pass. Need to stop everything immediately — misbehaving agent, lost oversight, anything? selat freeze refuses all funding and paid calls from this CLI until you selat unfreeze.

Spending caps

A runaway agent is stopped at four independent scopes — none can be raised by anything running inside an agent session:

Scope	Set by	Ceiling
Per call	Automatic; overridable down via `--max-amount` on `run` / `skill run` / `compare --pay` / `verify --pay`	$1.10 hard cap for everyone. An explicit `--max-amount` can’t raise it, and a TTY doesn’t count as a human gate.
Per session	`selat budget start --amount <usd>` (writes `session.json`)	Paid calls refuse outright without a file-armed budget. `SELAT_SESSION_BUDGET` in the shell env or cwd `.env` cannot arm or invent one — only an already-armed file budget can be lowered that way. `selat budget stop` disarms.
Per day / week / month	`selat setup-policy`	Hard caps on the Agent Wallet itself, enforced by Circle across every service — including ones discovered tomorrow. Every policy write needs a fresh emailed OTP, so an agent can never raise its own limits.
Kill switch	`selat freeze` / `selat unfreeze`	Local and instant: refuses `selat fund` (deposits and `--onramp`) and paid calls from this CLI. Free discovery keeps working. Does not change Circle wallet policy.

Commands

Command	Description
`selat init`	Full bootstrap: skill, Circle auth, Agent Wallet, `selat-pay`, and config. Idempotent.
`selat search "<intent>"`	Discover + rank endpoints for a capability. Free — no wallet, no spend.
`selat run "<intent>"`	Discover + rank + pay for an x402 service in one pipe.
`selat skill <subcommand>`	List, install, run, compare, and author agent skills (see below).
`selat fund`	Top up your Gateway balance. Dry-runs first; requires explicit confirmation. Refused while frozen.
`selat refund claim \| query <quote-id>`	File or check a refund claim for a prior settled quote. Reviewed before anything is issued. Auth, not a payment.
`selat history`	Show locally recorded Gateway micropayments.
`selat spend`	Unified spend report: settled spend + Apify token utilization. Read-only.
`selat budget [--json]`	Show spending caps + remaining budget (read-only). `budget start --amount <usd>` / `budget stop` arm or disarm the required session tripwire.
`selat freeze` / `selat unfreeze`	Local kill switch for fund + pay from this CLI.
`selat setup-policy`	Set Circle spending limits on your Agent Wallet (requires an email OTP).
`selat doctor [--by-chain]`	Diagnose setup problems (skill, PATH, auth, wallet, config).
`selat --help`, `selat --version`	Show help (`-h`) or version (`-v`).

`selat init`

Bootstraps an agent-payment setup in one flow.

Flag	Description
`--force`	Re-create / ensure wallets non-interactively (skips the reuse-or-create prompt).
`--email <address>`	Circle agent account email (skips the login email prompt).
`--wallet <n\|address\|new>`	Select a wallet non-interactively (skips the “wallet to use” prompt): a 1-based list index, a `0x` address, or `new`. Also read from `SELAT_WALLET`. For agent shells / CI with no TTY.
`--router-url=<url>`	Override the router URL for this run (default `https://router.selat.ai`). Must be `https://`.

`selat search "<intent>"`

Runs the free front half of selat run: discovers matching endpoints across the federated catalogs and ranks them for the intent, without touching a wallet. No payment path exists in this command.

Flag	Default	Description
`--top <n>`	`5`	Show the top N matches.
`--capability <name>`	—	Rank only endpoints labeled with this capability (Layer 0). Use when you know the kind of service but not which one — an unknown name or an empty labeled pool is refused, never silently widened.
`--json`	—	Machine-readable output (for agents and interception hooks).
`--explain`	—	Show why each match is or isn’t payable right now.
`--refresh`	—	Re-fetch the catalogs before ranking.
`--verbose`	—	Also show catalog-loader warnings (skipped/invalid entries).

selat search "transcribe audio to text" --top 3
selat search "people enrichment" --json
selat search "find recent papers" --capability web.search

When an installed vetted skill (selat skill list --available) is a strong textual match for the intent, search surfaces it as a separate callout above the federated shortlist — a suggestion, never enforced.

`selat run "<intent>"`

Takes a natural-language intent and runs the discovery skill’s ranking + payment plan against it, paying for the top match. Requires an armed session budget (selat budget start) — see Spending caps.

Flag	Description
`--dry-run`	Show the pick, price, and the exact command without paying.
`--max-amount <usd>`	Per-call spend ceiling. Hard-capped at $1.10 for everyone — `--allow-high-max-amount` and an interactive TTY do not raise it.
`--param key=value`	Fill an endpoint parameter (repeatable): path placeholders, query params, and POST body hints.
`--endpoint <url>` `--method <verb>`	Pin the exact catalog endpoint instead of letting the intent re-rank one — necessary because catalog services are merged across registries and a reworded intent can resolve to a different endpoint at a different price. The URL must already be listed in the catalog; add `--allow-unlisted` only when you’ve confirmed the target yourself.
`--live-probe`	Allow plan-time endpoint/schema probing (may invoke the target’s method/body).
`--input '<json>'`	Inline Actor input, for runs that resolve to an Apify pick.
`--input-file <path>`	Read the Actor input JSON from a file instead.
`--auto-rebuy`	Apify prepaid-token picks only: if the token drains mid-run, buy a replacement (~$1.05) and retry the run. Ignored for other services.
`--capability <name>`	Scope ranking to a labeled capability, same semantics as `search --capability`.
`--json`	Machine-readable output.
`--verbose`	Also show catalog-loader warnings.

selat run "find USDC price news and summarize"
selat run "scrape this page" --input '{"url": "https://example.com"}' --auto-rebuy
selat run "translate this document" --dry-run --json

Unknown flags are a hard error on run, not treated as intent text — this command spends real money, and silently dropping a flag like --dry-run would mean paying when you asked not to.

`selat fund`

Tops up your Gateway balance. Shows the plan locally, then requires you to confirm before depositing. Refused while selat freeze is on.

Flag	Default	Description
`--chain <key>`	`arc` (`base` with `--method eco`)	Source chain: `base`, `optimism`, `arbitrum`, `polygon`, `ethereum`, `avalanche`, `unichain`, or `arc` (direct only — Arc deposits go through the Circle agent wallet, same as every other chain, since Circle CLI ≥1.1.1).
`--amount <usd>`	`2`	USDC amount to deposit. $0.50 minimum — the Circle CLI’s Gateway deposit floor.
`--method <direct\|eco>`	`direct`	Both methods are gasless (the agent wallet’s transactions are gas-sponsored) — the choice is speed and destination. `direct` deposits on the chain you fund from (settles on that same chain, no routing fee) and works from every source chain above. `eco` uses Eco Fast Deposits from Base, Optimism, or Arbitrum only — a ~30-second credit vs the ~5–10-minute direct wait, for a small fixed fee — and always settles into Circle Gateway on Arc regardless of source chain.
`--onramp`	—	Buy USDC with a card instead of transferring it yourself. Mints a Circle Onramp browser-widget session and prints/opens the URL — nothing moves until you complete the purchase there; the CLI never sees your card. This is SELAT’s own onramp, not Circle CLI’s Transak-backed `wallet fund --method fiat`.
`--address <0x>`	configured wallet	Onramp destination wallet. Only valid with `--onramp`.
`--wait`	—	Poll until the deposit is actually spendable (typically 5–10 min).
`--timeout <sec>`	900 (15 min)	Max time to wait with `--wait`.
`--by-chain`	—	Show the per-chain balance breakdown instead of one combined number.
`--yes`, `--confirm`	—	Skip the deposit confirmation prompt.

selat fund --chain optimism --amount 2                # direct: settles on Optimism
selat fund --chain base --amount 2 --method eco       # eco: ~30s credit, settles on Arc
selat fund --chain base --amount 5 --wait             # block until spendable
selat fund --onramp                                   # buy USDC with a card, no crypto required to start

Settlement chain depends on the method: a direct deposit lands in Gateway on the chain you deposited from, while an eco deposit always lands in Gateway on Arc regardless of the source chain.

Buy USDC with a card (Onramp)

No crypto yet? selat fund --onramp lets you start from a debit or credit card. It mints a one-time Circle Onramp session through the SELAT catalog (free; the Onramp key stays server-side) and gives you a browser link. You pick the amount and pay inside Circle’s widget — the CLI never sees your card, never prompts for an amount, and moves no money itself.

selat fund --onramp                                   # fund the configured SELAT wallet
selat fund --onramp --address 0xYourOtherAgentWallet  # fund a different agent wallet

Funding by card is two steps:

Buy USDC in the widget

Run selat fund --onramp. In a terminal it offers to open the link in your browser; in an agent (non-interactive) shell it prints the link for the agent to relay into chat. Links expire after about 30 minutes — re-run the command any time for a fresh one.The session is scoped to USDC only, on the chains selat fund can deposit from: Base, Ethereum, Arbitrum, Polygon, Avalanche, Unichain, and Arc. (Circle’s widget doesn’t carry USDC on Optimism, so it isn’t offered.) The purchase lands on-chain in your agent wallet on the chain you choose.

Deposit it into Gateway

Once the purchase has landed on-chain, deposit it into your Gateway balance like any other USDC — pass --chain for the chain you bought on:

selat fund --chain <chain-you-bought-on> --amount <usd>

The widget’s identity check (KYC) may continue on your phone. When it asks for an email, use the same email as your Circle Agent Wallet login — a different email breaks the link between the verified identity and the wallet being funded. The CLI prints your login email next to the link when it can read it.

A few more things to know:

First run. selat init offers the same path when your wallet is empty — answer card at the send / card / skip prompt.
Other wallets. --address funds any agent wallet. If it isn’t the configured SELAT wallet, the CLI warns you — paid calls still spend from the configured wallet.
Kill switch. --onramp is refused while selat freeze is on, like every other funding path.
Not Transak. This is SELAT’s built-in onramp. Circle CLI’s circle wallet fund --method fiat is a different, Transak-backed onramp.
If the link can’t be minted (catalog unreachable), the command exits with an error — crypto funding with selat fund --amount <usd> still works.

`selat refund claim | query <quote-id>`

Files or checks a refund claim for a prior settled quote (a selatx… ID from a paid call’s receipt), authenticated through selat-pay with a signed wallet-ownership proof (an EIP-712 signature that can’t move funds). This is authentication, not a payment — it doesn’t touch the session budget or --max-amount. Every claim is reviewed; what comes back depends on whether the upstream captured the payment — see Refunds follow capture.

Flag	Description
`--chain <name>`	Chain key forwarded to `selat-pay` (e.g. `base`).
`--router-url <url>`	Override `SELAT_ROUTER_URL` for this call.

selat refund claim selatx1a2b3c... --chain base
selat refund query selatx1a2b3c... --chain base

`selat budget`

Read-only view of the wallet’s Circle spending caps and the remaining per-window budget, plus the commands to arm or disarm the session spending tripwire that paid calls require. See Spending caps for how this fits with selat setup-policy and selat freeze.

selat budget                      # show caps + remaining budget
selat budget --json
selat budget start --amount 5     # arm the session for up to $5 of paid calls
selat budget stop                 # disarm it

`selat freeze` / `selat unfreeze`

A local, instant kill switch — no Circle round-trip. While frozen, this CLI refuses selat fund (deposits and --onramp) and any paid call; selat-pay also refuses to sign. Free discovery (search, skill list, doctor) keeps working. It does not touch Circle wallet policy, which stays governed by selat setup-policy.

selat freeze --note "pausing while I review last night's spend"
selat unfreeze

`selat history`

Shows locally recorded Gateway micropayments.

Flag	Default	Description
`--address <addr>`	`SELAT_AGENT_WALLET_ADDRESS`	Wallet to filter by.
`--chain <key>`	—	Chain key to filter by (e.g. `base`).
`--limit <n>`	`20`	Number of records to show (positive integer).
`--json`	—	Emit structured JSON.

`selat spend`

Prints a unified, read-only spend report: settled spend from the local selat-pay ledger plus Apify prepaid-token utilization from the token store.

Flag	Description
`--json`	Emit structured JSON.
`--wallet <0x...>`	Wallet to report on.
`--ledger <path>`	Override the ledger path.
`--store <path>`	Override the token-store path.

`selat setup-policy`

Interactively sets Circle spending caps (per-transaction, daily, weekly, monthly) on your Agent Wallet. Requires an email OTP per chain — Circle gates policy writes for security, and there is no batch write. Recommended before any deposit over ~$20.

Flag	Default	Description
`--per-tx <usd>`	5	Per-transaction cap.
`--daily <usd>`	50	Daily cap.
`--weekly <usd>`	200	Weekly cap.
`--monthly <usd>`	500	Monthly cap.
`--chain <CODE>`	every chain the wallet exists on	Cap only this one chain (e.g. `BASE`, `ARB`) — one emailed code instead of N.
`--quarantine-days <n>`	30	Local reliability policy only (no Circle write, no emailed code): days of recent charged `5xx` failures that keep an endpoint excluded from ranking picks (range 1–90). Saved to the selat config file; given alone, saves it and exits without touching Circle. See First-Party Transactability for how this relates to the 90-day evidence window.

With all four caps given as flags, the prompts are skipped and the only interactive step left is Circle’s emailed code(s).

`selat doctor`

Runs a one-pass diagnosis of common setup problems (skill install, PATH, Circle auth, wallet, config, catalog freshness).

Flag	Description
`--by-chain`	Show the per-chain Gateway balance breakdown instead of one combined number.

Agent skills

Beyond ad-hoc selat run, the CLI can install and run agent skills — named, reusable payment recipes from the public selat-skills registry (or a local path).

selat skill list --available                 # browse the catalog (with reliability badges)
selat skill install market-snapshot          # install a skill by name (or ./path)
selat skill run market-snapshot              # run it (needs an armed session budget)
selat skill run token-price --symbols ETH,USDC
selat skill compare "search the web" --live-probe --limit 3   # benchmark candidates, free

Subcommand	Description
`skill list [--available]`	List installed skills, or available ones (with reliability) to install.
`skill install <name\|path> [--force] [--max-amount <usd>]`	Install a skill by name (from the registry) or a local path.
`skill run <name> [--<param> value ...]`	Run an installed skill, passing its manifest params as `--flags`. Payment overrides: `--chain <c>`, `--max-amount <usd>` (hard-capped at $1.10), `--allow-high-max-amount`. `--json` emits one machine object. Requires an armed session budget.
`skill compare "<intent>" --live-probe [--limit N] [--json] [--pay]`	Free. Benchmark the top catalog candidates for an intent side-by-side — price, rail, latency, reliability — without paying. `--live-probe` is required (it acknowledges the probe may invoke each candidate’s method/body). `--pay` adds one capped, confirmed test call per candidate and requires an armed session budget.
`skill new <name> [--dir <dir>] [--force]`	Scaffold a new skill folder (SOP layout) to contribute.
`skill validate <path>`	Validate a skill folder against the Agent Skill SOP (structure, required fields).
`skill verify <path> --live-probe [--pay] [--<param> value ...]`	Live-check each endpoint’s real 402 price/rail. `--live-probe` is required; `--pay` makes one capped paid call. Also accepts `--chain` / `--max-amount`.
`skill register <path> [--index <path>]`	Add or update the skill’s entry in `index.json`.
`skill submit <path> [--dry-run] [--fork\|--no-fork]`	Open a PR to the selat-skills repo (gated on a passing verify receipt). Submits from your fork by default unless you have write access.

selat skill run web-search --query "USDC news" --chain base            # pay from a Base Gateway balance
selat skill verify ./skills/token-price --live-probe --symbols ETH --pay   # capped real call

Configuration

selat init writes your config to $XDG_CONFIG_HOME/selat-pay/.env (mode 0600). Values are layered: shell env > cwd .env > this file. You can also set these in the environment to override defaults:

Variable	Purpose
`SELAT_AGENT_WALLET_ADDRESS`	Default wallet address (used by `history` and payments). Written by `selat init`.
`SELAT_WALLET`	Non-interactive wallet selection for `selat init --wallet`, same as the flag.
`SELAT_ROUTER_URL`	Router URL used at runtime (must be `https://`).
`SELAT_DEFAULT_ROUTER_URL`	Default router URL used by `selat init`.
`SELAT_PAY_BIN`	Path to the `selat-pay` binary, if not auto-resolved.
`SELAT_SKILLS_DIR`, `SELAT_SKILLS_REPO`, `SELAT_SKILLS_REF`, `SELAT_SKILLS_RAW_BASE`	Override the skills registry source.
`SELAT_DEBUG=1`	Print stack traces on fatal errors.

There is no raw-private-key signing path in the current CLI — every signature goes through the Circle Agent Wallet. SELAT_SESSION_BUDGET in the shell env or a cwd .env cannot arm or invent a session budget either; only selat budget start --amount <usd> (writing session.json) does that. See Spending caps.

Overview

Agentic payments

Transactability

HTTP 402

SELAT Plugins

Catalog MCP

SELAT Router SDK

Skills

Glossary

SELAT CLI

When to use it

Install

Prerequisites

Get started

Spending caps

Commands

`selat init`

`selat search "<intent>"`

`selat run "<intent>"`

`selat fund`

Buy USDC with a card (Onramp)

`selat refund claim | query <quote-id>`

`selat budget`

`selat freeze` / `selat unfreeze`

`selat history`

`selat spend`

`selat setup-policy`

`selat doctor`

Agent skills

Configuration

​When to use it

​Install

​Prerequisites

​Get started

​Spending caps

​Commands

​selat init

​selat search "<intent>"

​selat run "<intent>"

​selat fund

​Buy USDC with a card (Onramp)

​selat refund claim | query <quote-id>

​selat budget

​selat freeze / selat unfreeze

​selat history

​selat spend

​selat setup-policy

​selat doctor

​Agent skills

​Configuration

​Related docs

When to use it

Install

Prerequisites

Get started

Spending caps

Commands

`selat init`

`selat search "<intent>"`

`selat run "<intent>"`

`selat fund`

Buy USDC with a card (Onramp)

`selat refund claim | query <quote-id>`

`selat budget`

`selat freeze` / `selat unfreeze`

`selat history`

`selat spend`

`selat setup-policy`

`selat doctor`

Agent skills

Configuration

Related docs