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

# CLI

> Official command-line interface for the Data Legion API. Enrich and search person and company data from the terminal. Designed for both human users and AI agents.

The official Data Legion CLI lets you enrich and search person and company data directly from the terminal. It's fully async, outputs JSON to stdout (logs to stderr), and works as both a human-friendly tool and an AI agent backend. AI coding agents like Claude Code, Cursor, OpenClaw, Cline, and Aider can call it directly as a shell tool.

## Installation

<CodeGroup>
  ```bash Homebrew theme={null}
  brew install datalegion-ai/tap/datalegion-cli
  ```

  ```bash pip theme={null}
  pip install datalegion-cli
  ```

  ```bash uv theme={null}
  uv pip install datalegion-cli
  ```
</CodeGroup>

Requires Python 3.11+.

## Authentication

Set your API key using the built-in encrypted config store or an environment variable.

<CodeGroup>
  ```bash Config (encrypted on disk) theme={null}
  datalegion-cli config set api_key legion_your_key_here
  ```

  ```bash Environment variable theme={null}
  export LEGION_API_KEY=legion_your_key_here
  ```
</CodeGroup>

## Person

### Enrichment

Look up a person by email, phone, social URL, name, or other identifiers.

```bash theme={null}
# By email
datalegion-cli person enrich --email jane.doe@example.com

# By phone
datalegion-cli person enrich --phone "+15551234567"

# By social URL
datalegion-cli person enrich --social-url https://linkedin.com/in/janedoe

# By name and company
datalegion-cli person enrich --name "Jane Doe" --company "Acme Corp"

# By first/last name with location context
datalegion-cli person enrich --first-name Jane --last-name Doe \
  --company Acme --city "San Francisco" --state california

# Return multiple matches with confidence scores
datalegion-cli person enrich --name "Jane Doe" --company Acme \
  --multiple --min-confidence high --limit 5

# Return specific fields only
datalegion-cli person enrich --email jane@example.com \
  --fields full_name,job_title,company_name

# Read input from stdin
echo '{"email": "jane@example.com"}' | datalegion-cli person enrich --stdin
```

**All person enrich flags:**

| Flag                | Description                                   |
| ------------------- | --------------------------------------------- |
| `--email` / `-e`    | Email address                                 |
| `--phone` / `-p`    | Phone number                                  |
| `--social-url`      | Social profile URL (e.g. LinkedIn)            |
| `--linkedin-id`     | LinkedIn numeric ID                           |
| `--legion-id`       | Legion ID                                     |
| `--email-hash`      | SHA-256, SHA-1, or MD5 email hash             |
| `--name` / `-n`     | Full name                                     |
| `--first-name`      | First name                                    |
| `--last-name`       | Last name                                     |
| `--company` / `-c`  | Company name or domain                        |
| `--title`           | Job title                                     |
| `--city`            | City                                          |
| `--state`           | State                                         |
| `--country`         | Country                                       |
| `--school`          | School name                                   |
| `--birth-date`      | Birth date (YYYY-MM-DD)                       |
| `--address`         | Full address string                           |
| `--postal-code`     | Postal/ZIP code                               |
| `--multiple` / `-m` | Return multiple matches                       |
| `--limit` / `-l`    | Max results (default: 2)                      |
| `--min-confidence`  | Minimum confidence: `high`, `moderate`, `low` |
| `--fields`          | Comma-separated fields to include             |
| `--exclude`         | Comma-separated fields to exclude             |
| `--required`        | Comma-separated required fields               |
| `--titlecase`       | Title-case text fields in response            |
| `--stdin`           | Read JSON payload from stdin                  |

### Search

Query people using SQL syntax. The query is a positional argument.

```bash theme={null}
datalegion-cli person search \
  "SELECT * FROM people WHERE job_title ILIKE '%engineer%' AND state = 'california'" \
  --limit 25
```

| Flag             | Description                        |
| ---------------- | ---------------------------------- |
| `--limit` / `-l` | Max results (default: 10)          |
| `--fields`       | Comma-separated fields to include  |
| `--exclude`      | Comma-separated fields to exclude  |
| `--titlecase`    | Title-case text fields in response |

## Company

### Enrichment

Look up a company by domain, name, ticker, social URL, or other identifiers.

```bash theme={null}
# By domain
datalegion-cli company enrich --domain google.com

# By ticker
datalegion-cli company enrich --ticker GOOGL

# By name
datalegion-cli company enrich --name "Alphabet Inc"

# By name with industry qualifier
datalegion-cli company enrich --name "Mercury" --industry "financial services"

# Return multiple matches
datalegion-cli company enrich --name Google --multiple --limit 5
```

**All company enrich flags:**

| Flag                | Description                                     |
| ------------------- | ----------------------------------------------- |
| `--domain` / `-d`   | Company domain                                  |
| `--name` / `-n`     | Company name                                    |
| `--ticker` / `-t`   | Stock ticker symbol                             |
| `--social-url`      | Social profile URL (e.g. LinkedIn company page) |
| `--linkedin-id`     | LinkedIn numeric ID                             |
| `--legion-id`       | Legion ID                                       |
| `--industry`        | Industry (narrows name matching)                |
| `--multiple` / `-m` | Return multiple matches                         |
| `--limit` / `-l`    | Max results (default: 2)                        |
| `--min-confidence`  | Minimum confidence: `high`, `moderate`, `low`   |
| `--fields`          | Comma-separated fields to include               |
| `--exclude`         | Comma-separated fields to exclude               |
| `--required`        | Comma-separated required fields                 |
| `--titlecase`       | Title-case text fields in response              |
| `--stdin`           | Read JSON payload from stdin                    |

### Search

Query companies using SQL syntax. The query is a positional argument.

```bash theme={null}
datalegion-cli company search \
  "SELECT * FROM companies WHERE industry = 'software development' AND legion_employee_count > 50" \
  --limit 20
```

| Flag             | Description                        |
| ---------------- | ---------------------------------- |
| `--limit` / `-l` | Max results (default: 10)          |
| `--fields`       | Comma-separated fields to include  |
| `--exclude`      | Comma-separated fields to exclude  |
| `--titlecase`    | Title-case text fields in response |

## Utilities

Utility commands are free and don't consume credits.

### Clean Fields

Normalize emails, phones, names, domains, and other fields. Pass a JSON payload as a positional argument or via stdin.

```bash theme={null}
# Positional JSON argument
datalegion-cli utility clean \
  '{"email": "  JANE.DOE+work@GMAIL.COM  ", "phone": "(555) 123-4567", "domain": "https://www.Google.com/about"}'

# From stdin
echo '{"email": "test@GMAIL.COM"}' | datalegion-cli utility clean --stdin
```

| Flag       | Description                          |
| ---------- | ------------------------------------ |
| `--stdin`  | Read JSON fields from stdin          |
| `--region` | Default phone region (default: `US`) |

### Hash Email

Generate privacy-preserving email hashes (SHA-256, SHA-1, MD5). The email is a positional argument.

```bash theme={null}
datalegion-cli utility hash jane@example.com
```

### Validate

Check data format and get cleaning suggestions before enrichment.

```bash theme={null}
datalegion-cli utility validate \
  --email "not-an-email" --phone "+15551234567" --domain "google.com"
```

| Flag           | Description               |
| -------------- | ------------------------- |
| `--email`      | Email to validate         |
| `--phone`      | Phone to validate         |
| `--name`       | Name to validate          |
| `--domain`     | Domain to validate        |
| `--social-url` | Social URL to validate    |
| `--company`    | Company name to validate  |
| `--ticker`     | Ticker symbol to validate |
| `--stdin`      | Read JSON from stdin      |

## Account

### Check Credit Balance

```bash theme={null}
datalegion-cli credits balance
```

### View Usage History

```bash theme={null}
datalegion-cli credits usage --from 2026-03-01 --to 2026-03-26
```

## Agent Integration

The CLI is designed for AI agent workflows. Claude Code, Cursor, OpenClaw, Cline, Aider, and other AI coding agents can invoke it as a shell tool — no MCP configuration needed. All structured output goes to stdout as JSON, while logs and progress indicators go to stderr, so agents and scripts can parse results directly.

```bash theme={null}
# Pipe to jq
datalegion-cli person enrich --email jane@example.com | jq '.full_name'

# Pipe from stdin
echo '{"email": "jane@example.com"}' | datalegion-cli person enrich --stdin

# Quiet mode (suppress all non-JSON output)
datalegion-cli person enrich --email jane@example.com --quiet
```

<Note>
  The CLI and [MCP server](/integrations/mcp-server) are complementary. Use MCP for native tool-call integration with AI assistants. Use the CLI when you need shell access, scripting, or want a zero-config option that any agent can call via `bash`.
</Note>

## Global Flags

| Flag               | Description             |
| ------------------ | ----------------------- |
| `--verbose` / `-v` | Enable debug logging    |
| `--quiet` / `-q`   | Suppress all log output |
| `--help`           | Display command help    |

## Auto-Update

The CLI monitors GitHub releases and can self-update.

```bash theme={null}
# Check for updates
datalegion-cli update --check

# Install updates
datalegion-cli update

# Show current version
datalegion-cli version
```

## Credits

CLI commands consume credits at the same rate as the corresponding REST API endpoints. Utility commands are free.

## Rate Limits

The same [rate limits](/api-reference/overview#rate-limiting) apply to CLI requests as to direct API calls.

## Resources

* [PyPI Package](https://pypi.org/project/datalegion-cli/)
* [GitHub Repository](https://github.com/datalegion-ai/datalegion-cli)
* [API Reference](/api-reference/overview)