# CLI (/docs/cli)



<Callout type="warn" title="Not on npm yet">
  The `grid` CLI (`@relaygrid/cli`) is not published yet. Until it is, the same stream is one
  `curl -N` away: see [live tail](/docs/concepts/logs-and-drains#live-tail).
</Callout>

`grid` needs Node 22.18 or newer and a key with `logs:read`.

```bash
export GRID_API_KEY=grid_live_…
grid logs tail --capability people.email.find --status error
```

## Commands [#commands]

```text
grid logs tail [filters] [--json]     Stream the live log (calls, runs, jobs, lists, alerts)
grid logs recent [filters] [-n 50]    Print the newest buffered events and exit
```

`tail` prints one line per event (for calls: time, outcome, HTTP status, endpoint, latency, cost,
error code and call id) until you press Ctrl-C, reconnecting on its own. `--json` prints each event as a JSON line instead, for `jq`.

## Filters [#filters]

| Flag                                    | Filter                           |
| --------------------------------------- | -------------------------------- |
| `--capability <id,…>`                   | `capability`                     |
| `--provider <slug,…>`                   | `provider`                       |
| `--endpoint <id,…>`                     | `endpoint_id`                    |
| `--status <hit\|miss\|failed\|error,…>` | `status`                         |
| `--key <id,…>`                          | `key_id`                         |
| `--app <id,…>`                          | `app_id`                         |
| `--run <id>`                            | `run_id` (a run, list or job id) |
| `--waterfall <id>`                      | `waterfall_id`                   |
| `--kinds <call,run,job,list,alert>`     | `kinds`                          |
| `--min-latency <ms>`                    | `latency_min`                    |
| `--min-cost <micro-USD>`                | `cost_min`                       |
| `--sample <0-1>`                        | `sample`                         |
| `--fields <col,…>`                      | `fields`                         |
| `--replay <0-1000>`                     | `replay`                         |

The API validates every value; see the [live tail filters](/docs/concepts/logs-and-drains#live-tail).

## Environment [#environment]

| Variable       |                                                                              |
| -------------- | ---------------------------------------------------------------------------- |
| `GRID_API_KEY` | API key with `logs:read` (required)                                          |
| `GRID_API_URL` | API base URL (default `https://api.gridrouter.io`; `--api-url` overrides it) |