# CLI reference

The `routergrowth` CLI mirrors the API one-to-one: same names, same JSON, printed as plain text with no colors and no interactive prompts, so agents can drive it directly.

```bash
npm install -g routergrowth
```

`EACCES`? Install per-user: `npm install --prefix ~/.local routergrowth`, then symlink `~/.local/node_modules/.bin/routergrowth` into your `PATH`.

## Commands

### setup

```bash
routergrowth setup --client "my-agent"
```

Initializes local config and identifies the calling client (useful when several agents share a machine).

### signup

```bash
routergrowth signup --email you@company.com --org "Acme"
```

Sandbox onboarding: creates an organization with $5 of promotional credit and saves the minted `rg_test_` key locally. On production, mint keys in the [dashboard](/dashboard) instead and store them with `keys add`.

### keys

```bash
routergrowth keys add -k rg_live_... -l main   # store a key under a label
routergrowth keys list                          # stored keys (labels, never raw keys)
routergrowth keys activate -l main              # switch the active key
routergrowth keys remove -l old                 # delete a stored key
```

Keys live in local config only; never commit them.

### balance

```bash
routergrowth balance
```

Prints the wallet: balance, reserved, available. Same data as [`GET /v1/wallet`](/docs/api/wallet).

### discover

```bash
routergrowth discover -q "find a verified email for a person"
```

Catalog search by job description; free. Each hit prints its status, providers, starting price and the `inspect` command to run next.

### inspect

```bash
routergrowth inspect -c contact.find
```

The capability's contract: input schema, output fields, providers, exact prices, billing conditions. Run it (and surface the price) before any billable `run`.

### run

```bash
routergrowth run -c contact.find \
  -i '{"first_name":"Alex","last_name":"Rivera","company_domain":"example.com"}' \
  --max-cost 0.10 \
  -o result.json
```

| Flag | Notes |
| --- | --- |
| `-c` | capability slug |
| `-i` | input JSON (must match the inspected schema) |
| `--max-cost` | USD cap applied to every routing attempt |
| `--provider` | pin a provider instead of `auto` |
| `--strategy` | `cheapest`, `fastest`, `highest_success_rate`, `best_value` (default) |
| `-o` | write the result to a file instead of printing it |

Write large results to a file with `-o`; the summary line still prints what was charged and which provider delivered.

### runs

```bash
routergrowth runs                 # recent runs, newest first
routergrowth runs get -r run_...  # one run in full
```

Same records as [`GET /v1/runs`](/docs/api/runs): status, provider, attempts, quoted and charged amounts.

## Ground rules for agents

- `inspect` before any billable `run`, and show the user the price.
- Cap every call with `--max-cost`.
- Stop and ask before a batch that would exceed about $1.
- Never present sandbox mock output as real data.