Skip to content

Install rc, the Reverse Contact command line tool, sign in, and check, fetch, enrich and search, enrich whole files in bulk and fill your Lists from your terminal or a script.

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. The agent skill teaches coding agents to use it.

The current release is rc 0.8.1.

Install

Install

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

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.

Sign in

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

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 costs the same credits as the API calls it makes.

CommandWhat it doesCredits
rc check person or rc check company with --url or --idWhether a profile exists and when it was last updated (Person profile status)Free
rc fetch person or rc fetch company with --url or --idThe cached profile (Person profile)1 when found, a 404 is free
rc fetch person --url ... --liveA fresh copy, as a task (Person profile live)2 per request
rc enrich person with --email, or --first-name, --last-name and --company-domain or --company-nameThe person behind an email or a name (Enrich profile)2 when found, a 404 is free
rc enrich company --domainThe company behind a domain (Enrich company)2 when found, a 404 is free
rc search people with filtersPeople matching filters: the CLI counts them first with the free People search count, then runs People search. The next page comes with --cursor1 per profile delivered, the count is free
rc search organizations with filtersCompanies matching filters, as full profiles: the CLI counts them first with the free Company search count, then runs Company search. --limit sets the page size and the next page comes with --cursor1 per company delivered, the count is free
rc search fields people or rc search fields organizationsThe filters each search accepts (People search available fields, Company search available fields)Free
rc contact email with --url or --id, or a name and --company-domainA professional email, or a personal one with --type personal (--type any accepts either), as a task (Find Email)3 for a professional email, 5 for a personal one, when found: --type any costs 3, 5 or 8
rc contact phone with --url or --id, or a name and --company-domainA phone number, as a task (Find Phone)20 when a number is found
rc task <taskId>The status and result of a task: a live fetch or a contact lookup (Polling), or a Bulk task (Get a task)Free
rc bulk create --file people.csvEnrich up to 25,000 people from a CSV, NDJSON or JSON file in one task (Bulk), see Bulk belowEach item what its unit call costs, only for what is found
rc bulk get <taskId>A Bulk task and its progress (Get a task); --wait follows it until it settlesFree
rc bulk listThe tasks of your workspace, newest first, with --status (Task history)Free
rc bulk rows <taskId>A page of results, even while the task runs (Read task results by page); --all reads every result until nothing more will comeFree
rc bulk results <taskId>The results file of a settled task, CSV or NDJSON (Download task results)Free
rc bulk cancel <taskId>Stop a task: items that had not started are never charged (Cancel a task)Free
rc lists read <listId>A page of the members of a List (List members), with --kind, --page-size and --cursorFree
rc lists add <listId>Add people or companies to a List, from flags or a --signals-file of up to 1,000 (Add members)Per new member, as Add members: 1 or 2 credits. A member already on the List is free
rc lists export <listId>The List as CSV or NDJSON, to stdout or --out (Export a List)Free
rc usageThe credit balance, the rate limits and the credit limits of the API key (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.

Both searches take --area with a zone id from the area values, such as MR:EMEA or MC:DACH, comma-separated for several zones: it adds up with --country-code. rc search people also takes --connections-count as a range, such as 501- for more than 500 connections.

rc search companies and rc search fields companies call /v2/search/companies, which goes into maintenance on November 9, 2026, for a few weeks: use rc search organizations and rc search fields organizations instead. See Migrating company search to the new endpoint.

Examples

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

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 codeMeaning
0Success, including a not-found result (success: false, 0 credits)
1API error, including 402 (not enough credits), 403 (access denied: key permissions or a suspended workspace), a credit limit of the API key reached (key_credit_limit_reached) and a 429 still refused after the retries. With --wait, also a live task that ended errored, and a Bulk task that failed, is paused, or was still running when --max-wait ran out
2Usage error: a missing input, a bad value or two flags that cannot go together
3Authentication error: no API key, or a key the API refuses with 401
4Network error, request timeout, or a --wait on a live task 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. A credit limit of the API key is never retried: the daily limit reopens at 00:00 UTC, the monthly one on the 1st, and the total one when someone raises or resets it in API Keys.

Live tasks

rc fetch ... --live, rc contact email and rc contact phone return a task id at once: read it later with rc task <taskId>, which returns the task 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 task that ended errored exits 1. Results usually arrive within seconds but can take tens of minutes, so read the task later with rc task rather than waiting in a loop.

To block until a live fetch finishes, add --wait with a --timeout in seconds that leaves the task 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 task keeps running: read it with rc task.

Bulk

rc bulk create --file people.csv starts a Bulk task from a CSV, NDJSON or JSON file of up to 25,000 people, or from stdin with --file -. In a CSV, the header names the fields of each item, linkedinUrl, email, firstName, lastName, companyDomain, companyName and externalId, whatever their case or separators (first_name works too); other columns are left out and listed on stderr. --families takes profile (the default), contact_email and contact_phone, comma-separated, or check alone, the free check of each profile URL (see Check profiles in bulk), --type the kind of email (professional, personal or any), and --live reads each profile URL live. --task-name names the task in the history and --webhook-url receives its task.updated event.

The CLI sends an Idempotency-Key with each task. When the answer is lost, it prints that key: the same command with --idempotency-key and the same file starts and bills nothing twice.

With --wait, the CLI follows the task until it settles, with a progress bar on stderr at a terminal, and -o results.csv then writes the results (.ndjson for NDJSON). --max-wait stops following after that many seconds, 21,600 (6 hours) by default: the task keeps running, and rc bulk get <taskId> --wait follows it again.

rc bulk rows <taskId> --all writes every result as one JSON object per line as soon as it is ready, to stdout or to -o: it waits while the next item runs, and on a cancelled task it says on stderr that it waits for the items in flight, within the hour. rc bulk results <taskId> -o results.ndjson downloads the file of a settled task, streamed to disk and written under its name only once whole; --format csv or --format ndjson picks the format when the file name does not. Reading the results is free.

Bulk

rc bulk create --file people.csv --families profile,contact_email --wait -o results.csv

Lists

rc lists read <listId> reads a page of the members of a List: --kind picks all (the default), members or pending, --page-size the rows per page, and --cursor the next page. rc lists add <listId> adds one person or company from --url, --email, --first-name and --last-name with --company-domain or --company-name, or --domain on a companies List, or up to 1,000 Signals from a JSON array with --signals-file (- reads stdin). A Signal that matches no one waits as Pending Intake and costs nothing. rc lists export <listId> --out list.csv writes the List as CSV, and --fail-on-empty exits 1 when it has no member. --fields name,title,contact_email chooses the columns of the CSV, in order (Choose the columns). --format ndjson writes one JSON object per line instead, each member with its stored profile, its company and the columns your team added in the app, for a program to read: rc lists export <listId> --format ndjson | jq -c 'select(.kind == "member") | .person'.

Environment variables

VariableEffect
RC_API_KEYThe API key, ahead of the stored one
RC_BASE_URLThe API address (https://api.reversecontact.com by default)
RC_OUTPUTjson or human, whatever the terminal
RC_DEBUG=1Print the stack trace of an error
RC_NO_UPDATE_CHECK=1Turn 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 that rc search people and rc search organizations run before their 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, so it works as a quick check before a task.

How do I enrich a whole CSV file with the Reverse Contact CLI?

Run rc bulk create --file people.csv --wait -o results.csv. It sends up to 25,000 people in one Bulk task, follows the task until it settles and writes one result row per person. Each person costs what its unit call costs, only for what is found, and rc bulk rows --all reads the results while the task still runs.

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.

Last verified