> ## Documentation Index
> Fetch the complete documentation index at: https://selat.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SELAT CLI

> Set up and run SELAT agent payments from the terminal — discover, rank, and pay x402 services in one command.

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`](https://www.npmjs.com/package/@selat-ai/selat-cli) package, which installs the **`selat`** command.

<Tip>
  `selat` is the high-level CLI. Under the hood it shells out to the lower-level [`@selat-ai/selat-pay`](https://www.npmjs.com/package/@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.
</Tip>

## 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](/docs/selat-sdk) documentation. Do not combine its package installation or signer setup with this terminal workflow.

## Install

```bash theme={null}
npm install -g @selat-ai/selat-cli
```

Verify the install:

```bash theme={null}
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`](https://github.com/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 → run**, with `selat search` as the free preview of what `run` would pick.

<Steps>
  <Step title="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.

    ```bash theme={null}
    selat init
    ```

    If you have no spendable USDC, `init` points you to `selat fund`.
  </Step>

  <Step title="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.

    ```bash theme={null}
    selat fund --chain base --amount 2
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    selat search "summarize the latest news on gold prices"
    ```
  </Step>

  <Step title="Pay for the best match">
    `run` discovers matching x402 services, ranks them, and pays for the best one in a single pipe.

    ```bash theme={null}
    selat run "summarize the latest news on gold prices"
    ```
  </Step>
</Steps>

<Tip>
  Before depositing more than \~\$20, set spending caps with `selat setup-policy`. If anything looks off, `selat doctor` diagnoses your setup in one pass.
</Tip>

## 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, and author agent skills (see below).                               |
| `selat fund`                      | Top up your Gateway balance. Dry-runs first; requires explicit confirmation.           |
| `selat history`                   | Show locally recorded Gateway micropayments.                                           |
| `selat spend`                     | Unified spend report: settled spend + Apify token utilization. Read-only.              |
| `selat setup-policy`              | Set Circle spending limits on your Agent Wallet (requires an email OTP).               |
| `selat doctor`                    | 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).              |
| `--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.                                      |
| `--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.                        |

```bash theme={null}
selat search "transcribe audio to text" --top 3
selat search "people enrichment" --json
```

### `selat run "<intent>"`

Takes a natural-language intent and runs the discovery skill's ranking + payment plan against it, paying for the top match.

| Flag                  | Description                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--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) and retry the run. Ignored for other services. |

```bash theme={null}
selat run "find USDC price news and summarize"
selat run "scrape this page" --input '{"url": "https://example.com"}' --auto-rebuy
```

### `selat fund`

Tops up your Gateway balance. Shows the plan locally, then requires you to confirm before depositing.

| Flag                     | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--chain <key>`          | `base`   | Chain to deposit from (e.g. `arc`, `base`, `optimism`, `arbitrum`).                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--amount <usd>`         | `2`      | USDC amount to deposit. Must be a positive number.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--method <direct\|eco>` | `direct` | Both methods are gasless (the agent wallet's transactions are gas-sponsored) — the choice is speed. `direct` deposits on the chain you fund from (settles on that same chain, no routing fee). `eco` uses Eco Fast Deposits from Base (current Circle CLI eco coverage; Eco natively supports Optimism and Arbitrum too) — a \~30-second credit vs the \~5–10-minute direct wait, for a small fixed routing fee — and **always settles into Circle Gateway on Polygon**. |

```bash theme={null}
selat fund --chain optimism --amount 2                # direct: settles on Optimism
selat fund --chain base --amount 2 --method eco       # eco: ~30s credit, settles on Polygon
```

<Tip>
  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 Polygon regardless of the source chain.
</Tip>

### `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 — Circle gates policy writes for security. Recommended before any deposit over \~\$20.

Also sets the local **quarantine period** — how many days of recent charged `5xx` failures (with nothing settled) keep an endpoint excluded from ranking picks. `--quarantine-days <n>` (whole days, 1–90; default 30) saves it to the selat config with no Circle write and no emailed code, so it works non-interactively too — given alone, the command saves it and exits without touching Circle. See [First-Party Transactability](/docs/transactability/first-party#honest-limits) for how the quarantine clock relates to the 90-day evidence window.

### `selat doctor`

Runs a one-pass diagnosis of common setup problems (skill install, `PATH`, Circle auth, wallet, config). Run it whenever something looks off. Takes no flags.

## Agent skills

Beyond ad-hoc `selat run`, the CLI can install and run **agent skills** — named, reusable payment recipes from the public [selat-skills](https://github.com/SELAT-AI/selat-skills) registry (or a local path).

```bash theme={null}
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
selat skill run token-price --symbols ETH,USDC
```

| 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> [--p value ...]`                          | Run an installed skill, passing its params as `--flags`. Payment overrides: `--chain <c>`, `--max-amount <usd>`, `--raw-key`. |
| `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> [--pay] [--p value ...]`               | Live-check each endpoint (real 402 price/rail); `--pay` makes a 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]`                           | Open a PR to the selat-skills repo (gated on a passing verify receipt).                                                       |

```bash theme={null}
selat skill run web-search --query "USDC news" --chain base            # pay from an Base Gateway balance
selat skill verify ./skills/token-price --symbols ETH --pay            # capped real call
```

## Configuration

`selat init` writes your config to `$XDG_CONFIG_HOME/selat-pay/.env`. 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).         |
| `SELAT_PRIVATE_KEY`                                                                  | Signing key for the payer, when not using a Circle Agent Wallet. |
| `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.                              |

## Related docs

* [SELAT Router](/docs/router)
* [SELAT Router SDK](/docs/selat-sdk)