Command line interface (CLI)

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 teaches coding agents to drive.

The current release is rc 0.3.0.

Install

curl -fsSL https://app.reversecontact.com/cli/install.sh | sh

brew install visum-run/tap/rc

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. 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.

# Opens a page where you approve the access from your workspace.
rc auth login --browser

rc auth login rc_your_api_key

# 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.

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.

rc enrich person --email jane.doe@acme.com --fields firstName,lastName,currentPositionTitle

rc check person --url https://social.com/in/janedoe
rc fetch person --url https://social.com/in/janedoe

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"

rc search companies --industry "Software Development" --size 51-200 --country "United States"

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":"..."}}.

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

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.