enrich a CSV from the command line

You exported a CSV from your CRM, a conference badge scanner, a spreadsheet, or a database query. It has email addresses but not much else. You need names, titles, companies, industries, and phone numbers.

Here's how to enrich that CSV without leaving your terminal.

Prerequisites

$ brew install enrichcli/tap/enrichcli

$ enrich config set api_key ek_live_your_key_here

$ brew install jq

Step 1: Inspect Your CSV

First, see what you're working with:

$ head -5 leads.csv

name,email,company
John Smith,john@acme.com,
Sarah Chen,sarah@datadog.com,
Mike Johnson,mike@stripe.com,
Lisa Park,lisa@vercel.com,

You have names and emails. Company column is empty. You need to fill in the gaps.

Step 2: Extract Emails

Pull out just the email column for enrichment:

$ tail -n +2 leads.csv | cut -d',' -f2 > emails.txt

$ cat emails.txt
john@acme.com
sarah@datadog.com
mike@stripe.com
lisa@vercel.com

Step 3: Enrich Each Email

Basic: One at a Time

$ while read email; do
    enrich email "$email" --json
  done < emails.txt > enriched.jsonl

This creates a JSONL file (one JSON object per line) with full enrichment data for each email.

With Progress Tracking

$ total=$(wc -l < emails.txt)
$ count=0
$ while read email; do
    count=$((count + 1))
    echo "[$count/$total] Enriching $email..." >&2
    enrich email "$email" --json 2>/dev/null
  done < emails.txt > enriched.jsonl

With Error Handling

$ while read email; do
    result=$(enrich email "$email" --json 2>/dev/null)
    if [ $? -eq 0 ]; then
        echo "$result"
    else
        echo "{\"email\":\"$email\",\"error\":\"enrichment_failed\"}"
    fi
  done < emails.txt > enriched.jsonl

Step 4: Convert JSONL Back to CSV

Use jq to extract the fields you want and format as CSV:

$ cat enriched.jsonl | jq -r '
  [
    .person.name // "unknown",
    .email // .person.email // "unknown",
    .person.title // "",
    .company.name // "",
    .company.industry // "",
    .company.headcount // "",
    .person.location // ""
  ] | @csv
' > enriched.csv

Add a header:

$ echo "name,email,title,company,industry,headcount,location" > final.csv
$ cat enriched.csv >> final.csv

Result:

name,email,title,company,industry,headcount,location
"John Smith","john@acme.com","Software Engineer","Acme Corp","Manufacturing","50-100","Chicago, IL"
"Sarah Chen","sarah@datadog.com","Senior Engineer","Datadog","Cloud Monitoring","5000+","New York, NY"
"Mike Johnson","mike@stripe.com","Product Manager","Stripe","Financial Technology","8000+","San Francisco, CA"
"Lisa Park","lisa@vercel.com","Design Lead","Vercel","Developer Tools","500-1000","San Francisco, CA"

Complete One-Liner

If you want the whole thing as a single pipeline:

$ tail -n +2 leads.csv | cut -d',' -f2 | \
  while read email; do enrich email "$email" --json 2>/dev/null; done | \
  jq -r '[.person.name, .email, .person.title, .company.name, .company.industry, .company.headcount] | @csv' | \
  (echo "name,email,title,company,industry,headcount" && cat) > enriched.csv

Advanced: Domain Enrichment from Email

If you want richer company data, extract domains and enrich those separately:

$ tail -n +2 leads.csv | cut -d',' -f2 | cut -d'@' -f2 | sort -u > domains.txt

$ cat domains.txt
acme.com
datadog.com
stripe.com
vercel.com

$ while read domain; do
    enrich domain "$domain" --json 2>/dev/null
  done < domains.txt > companies.jsonl

Now you have detailed company profiles (tech stack, funding, revenue) alongside your person data.

Advanced: Parallel Enrichment

For large files, sequential enrichment is slow. Speed it up with GNU Parallel or xargs:

$ cat emails.txt | xargs -P 5 -I {} sh -c 'enrich email "{}" --json 2>/dev/null' > enriched.jsonl

Or with GNU Parallel:

$ cat emails.txt | parallel -j 5 'enrich email {} --json 2>/dev/null' > enriched.jsonl

Note: Be mindful of API rate limits when running parallel enrichments. 5 concurrent requests is usually safe.

Advanced: Merge Original CSV with Enriched Data

If you want to keep all original columns and append enriched columns:

#!/bin/bash
# merge-enriched.sh

INPUT="leads.csv"
OUTPUT="leads_enriched.csv"

# Print header
head -1 "$INPUT" | tr -d '\n'
echo ",title,industry,headcount,location"

# Process each row
tail -n +2 "$INPUT" | while IFS=',' read -r name email company rest; do
    # Enrich the email
    data=$(enrich email "$email" --json 2>/dev/null)

    if [ $? -eq 0 ]; then
        title=$(echo "$data" | jq -r '.person.title // ""')
        industry=$(echo "$data" | jq -r '.company.industry // ""')
        headcount=$(echo "$data" | jq -r '.company.headcount // ""')
        location=$(echo "$data" | jq -r '.person.location // ""')
    else
        title=""
        industry=""
        headcount=""
        location=""
    fi

    echo "$name,$email,$company,$title,$industry,$headcount,$location"
done > "$OUTPUT"

Tips for Batch Enrichment

1. Filter Before Enriching

Don't waste credits on free email domains — they have low match rates:

$ grep -v -E '@(gmail|yahoo|hotmail|outlook|aol)\.' emails.txt > professional_emails.txt

2. Deduplicate First

Remove duplicate emails before enriching:

$ sort -u emails.txt > unique_emails.txt

3. Check Your Credit Balance

Before enriching 5,000 emails, make sure you have enough credits:

$ enrich config show
Plan: Pro
Credits remaining: 847
Credits used this month: 153

4. Use Cached Results

enrichcli caches results server-side. If you're re-enriching contacts that were already enriched (by you or another user), the cached results are free and instant.

5. Save Raw JSON

Always save the raw JSONL output before converting to CSV. CSV loses nested data (tech stacks, experience arrays, etc.). Keep the JSONL as your source of truth:

$ ... > enriched.jsonl

$ cat enriched.jsonl | jq -r '[...fields...] | @csv' > for_crm_import.csv
$ cat enriched.jsonl | jq -r '[...other fields...] | @csv' > for_marketing.csv

6. Handle Large Files in Batches

For files with 10,000+ rows, process in batches to track progress and handle failures:

$ split -l 500 emails.txt batch_
$ for batch in batch_*; do
    echo "Processing $batch..."
    while read email; do
        enrich email "$email" --json 2>/dev/null
    done < "$batch" >> enriched.jsonl
    echo "Completed $batch ($(wc -l < enriched.jsonl) total)"
done
$ rm batch_*

Example: Full Pipeline

Here's a complete, production-ready script:

#!/bin/bash
set -euo pipefail

INPUT="${1:?Usage: $0 input.csv}"
OUTPUT="${INPUT%.csv}_enriched.csv"
RAW="${INPUT%.csv}_enriched.jsonl"

echo "=== CSV Enrichment Pipeline ==="
echo "Input: $INPUT"

# Extract and clean emails
tail -n +2 "$INPUT" | cut -d',' -f2 | \
  grep -E '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' | \
  grep -v -E '@(gmail|yahoo|hotmail|outlook|aol)\.' | \
  sort -u > /tmp/to_enrich.txt

total=$(wc -l < /tmp/to_enrich.txt)
echo "Emails to enrich: $total"

# Enrich
count=0
while read email; do
    count=$((count + 1))
    printf "\r[%d/%d] %s" "$count" "$total" "$email" >&2
    enrich email "$email" --json 2>/dev/null || true
done < /tmp/to_enrich.txt > "$RAW"

echo ""
echo "Raw output: $RAW"

# Convert to CSV
echo "name,email,title,company,industry,headcount,location" > "$OUTPUT"
cat "$RAW" | jq -r '
  [
    .person.name // "",
    .email // "",
    .person.title // "",
    .company.name // "",
    .company.industry // "",
    .company.headcount // "",
    .person.location // ""
  ] | @csv
' >> "$OUTPUT"

enriched=$(tail -n +2 "$OUTPUT" | wc -l)
echo "Enriched CSV: $OUTPUT ($enriched records)"
echo "Done."

Usage:

$ chmod +x enrich-csv.sh
$ ./enrich-csv.sh leads.csv