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

# Pipecorn CLI

> Search leads and accounts, enrich contacts in bulk from CSV, manage lists, and stream buying signals to a webhook, all from your terminal or a shell script.

`pipecorn` is the command-line interface for Pipecorn. It wraps the
[REST API](/api-reference/main-use-cases) so you can run searches, enrichments,
list operations, and signal streams from a terminal, a cron job, or CI, with
JSON, CSV, or table output and structured exit codes.

Source and issues: [github.com/Pipecorn/cli-pipecorn](https://github.com/Pipecorn/cli-pipecorn).
Package: [`@pipecorn/cli`](https://www.npmjs.com/package/@pipecorn/cli) on npm.

## Install

<Tabs>
  <Tab title="npx (no install)">
    ```sh theme={null}
    npx @pipecorn/cli --help
    ```
  </Tab>

  <Tab title="npm (global)">
    ```sh theme={null}
    npm install -g @pipecorn/cli
    ```
  </Tab>

  <Tab title="Homebrew (macOS)">
    ```sh theme={null}
    brew tap pipecorn/tap
    brew trust pipecorn/tap
    brew install pipecorn
    ```

    `brew trust` is required once per machine: since Homebrew 6.0, formulae and
    casks from third-party taps are not loaded until you opt in. On Linux and
    Windows, install from npm.
  </Tab>
</Tabs>

## Authenticate

Get an API key at [app.pipecorn.com/settings/apis/keys](https://app.pipecorn.com/settings/apis/keys), then either save it or export it:

```sh theme={null}
pipecorn login pk_live_xxx
# or
export PIPECORN_API_KEY=pk_live_xxx
pipecorn whoami
```

Credentials are stored at `~/.config/pipecorn/credentials.json` with mode
`0600`. Precedence, highest first: `--api-key` on any command, then the
`PIPECORN_API_KEY` environment variable, then the saved file.

## Quick examples

```sh theme={null}
# Preview an account search (synchronous, free)
pipecorn accounts search --preview --keyword '"sales agency"' --company-size 11-50

# Start an async lead search and poll until it finishes
JOB=$(pipecorn leads search --job-titles 'Head of Sales' --limit 50 --format json | jq -r .id)
pipecorn jobs status "$JOB" --watch

# Bulk-enrich contacts from CSV (async; prints enrichment_id)
pipecorn contacts enrich --batch leads.csv --enrichment email \
  --webhook-url https://my.app/webhooks/pipecorn

# Dry-run to see the credit cost first
pipecorn contacts enrich --batch leads.csv --enrichment phone --dry-run

# Export a list to CSV
pipecorn lists export <list-id> -o list.csv

# Buying signals streamed to a webhook
pipecorn signals hiring --webhook-url https://my.app/hook \
  --selected-titles 'Account Executive' --published-date last_7_days
```

See the [command reference](/cli/commands) for every command and flag.

## Output and exit codes

`--format json|csv|table` selects the output format. The default is `table`
on a TTY and `json` otherwise, so pipes work without flags. `-o file.csv`
writes to disk instead of stdout. Errors go to stderr, and the exit code
identifies the failure class:

| Code | Meaning                         |
| ---- | ------------------------------- |
| `0`  | Success                         |
| `1`  | Pipecorn API error              |
| `2`  | Invalid input                   |
| `3`  | Authentication                  |
| `4`  | Rate limit                      |
| `5`  | Credits or plan limit exhausted |

Exit code `5` covers both an empty enrichment credit balance and an exhausted
extraction quota. They are different things with different fixes; see
[Credits vs limits](/api-reference/credits-vs-limits). Use `--format json` to
read the underlying API error and its `code` field.

## Configuration

```sh theme={null}
pipecorn config list
pipecorn config set base_url https://staging.pipecorn.com/api/v2
pipecorn config set default_format json
pipecorn config get base_url
```

Config lives at the platform's standard XDG location,
`~/.config/pipecorn/config.json` on Linux and macOS.