# CLI reference

The `jell` 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 jell
```

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

## Commands

### setup

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

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

### signup

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

Sandbox onboarding: creates an organization with $1 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
jell keys add -k rg_live_... -l main   # store a key under a label
jell keys list                          # stored keys (labels, never raw keys)
jell keys activate -l main              # switch the active key
jell keys remove -l old                 # delete a stored key
```

Keys live in local config only; never commit them.

### balance

```bash
jell balance
```

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

### discover

```bash
jell discover -q "find a verified email for a person"
jell discover -q "tiktok video comments" --kind endpoint --provider tikhub
```

Catalog search by job description; free. One ranked list of capabilities and [raw provider endpoints](/docs/api/endpoints), each with its kind, status, relevance score, price or cost model and health verdict, followed by the server's hints on what to do next. `--kind` and `--provider` narrow it.

### endpoints

```bash
jell endpoints -p dataforseo -q backlinks
```

Everything one provider serves raw, with a substring filter. Free.

### inspect

```bash
jell inspect -c contact.find
jell inspect -p dataforseo -e /v3/serp/google/organic/live/advanced
```

The capability's contract: input schema, output fields, providers, exact prices, billing conditions, health. For a raw endpoint (`-p` and `-e`): the provider's own input spec, cost model, health, which capability wraps it, and a ready-to-paste `run` line. Run it (and surface the price) before any billable `run`.

### run

```bash
jell run -c contact.find \
  -i '{"first_name":"Alex","last_name":"Rivera","company_domain":"example.com"}' \
  --max-cost 0.10
# returns a compact receipt immediately
jell runs get -r <run_id> --wait 60 -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) |
| `-w`, `--wait [seconds]` | opt into polling; bare `--wait` waits up to 120 seconds |
| `-o` | write the result to a file instead of printing it |

`run` submits immediately by default and returns a compact receipt with the run ID. This keeps provider latency out of the agent's request path. Add `--wait`, or poll with `runs get -r <run_id> --wait 60`. Write large results to a file with `-o`; the summary line still prints what was charged and which provider delivered.

A raw endpoint run addresses the provider directly:

```bash
jell run -p dataforseo -e /v3/serp/google/organic/live/advanced \
  -i '{"keyword":"best crm","location_code":2840,"language_code":"en"}' \
  --max-cost 0.05 -o serp.json
```

| Flag | Notes |
| --- | --- |
| `-p`, `-e` | provider slug and the provider's endpoint path, from `discover` or `endpoints` |
| `-i` | the provider's request body (on `GET` endpoints: its query parameters) |
| `--query` | extra query parameters as JSON |
| `--path` | values for `{placeholders}` in the endpoint path, as JSON |
| `--max-cost` | bounds the hold and the charge; set it on every raw call |

There is no quote: the run settles on the provider's measured cost after the call, never above `--max-cost`.

### runs

```bash
jell runs                 # recent runs, newest first
jell runs get -r run_... --wait 60 -o result.json
```

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

### history

```bash
jell history alex.rivera@example.com          # every run that mentions this person: touches, results to reuse
jell history example.com                      # a company: enrichments, people found there, anyone at it contacted
jell history https://www.linkedin.com/in/alex-rivera
jell history "Alex Rivera" --kind text
jell history --file leads.txt                 # one identifier per line: seen / contacted / reusable, before a batch
```

Check it before enriching or messaging anyone. It is [`GET /v1/history`](/docs/api/runs#history-for-a-subject) over the run log, so it is exactly as complete as what went through Jell. Free.

### guard

```bash
jell guard                 # daily cap, per-run ceiling, today's spend
jell guard --daily 25      # block runs once $25 is spent in a UTC day
jell guard --per-run 1     # block any single run holding more than $1 (off by default)
jell guard --per-run off
jell guard --off
```

## Ground rules for agents

- `inspect` before any billable `run`, and show the user the price.
- Cap every call with `--max-cost`; on raw endpoints it is the only price control you have before the run.
- Prefer a capability over the raw endpoint it wraps (`discover` says which): normalized output, a quote, failover.
- Stop and ask before a batch that would exceed about $1.
- Never present sandbox mock output as real data.