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

# CLI

> The full Up2Data API from your terminal — enrich, search, Signals, and account as shell commands.

The `up2data` CLI puts the **entire Gateway API** in your shell. Every command maps 1:1 onto a `/v1/*` REST route and prints JSON on stdout, so it composes naturally with `jq`, pipes, and scripts.

```bash theme={null}
npx -y up2data login    # opens the browser, saves a key locally
npx -y up2data enrich profile --url https://linkedin.com/in/satyanadella --pretty
```

The same package also runs the [MCP server](/mcp-docs) for agents — one install covers both.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install -g up2data
  ```

  ```bash npx (no install) theme={null}
  npx -y up2data --help
  ```
</CodeGroup>

Requires Node 18+.

## Log in

```bash theme={null}
up2data login
```

This opens your browser to approve the device, then saves an API key to `~/.config/up2data/credentials.json` (mode `0600`). No browser available? `login` also accepts pasting a key from [API keys](https://up2data.ai/dash/keys).

```bash theme={null}
up2data whoami    # show active key source
up2data logout    # remove saved credentials
```

For CI or servers, skip `login` and set the environment variable instead:

```bash theme={null}
export UP2DATA_API_KEY="u2d_live_..."
```

`UP2DATA_API_KEY` always takes precedence over saved credentials.

## Usage

Commands follow `up2data <group> <action> [--flags]`:

```bash theme={null}
up2data enrich profile --url https://linkedin.com/in/satyanadella --pretty
up2data search people --filters '{"titles":["CTO"],"keywords":"fintech"}' --max-results 10
up2data account get --pretty
```

### Flags

| Flag                                          | Meaning                                                                                                  |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--url <url>`, `--max-results 10`, …          | Any flag becomes a request body field; kebab-case maps to snake\_case (`--max-results` → `max_results`). |
| `--filters '{…}'`                             | JSON values are parsed automatically — anything starting with `{` or `[`.                                |
| `--json '{…}'` / `--json @file` / `--json @-` | Provide the full request body as JSON, from an argument, a file, or stdin.                               |
| `--pretty`                                    | Pretty-print the JSON response.                                                                          |
| `--data-only`                                 | Print only `data` (omit `meta` — handy for piping).                                                      |
| `-h`, `--help`                                | Per-command help: summary, method, and API path.                                                         |

Repeated flags become arrays: `--title CTO --title CEO` → `"title": ["CTO", "CEO"]`.

### Exit codes & errors

Success exits `0` with JSON on stdout. API errors print the structured error to stderr and exit `1` — same error shapes as [REST](/errors).

## Commands

Same surface, same [credit costs](/concepts/credits), and same pay-on-success rules as the REST API.

### Enrich

```bash theme={null}
up2data enrich profile --url <linkedin-url>     # 1 credit on success
up2data enrich company --url <company-url>      # 1 credit on success
up2data enrich post --url <post-url>            # 1 credit on success
up2data enrich job --url <job-url>              # 1 credit on success
```

### Search

```bash theme={null}
up2data search people             --filters '{…}'   # or --search-url <url>
up2data search people-sales-nav   --filters '{…}'   # or --sales-nav-url <url>
up2data search companies          --filters '{…}'
up2data search companies-sales-nav --filters '{…}'
up2data search jobs               --filters '{…}'
up2data search posts              --filters '{…}'
```

Search accepts structured `filters` **or** a LinkedIn / Sales Nav URL — not both.

### Related data

```bash theme={null}
up2data profile activity          --url <profile-url>
up2data profile recommendations   --url <profile-url>
up2data company posts             --url <company-url>
up2data company insights          --url <company-url>    # 5 credits
up2data company headcount         --url <company-url>
up2data company jobs-count        --url <company-url>
up2data post comments             --url <post-url>
up2data post reactions            --url <post-url>
up2data post reposts              --url <post-url>
```

### Batch

```bash theme={null}
up2data batch create --json @batch.json    # free to create; items bill on resolution
up2data batch get --job-id <job_id>        # free to poll
```

### Signals

```bash theme={null}
up2data signal create --json '{
  "name": "Watch Satya",
  "schedule": {"interval": "1d"},
  "target": {"type": "profile", "linkedin_url": "https://linkedin.com/in/satyanadella"},
  "criteria": {"mode": "field_change", "fields": ["*"]}
}'
up2data signal bulk-create --json @signals.json
up2data signal list --status active --limit 20
up2data signal get --signal-id <id>
up2data signal update --signal-id <id> --json '{…}'
up2data signal delete --signal-id <id>
up2data signal pause --signal-id <id>       # or: up2data signals pause --tag <tag>
up2data signal resume --signal-id <id>      # or: up2data signals resume --tag <tag>
up2data signal check-now --signal-id <id>   # bills the underlying scrape
up2data signal test --signal-id <id>
up2data signal test-webhook --signal-id <id>
up2data signal triggers --signal-id <id>
up2data triggers list --since 2026-07-01
up2data triggers get --trigger-id <id>
up2data webhook-delivery get --delivery-id <id>
up2data signals usage --group-by day
```

### Account

```bash theme={null}
up2data account get       # balance and settings — free
up2data account update --json '{…}'
```

Run `up2data --help` for the always-current list straight from the binary.

## Scripting recipes

Pipe with `jq` — `--data-only` strips the `meta` envelope:

```bash theme={null}
# Names and headlines of the first 10 fintech CTOs
up2data search people \
  --filters '{"titles":["CTO"],"keywords":"fintech"}' \
  --max-results 10 --data-only \
  | jq -r '.results[] | "\(.full_name)\t\(.headline)"'
```

Enrich a file of profile URLs, one JSON line per profile:

```bash theme={null}
while read -r url; do
  up2data enrich profile --url "$url" --data-only
done < profiles.txt > enriched.jsonl
```

Check your balance before a large run:

```bash theme={null}
credits=$(up2data account get --data-only | jq '.credits_remaining')
echo "Credits left: $credits"
```

Body from stdin (works with any generator):

```bash theme={null}
echo '{"url": "https://linkedin.com/in/satyanadella"}' | up2data enrich profile --json @-
```

<Warning>
  Commands are billable — same credits as REST. Enrich and search charge on success; `signal check-now` bills the underlying scrape. `account get`, `batch get`, and Signal management are free.
</Warning>

## Configuration

| Variable           | Default                  | Purpose                              |
| ------------------ | ------------------------ | ------------------------------------ |
| `UP2DATA_API_KEY`  | —                        | API key; overrides saved credentials |
| `UP2DATA_BASE_URL` | `https://api.up2data.ai` | Gateway base URL                     |
| `UP2DATA_APP_URL`  | `https://up2data.ai`     | Dashboard URL used by `login`        |

Credentials file: `~/.config/up2data/credentials.json`.

## CLI vs MCP vs REST

| Use                                     | When                                                      |
| --------------------------------------- | --------------------------------------------------------- |
| **CLI**                                 | Shell scripts, quick lookups, cron jobs, piping into `jq` |
| **[MCP](/mcp-docs)**                    | AI agents — Claude, Cursor, VS Code call tools directly   |
| **[REST](/api-reference/introduction)** | Production pipelines and backend integrations             |

All three share the same keys, credits, rate limits, and pay-on-success semantics.