> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crustdata CLI

> The Crustdata API from your terminal: search, identify, and enrich companies and people, run bulk jobs, and pipe clean JSON into anything.

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

<Steps>
  <Step title="Install">
    ```bash theme={"theme":"vitesse-black"}
    curl -fsSL https://static-assets.crustdata.com/cli/install.sh | sh
    ```

    On Windows:

    ```powershell theme={"theme":"vitesse-black"}
    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`.
  </Step>

  <Step title="Authenticate">
    ```bash theme={"theme":"vitesse-black"}
    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`.
  </Step>

  <Step title="Run a command">
    ```bash theme={"theme":"vitesse-black"}
    crustdata company enrich --domains stripe.com --fields basic_info,headcount
    ```
  </Step>
</Steps>

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

```bash theme={"theme":"vitesse-black"}
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.

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

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

```bash theme={"theme":"vitesse-black"}
# 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

```bash theme={"theme":"vitesse-black"}
# 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

```bash theme={"theme":"vitesse-black"}
# 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

```bash theme={"theme":"vitesse-black"}
# 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.

```bash theme={"theme":"vitesse-black"}
# 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:

```bash theme={"theme":"vitesse-black"}
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)
```

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

## Bulk jobs

```bash theme={"theme":"vitesse-black"}
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:

```bash theme={"theme":"vitesse-black"}
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](/for-agents/mcp) into your agent clients:

```bash theme={"theme":"vitesse-black"}
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:

```bash theme={"theme":"vitesse-black"}
# 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`.


## Related topics

- [Rate limits](/general/rate-limits.md)
- [Crustdata for Recruiting](/recruiting/overview.md)
- [MCP Server](/for-agents/mcp.md)
- [Claude Code plugin](/for-agents/claude-plugin.md)
- [Company Identify](/company-docs/identify/introduction.md)