> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/guides/cli
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# Command line interface (CLI)

> Install rc, the Reverse Contact command line tool, sign in, and check, fetch, enrich and search from your terminal or a script.

- Last verified: 2026-10-15

## Introduction

`rc` is the official Reverse Contact command line tool: one binary for macOS, Linux and Windows that calls the same API with the same credits and rate limits, and prints JSON ready for `jq` or a script. It is also what the [agent skill](https://docs.reversecontact.com/guides/agent-skills) teaches coding agents to drive.

The current release is `rc` 0.3.0.

## Install

**Install**

```bash [macOS and Linux]
curl -fsSL https://app.reversecontact.com/cli/install.sh | sh
```
```bash [Homebrew]
brew install visum-run/tap/rc
```
```powershell [Windows]
powershell -c "irm https://app.reversecontact.com/cli/install.ps1 | iex"
```

The install scripts download the binary for your platform, check it against the published SHA-256 checksum, and install it in `~/.local/bin` on macOS and Linux, or `%LOCALAPPDATA%\Programs\rc` on Windows. Set `RC_INSTALL_DIR` to install elsewhere, or `RC_VERSION` to pin a version. Run `rc version` to see the installed version, and whether a newer one is out: it reads `https://app.reversecontact.com/cli/manifest.json`.

## Sign in

The CLI needs an API key from [API Keys](https://app.reversecontact.com/api-keys). It looks for one in this order: the `--api-key` flag, the `RC_API_KEY` environment variable, then the key stored by `rc auth login`.

**Sign in**

```bash [Browser]
# Opens a page where you approve the access from your workspace.
rc auth login --browser
```
```bash [API key]
rc auth login rc_your_api_key
```
```bash [Script or CI]
# Nothing written to disk:
export RC_API_KEY=rc_your_api_key
# Or store the key from a secret manager:
echo "$RC_API_KEY" | rc auth login --with-token
```

`rc auth status` shows where the key comes from and the credit balance of the workspace; it exits with code `3` when no valid key is found. `rc auth logout` removes the stored key. With `--browser` on a machine without a browser, add `--no-open` to print the address to open instead.

The stored key lives in `~/.config/reversecontact/config.json` on macOS and Linux (`$XDG_CONFIG_HOME/reversecontact/config.json` when it is set), and in `%APPDATA%\reversecontact\config.json` on Windows.

## Commands

Each command calls the API and is billed like it: the credits below are the ones of the API.

| Command | What it does | Credits |
| ------- | ------------ | ------- |
| `rc check person` or `rc check company` with `--url` or `--id` | Whether a profile exists and when it was last updated ([Person profile status](https://docs.reversecontact.com/endpoints/check-person)) | Free |
| `rc fetch person` or `rc fetch company` with `--url` or `--id` | The cached profile ([Person profile](https://docs.reversecontact.com/endpoints/fetch-profile)) | 1 when found, a `404` is free |
| `rc fetch person --url ... --live` | A fresh copy, as a job ([Person profile live](https://docs.reversecontact.com/endpoints/fetch-profile-live)) | 2 per request |
| `rc enrich person` with `--email`, or `--first-name`, `--last-name` and `--company-domain` or `--company-name` | The person behind an email or a name ([Enrich profile](https://docs.reversecontact.com/endpoints/enrich-person)) | 2 when found, a `404` is free |
| `rc enrich company --domain` | The company behind a domain ([Enrich company](https://docs.reversecontact.com/endpoints/enrich-company)) | 2 when found, a `404` is free |
| `rc search people` with filters | People matching filters: the CLI counts them first with the free [People search count](https://docs.reversecontact.com/endpoints/search-people-count), then runs [People search](https://docs.reversecontact.com/endpoints/search-people). The next page comes with `--cursor` | 1 per profile delivered, the count is free |
| `rc search companies` with filters | Companies matching filters ([Company search](https://docs.reversecontact.com/endpoints/search-companies)). The next page comes with `--page` | 1 per page |
| `rc search fields people` or `rc search fields companies` | The filters each search accepts ([People search available fields](https://docs.reversecontact.com/endpoints/search-people-available-fields), [Company search available fields](https://docs.reversecontact.com/endpoints/search-companies-available-fields)) | Free |
| `rc contact email` with `--url`, or a name and `--company-domain` | A professional email, as a job ([Find Email](https://docs.reversecontact.com/endpoints/contact-email)) | 3 when an email is found |
| `rc contact phone` with `--url`, or a name and `--company-domain` | A phone number, as a job ([Find Phone](https://docs.reversecontact.com/endpoints/contact-phone)) | 20 when a number is found |
| `rc task <taskId>` | The status and result of a job ([Polling](https://docs.reversecontact.com/guides/polling)) | Free |
| `rc usage` | The credit balance and rate limits ([Usage](https://docs.reversecontact.com/endpoints/usage)) | Free |

When you already have a profile URL or a Reverse Contact id, `rc fetch` (1 credit) is cheaper than `rc enrich` (2 credits), and a free `rc check` first tells you whether the cached copy is recent enough. `rc enrich person` does not take a profile URL. Without `--fields`, the JSON output is the full API response, and its `quotas.creditsConsumed` says what the call consumed.

**Examples**

```bash [Enrich]
rc enrich person --email jane.doe@acme.com --fields firstName,lastName,currentPositionTitle
```
```bash [Check, then fetch]
rc check person --url https://social.com/in/janedoe
rc fetch person --url https://social.com/in/janedoe
```
```bash [Search people]
rc search people --title CTO --country France --limit 25
# The next page: pass back metadata.nextCursor of the previous one.
rc search people --title CTO --country France --limit 25 --cursor "$NEXT_CURSOR"
```
```bash [Search companies]
rc search companies --industry "Software Development" --size 51-200 --country "United States"
```
```bash [Balance]
rc usage --json | jq '.quotas.workspace.credits.left'
```

## In scripts

Output is JSON whenever stdout is not a terminal, so pipes and scripts get JSON without a flag; `--json` forces it everywhere. Without `--fields`, stdout gets the full API response; with it, only the fields you picked, flat, without the response envelope. An error goes to stderr as `{"error":{"code":"...","message":"...","hint":"..."}}`.

| Exit code | Meaning |
| --------- | ------- |
| `0` | Success, including a not-found result (`success: false`, 0 credits) |
| `1` | API error, including `402` (not enough credits), `403` (access denied: free trial or key permissions) and a `429` still refused after the retries. With `--wait`, also a job that ended `errored` |
| `2` | Usage error: a missing input, a bad value or two flags that cannot go together |
| `3` | Authentication error: no API key, or a key the API refuses with `401` |
| `4` | Network error, request timeout, or a `--wait` that ran out of time |

A not-found result exits `0` on purpose, so a batch keeps going: add `--fail-on-not-found` to `rc enrich` to exit `1` instead. Other options common to the commands: `--fields` keeps only the listed fields (comma-separated, dotted paths such as `location.city`), `--quiet` hides spinners and credit hints, and `--timeout` sets the request timeout in seconds (30 by default). On a `429`, the CLI makes 3 attempts in all: it retries twice, after 1 then 2 seconds.

## Live jobs

`rc fetch ... --live`, `rc contact email` and `rc contact phone` return a job id at once: read it later with `rc task <taskId>`, which returns the job status and its `result` when it succeeded. Without `--wait`, `rc task` exits `0` whatever the status: read `data.status` (`succeeded` or `errored`). With `--wait`, a job that ended `errored` exits `1`. Results usually arrive within seconds but can take tens of minutes, so prefer this over waiting in a loop.

To block until a live fetch finishes, add `--wait` with a `--timeout` in seconds that leaves the job enough time: `rc fetch person --url https://social.com/in/janedoe --live --wait --timeout 300`. When the time runs out, `rc` exits `4` and the job keeps running: read it with `rc task`.

## Environment variables

| Variable | Effect |
| -------- | ------ |
| `RC_API_KEY` | The API key, ahead of the stored one |
| `RC_BASE_URL` | The API address (`https://api.reversecontact.com` by default) |
| `RC_OUTPUT` | `json` or `human`, whatever the terminal |
| `RC_DEBUG=1` | Print the stack trace of an error |
| `RC_NO_UPDATE_CHECK=1` | Turn off the update check of `rc version` |

## FAQ

### Does the Reverse Contact CLI cost more than the API?

No. Each `rc` command calls the Reverse Contact API and is billed exactly like it, with the same credits and the same rate limits: `rc check` and `rc usage` are free, `rc fetch` costs 1 credit when the profile is found, `rc enrich` costs 2 credits when a match is found, and the count `rc search people` runs before its search is free.

### How do I use the Reverse Contact CLI in CI without a browser?

Set the `RC_API_KEY` environment variable, which writes nothing to disk, or pipe the key into `rc auth login --with-token`. `rc auth status` exits with code `3` when no valid key is found, which makes a quick check before a job.

### How does a script tell a not-found result from an error with the Reverse Contact CLI?

A not-found result exits with code `0` and costs 0 credits; without `--fields`, the JSON output also says `success: false`. Errors exit with code `1` (API), `2` (usage), `3` (authentication) or `4` (network), with the error on stderr. Add `--fail-on-not-found` to `rc enrich` to make a not-found result exit `1`.