Crustdata CLI - Crustdata Docs

The crustdata CLI puts the full API in your terminal: every endpoint is a typed command with real flags. It renders markdown tables when you’re looking and raw JSON when you’re piping, so the same commands serve you, your scripts, and your agents.

Quick start

Install

curl -fsSL https://static-assets.crustdata.com/cli/install.sh | sh

On Windows:

irm https://static-assets.crustdata.com/cli/install.ps1 | iex

The installer verifies checksums, puts the binary in ~/.crustdata/bin, and adds that directory to your PATH (set CRUSTDATA_NO_MODIFY_PATH=1 to skip). Open a new terminal, then upgrade later with crustdata upgrade.

Authenticate

crustdata auth login

Opens your browser: sign in, pick your team, and the CLI stores the resulting API key. No browser on the machine? --no-browser prints the sign-in URL and asks you to paste the redirect back. For CI and scripts, pipe a key in with crustdata auth login --with-token < key.txt, or set CRUSTDATA_API_KEY.

Run a command

crustdata company enrich --domains stripe.com --fields basic_info,headcount

Commands

Command	What it does
`company search / identify / enrich / reviews / suggest`	Firmographics, employee reviews, field suggestions
`person search / enrich / contacts / dev / suggest`	Profiles, contact details, dev-platform data
`job search / suggest`	Job listings from the indexed dataset
`social-post search / fetch`	Social posts by keyword, person, or company
`web search / fetch`	Real-time web search and page fetch
`batch <noun> <verb>`	Bulk jobs: submit, `--wait`, download JSONL results
`account credits / endpoints`	Balance and rate limits
`auth login / logout / status / token`	Authentication (browser sign-in or API key)
`docs / docs read / docs fs`	Search and read these docs from the terminal
`mcp install / list / remove`	Wire the Crustdata MCP into agent clients
`upgrade`	Update the CLI in place (checksum-verified)

Add --live to search or enrich to query the professional network in real time instead of the indexed dataset.

Filters

Search commands take repeatable --filter 'field op value' expressions that AND together:

crustdata company search \
  --filter 'headcount.total > 100' \
  --filter 'basic_info.region in US,EU' \
  --limit 25

Operators come straight from the API: = != < > =< => in not_in (.) [.]. For or logic and nested groups, pass a full JSON body with --input query.json (or --input - for stdin). Flags override matching body fields.

Every request command supports --dry-run (print the composed body without sending it, at no cost) and --example (print real request examples from the API spec). Tab completion knows the filter fields: run crustdata completion zsh to set it up.

Output

On a terminal: markdown tables. Piped: raw response JSON. Force either with --format json|md.
Filter JSON inline with the built-in --jq (no jq install needed): crustdata account credits --jq .account.credits
stdout carries data only; progress and hints go to stderr. Exit codes: 0 success, 1 API error, 2 usage error, 4 auth error.
Nothing auto-paginates, because pages cost credits. Follow next_cursor explicitly.

Examples

Every example below runs as written (tested against v0.1.3).

Companies

# Enrich one company
crustdata company enrich --domains stripe.com --fields basic_info,headcount

# Pull a single value out of the enrichment
crustdata company enrich --domains stripe.com --fields basic_info \
  --jq '.[0].matches[0].company_data.basic_info.name'

# Resolve a name to a company record
crustdata company identify --names "Stripe" --exact-match

# Indexed search: filters AND together
crustdata company search \
  --filter 'headcount.total > 10000' \
  --filter 'locations.country in United States' \
  --limit 2

# OR logic lives in a JSON body; flags still override fields like limit
echo '{"filters":{"op":"or","conditions":[
  {"field":"basic_info.primary_domain","type":"=","value":"stripe.com"},
  {"field":"basic_info.primary_domain","type":"=","value":"openai.com"}
]}}' | crustdata company search --input - --limit 3 --jq .total_count

# Live search against the professional network (note: different field names, page required)
crustdata company search --live --filter 'REGION in United States' --page 1

# Employee reviews for a company
crustdata company reviews --crustdata-company-id 631394

# Suggest valid values for a search field
crustdata company suggest country 'Uni'

People

# Indexed person search
crustdata person search \
  --filter 'basic_profile.location.country = United States' --limit 2

# Live person search: professional-network vocabulary, page required
crustdata person search --live \
  --filter 'CURRENT_TITLE in CEO' \
  --filter 'REGION in United States' --page 1

# Enrich a profile
crustdata person enrich \
  --professional-network-profile-urls https://www.linkedin.com/in/dvdhsu/

# Contact details (fields use dotted paths)
crustdata person contacts \
  --professional-network-profile-urls https://www.linkedin.com/in/dvdhsu/ \
  --fields contact.business_emails

# Dev-platform profile from a GitHub URL
crustdata person dev --profile-url https://github.com/rajnandan1

# Suggest values for a person search field
crustdata person suggest basic_profile.city 'San'

Jobs, posts, and the web

# Fuzzy-match job titles with the (.) operator
crustdata job search --filter 'job_details.title (.) engineer' --limit 2

# Social posts by keyword (supports OR/AND, up to 6 terms)
crustdata social-post search --keyword 'series B' --limit 2

# A company's recent posts
crustdata social-post fetch --company-domain stripe.com --limit 2

# Search the web in real time
crustdata web search --query 'crustdata'

Account and housekeeping

# Credit balance as a bare number
crustdata account credits --jq .account.credits

# Preview a bulk submission without spending anything
crustdata batch person contacts \
  --professional-network-profile-urls https://www.linkedin.com/in/dvdhsu/ \
  --fields contact.business_emails --dry-run

# Update the CLI in place
crustdata upgrade

Dry runs, spec examples, and completion

Nothing in this group spends credits or needs auth, except live value completion.

# See exactly what --filter compiles into, without sending it
crustdata company search --dry-run \
  --filter 'headcount.total > 10000' \
  --filter 'locations.country in United States' --limit 5

# Live mode composes the flat array shape instead of the condition tree
crustdata person search --dry-run --live \
  --filter 'CURRENT_TITLE in CEO' --page 1

# Watch flags override an --input body
echo '{"limit":100,"cursor":"abc"}' | \
  crustdata company search --input - --limit 5 --dry-run

# List the spec's ready-made request bodies, then print one
crustdata company search --example
crustdata company search --example=recently_funded_us_companies

# Chain: spec example as the body, your flags on top, preview before sending
crustdata company search --example=recently_funded_us_companies > /tmp/q.json
crustdata company search --input /tmp/q.json --limit 3 --dry-run

Tab completion, one-time setup per shell:

source <(crustdata completion zsh)   # or bash / fish / powershell

crustdata company search --filter 'head<TAB>      # headcount.* fields from the spec vocabulary
crustdata company search --live --filter '<TAB>   # vocabulary flips to REGION, COMPANY_HEADCOUNT, ...
crustdata company search --filter 'headcount.total <TAB>   # the 10 operators
crustdata company search --filter 'country in Uni<TAB>     # live values from the API (needs auth)

Named examples need the = form (--example=name); bare --example lists what’s available. Value completion makes a free autocomplete API call; offline or logged out it completes nothing, without an error.

Bulk jobs

crustdata batch person enrich --input people.json --wait --download

Submits the job, polls until it completes, and downloads the results as decompressed JSONL. Or fire-and-forget and come back later with crustdata batch status <id> and crustdata batch download <id>.

Search the docs

The CLI reads these docs over their public MCP server, so answers arrive where you’re already working. No authentication needed:

crustdata docs "how do credits work"        # full-text search with page links
crustdata docs read general/rate-limits     # print a whole page
crustdata docs fs -- tree /api-reference    # browse the docs as a filesystem

Set up the Crustdata MCP

crustdata mcp install wires the hosted Crustdata MCP server into your agent clients:

crustdata mcp install                # interactive picker
crustdata mcp install claude-code    # installs the Crustdata plugin (MCP + skills)
crustdata mcp install cursor windsurf
crustdata mcp list                   # per-client install state and auth mode
crustdata mcp remove cursor          # deletes only the crustdata entry

Supported targets: claude-code (plugin by default, --mcp-only for the bare server), cursor, vscode, windsurf, claude-desktop (via the mcp-remote bridge), and claude-web (printed manual steps, since connectors are account-level). Config edits are merge-preserving — only the crustdata entry is ever touched, and --dry-run prints the exact change without writing anything. Auth defaults to OAuth on first connect inside each client. For headless setups, --with-key bakes your stored API key into the client config (plaintext, with a loud warning), and --with-key=env writes a ${env:CRUSTDATA_API_KEY} reference instead.

For scripts and agents

Piped output is always raw JSON, with no TTY-detection surprises. --jq runs everywhere without dependencies, and --help on any command includes runnable examples. Agents can explore safely: --dry-run composes any request without spending credits.

Non-interactive authentication

The browser flow only triggers on a real terminal — when stdin is a pipe, the CLI never opens a browser, and the paste prompt only appears when you give it nothing else, so agents never hang on a hidden prompt. Pick one of three paths:

# 1. Environment variable: no login step, nothing written to disk.
#    Best for ephemeral sandboxes. Beats the config file when both exist.
export CRUSTDATA_API_KEY=cd_xxx

# 2. Stdin: stores the key in the config file, keeps it out of shell history
echo "$KEY" | crustdata auth login --with-token

# 3. Inline flag: one-shot, but the key lands in shell history
crustdata auth login --token cd_xxx

auth login validates the key against the API before saving and exits with code 4 on a bad key, so a broken credential fails at setup instead of mid-task. Check state anytime with crustdata auth status.

​Quick start

​Commands

​Filters

​Output

​Examples

​Companies

​People

​Jobs, posts, and the web

​Account and housekeeping

​Dry runs, spec examples, and completion

​Bulk jobs

​Search the docs

​Set up the Crustdata MCP

​For scripts and agents

​Non-interactive authentication

Quick start

Commands

Filters

Output

Examples

Companies

People

Jobs, posts, and the web

Account and housekeeping

Dry runs, spec examples, and completion

Bulk jobs

Search the docs

Set up the Crustdata MCP

For scripts and agents

Non-interactive authentication