ravn
Integrations · CSV

Enrich any CSV from the command line

Run npx ravn enrich leads.csv --tool validate_email --column Email and you get leads.enriched.csv with every original column plus rw_* result columns. It works with any tool and any spreadsheet or CRM that exports CSV.

Start free: 1,000 lookups Read the docs

Setup

From file to enriched file

  1. / 01

    Sign in once

    npx ravn login sends an email code and saves your key to ~/.config/ravn. Check with npx ravn whoami. In CI, set RAVN_API_KEY instead.

  2. / 02

    Pick a tool

    npx ravn tools lists all 25 with their inputs. Most list jobs use validate_email, search_business_email_by_name, scrape_website or domain_to_company. The first three are our own checks; domain_to_company and other people/company tools run on your own provider key (ravn keys add pdl).

  3. / 03

    Map columns

    For a one-input tool use --column. For several inputs use --map field=Column,field=Column. The CLI stops with a list of real column names if one does not match.

  4. / 04

    Dry-run

    Add --dry-run. It reports the row count, the cost per row and what you have left this window, and spends nothing.

  5. / 05

    Run and resume

    Drop --dry-run. Progress is saved every 25 rows; if you stop it, run the same command to continue. If the 5-hour window fills up it waits for the reset, unless you pass --no-wait.

Commands

Every flag you will use

# Verify emails
npx ravn enrich leads.csv --tool validate_email --column Email

# Find work emails from name + company website
npx ravn enrich leads.csv --tool search_business_email_by_name \
  --map name=Name,company=Website --out leads.found.csv

# Try the first 50 rows before committing to the whole file
npx ravn enrich leads.csv --tool scrape_website --column Domain --limit 50

# Start again from row 1, ignoring saved progress
npx ravn enrich leads.csv --tool validate_email --column Email --restart

# Don't wait for the window to reset; mark remaining rows instead
npx ravn enrich leads.csv --tool validate_email --column Email --no-wait

What gets added

Original columns are kept in order. Result fields are prefixed so they never collide with yours.

ColumnMeaning
rw_statusok, not_found, error, or dropped if the run stopped on limits or a missing provider key.
rw_verdictFor email checks, the verdict: valid, invalid, risky or unknown
rw_errorError code such as invalid_input, empty on success
rw_<field>Each result field, for example rw_risk_score, rw_reason, rw_email, rw_confidence

Exit codes for scripts: 0 ok, 1 error, 2 usage, 3 auth, 4 rate limited, 5 provider key. See the CLI docs.

FAQ

Common questions.

All questions →

Does the CLI upload my whole file anywhere?

No. It reads the file locally and sends only the mapped field values for each row to the API. The other columns never leave your machine.

Why do some rows say dropped?

The run hit a 429 (window used up, with --no-wait) or a 403 (a people or company tool with no provider key connected) and marked the remaining rows rather than failing silently. Fix the limit or connect the key, then rerun with --restart, or rerun just those rows from a filtered file.

Do misses cost anything in a big file?

No. Rows that come back not_found give the lookup back, so you pay only for rows with data. The dry-run shows the most a run could cost.

Can I pipe the CLI into other scripts?

Yes. Single tool calls print JSON when output is piped, for example npx ravn validate_email --email jane@acme.com | jq .results.status, and the exit codes tell a script what went wrong.

More in integrations

Every page uses the same account, plan and tools. See pricing →