# CLI

> The Reply command line — contacts, sequences, inbox, and reports as shell commands with JSON output. Install with npm i -g reply-cli. High-level command map here; full flags and details at docs.reply.io/cli/commands.

## Install

```bash
npm install -g reply-cli      # installs the `reply` command (Node 20+)
# or zero-install:
npx -y reply-cli auth whoami
```

Same API key as every other surface — create one in Reply → **Settings → API Keys**. Resolution
order: `--api-key` flag → `REPLY_API_KEY` env var → `.env` file (current directory or up to 5
parents). The key is never logged or written anywhere by the CLI.

```bash
export REPLY_API_KEY=...
reply auth whoami             # verify: prints your user and team
```

## Command map

Every command maps to documented [v3 endpoints](/apis) — the CLI adds no private surface. Run
`reply <group> --help` for flags and examples on any command; the full reference is canonical at
[docs.reply.io/cli/commands](https://docs.reply.io/cli/commands).

| Command | What it does |
|---------|--------------|
| `reply auth whoami` | Verify the API key, show user and team |
| `reply contacts list\|get\|create\|update\|delete` | Contact CRUD (by ID or email) |
| `reply contacts search` | Filter contacts (`--term`, `--list`, `--sequence`, `--rule`) |
| `reply contacts statuses <id\|email>` | Opt-out, call, meeting, and per-sequence status |
| `reply contacts import <file.csv>` | CSV import — auto column mapping, dedupe, `--dry-run` |
| `reply lists list\|get\|create\|add-contacts` | Contact lists |
| `reply sequences list\|get\|create\|update` | Sequences (create accepts `--name` or JSON on stdin) |
| `reply sequences start\|pause\|archive <id>` | Sequence lifecycle (start/archive are confirmation-gated) |
| `reply sequences stats [id]` | Performance for one or all sequences (`--top`, `--preset`, `--from/--to`) |
| `reply sequences contacts list\|add\|remove <id>` | Contacts within a sequence |
| `reply inbox threads list\|get` | Inbox threads (`--unread`, `--category`, `--sequence`, `--search`) |
| `reply inbox reply <thread-id>` | Send a reply on a thread (confirmation-gated) |
| `reply inbox categories list\|assign` | Inbox categories |
| `reply reports emails` | Account-level email performance overview |
| `reply reports sequences` | Per-sequence performance table |
| `reply email-accounts list\|check` | Connected sending accounts |
| `reply schedules list\|get` | Sending schedules |

**Global flags:** `--json` (compact) / `--pretty` (formatted) · `--api-key <key>` ·
`--limit <n>` (default 25, max 1000) / `--skip <n>` / `--all` (fetch every page) ·
`--preset` (named date windows like `lastWeek`) · `--dry-run` (preview, zero API calls) ·
`--yes` (skip the confirmation prompt in scripts).

## Built for agents

- **JSON everywhere** — `--json` on every command; data on stdout, status on stderr, safe to pipe
  into `jq` or agent logic.
- **Deterministic errors** — one stderr JSON line:
  `{"error":{status,code,title,detail,hint}}`. Exit codes: `0` ok · `1` API error · `2` usage.
- **Safety by default** — destructive and sending commands prompt on a TTY and *refuse* without
  `--yes` in scripts; bulk commands support `--dry-run` (zero API calls).
- **Rate limits handled** — 429s honor `Retry-After`, 5xx retries back off exponentially; `--all`
  paginates through any list (wrapped as `{"items":[…],"count":N,"pagesFetched":P}`).
- **Scoped keys work as-is** — a key with `sequences:read` can list but not start.

```bash
# agent-style composition: pause every sequence with reply rate under 1%
reply sequences stats --json \
  | jq -r '.[] | select(.emailOverview.repliedPercentage < 1) | .sequenceId' \
  | xargs -I{} reply sequences pause {}
```

The complete machine contract — error shapes, pagination, rate-limit behavior, composition
patterns, and a drop-in agent prompt — is canonical at
[docs.reply.io/cli/agents](https://docs.reply.io/cli/agents).

## Not yet included

Prospect search and enrichment (**Coming soon** — the underlying [Live Data](/apis/prospect-search)
and [Enrichment](/apis/contact-enrichment) endpoints aren't generally available yet), webhooks
admin, tasks, templates, and the AI SDR module (use [REST](/apis) or [MCP](/mcp) for those today).

Source and issues: [github.com/replyio/reply-cli](https://github.com/replyio/reply-cli) · Package:
[npmjs.com/package/reply-cli](https://www.npmjs.com/package/reply-cli) · Docs:
[docs.reply.io/cli/overview](https://docs.reply.io/cli/overview)

## FAQ

**Does the CLI exist today?**

Yes. Install it with `npm i -g reply-cli` (or run `npx -y reply-cli`). Version 0.2 covers contacts, lists, sequences, inbox, reports, email accounts, and schedules against the v3 API. Prospect search and enrichment commands ship when those API endpoints do. The canonical command reference is at docs.reply.io/cli/commands.

**Why a CLI when there's already REST and MCP?**

Coding agents are exceptionally good at running shell commands. The CLI gives them composability (pipes, jq, cron) without writing HTTP client code, plus built-in retries, rate-limit handling, confirmation gates, and dry-runs — and gives humans a scriptable surface for one-off operations.

**How does it relate to the Agent Skill?**

The Skill (see /skills) is the reasoning layer — it teaches an agent which workflow to run. The CLI is its execution layer — deterministic commands the skill shells out to. You can use the CLI without the skill; the skill requires the CLI.