# CLI

`ra` is Closefinch's command line, built for people and coding agents. It covers every resource in the REST API,
prints a table in a terminal and JSON when piped, and has a built-in `--jq`. It has no dependencies (Node's standard
library only) and needs Node 22.12 or newer. Version 0.1.0.

## Install

It isn't on the npm registry yet: install the package built from the repository, with npm. Never pipe a script into
a shell.

```bash
node tools/cli/pack.mjs                                # in the repository: writes apps/cli/dist/revenueagent-cli-0.1.0.tgz
npm install -g ./apps/cli/dist/revenueagent-cli-0.1.0.tgz
ra --version
```

## Sign in

```bash
ra login --host https://api.closefinch.com
```

It shows a short code; approve it in your browser (OAuth device flow, nothing to paste). For scripts, use a key from
Settings → API keys instead, read from a variable rather than typed on the command line:
`printf %s "$RA_API_KEY" | ra auth login --host https://api.closefinch.com --with-key`. In CI, set `RA_HOST` and `RA_API_KEY`. `ra auth status` shows who you are; `ra auth logout` forgets the profile.

## Common commands

```bash
ra deals list --query q=Acme --fields id,name
ra deals get deal_…
ra tasks create --field values.title="Call back" --raw-field 'values.related=["deal_…"]'
ra api GET /v1/forecast
ra runs start agt_… --input '{"deal_id":"deal_…"}' --wait
ra bulk-create contacts --input contacts.jsonl
```

- Deleting and merging need `--force`; `--dry-run` prints the request instead of sending it.
- `ra runs start … --wait` exits 1 if the run failed; 3 if it's waiting for a person, paused or sleeping; and 0
  otherwise: done, cancelled, or still running after about 20 minutes of waiting (check its status before relying on it).
- `ra agent-context` prints, as JSON, what the CLI and your credential can do.

## Filter with --jq

```bash
ra deals list --jq '.data[] | select(.values.amount.amount > 10000) | {id, name}'
```

A deal's amount is `{ amount, currency }`, so compare `.values.amount.amount`. The built-in jq covers paths, `select`, `map`, comparisons, object and array construction, string interpolation,
`if`/`reduce`/`try`, `sort_by`/`group_by`/`unique_by`, `to_entries`/`with_entries`, regular expressions
and formats such as `@csv` and `@json`. It only reads: no assignment, no `def`, no environment access.

## Set up Claude Code

```bash
ra install claude-code
```

It adds the MCP server to the project's `.mcp.json` and a skill for Claude Code. They reference `${RA_API_KEY}`,
never the key itself, so set `RA_API_KEY` to a key from Settings → API keys (the browser sign-in doesn't make one). `ra install codex` prints the block for Codex's config instead. Quickstarts for other clients:
[Quickstarts](https://www.closefinch.com/docs/quickstart).

## Every command

From `ra help` (version 0.1.0):

```text
ra 0.1.0: the Closefinch CLI

  ra login --host <api url> [--scope "crm:read …"]     sign in in your browser with a short code (no key to paste)
  ra auth login --host <api url> --key <ra_live_…>     sign in with an API key (or --with-key to read it from stdin)
  ra auth login --host <api url> --client-id <id>      sign in with OAuth (an owner registers the app with
                                                       redirect http://127.0.0.1:8765/callback; --port to change)
  ra auth status | ra auth logout
  ra sandbox create --host <api url> [--agent-name <name>] [--claim-email <person's email>]
                                                       for agents: a sandbox organization with sample data and a limited
                                                       key (7 days, no outbound until a person claims it), saved as a profile
  ra api <GET|POST|PATCH|PUT|DELETE> <path> [--field k=v] [--raw-field k=<json>] [--body <json>|@file|-] [--query k=v]
  ra <resource> list [--query k=v] [--limit n] [--all]
  ra <resource> get <id> | create [--field …] | update <id> [--field …] | delete <id> --force
  ra bulk-create <resource> --input <file.json|file.jsonl|-> [--batch <id>]   25 per request; exits 1 if any row fails
  ra runs start <agent> [--input <json>] [--wait]
  ra agent-context                                     what this CLI and your credential can do, as JSON
  ra install claude-code [--dir .]                     add the MCP server (.mcp.json) and a skill for Claude Code
  ra install codex                                     print the Codex config block (writes nothing)

  Output: a table in a terminal, JSON when piped. --json, --output table|json|toon, --fields a,b.c, --jq <program> (a built-in jq).
  --dry-run prints the request instead of sending it. --profile <name>, --host <url>. CI: RA_HOST, RA_API_KEY.
```