Metadata-Version: 2.4
Name: datalegion-cli
Version: 1.1.0
Summary: CLI for the Data Legion API — agent-friendly, fully async
Project-URL: Homepage, https://www.datalegion.ai
Project-URL: Documentation, https://www.datalegion.ai/docs
Project-URL: Repository, https://github.com/datalegion-ai/datalegion-cli
Project-URL: Issues, https://github.com/datalegion-ai/datalegion-cli/issues
Author-email: Data Legion <engineering@datalegion.ai>
License-Expression: MIT
Keywords: b2b,cli,company-enrichment,contact-data,data-enrichment,datalegion,enrichment,person-enrichment
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography>=44.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: rich>=13.9.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# datalegion-cli

The official command-line interface for the [Data Legion](https://www.datalegion.ai) API. Built for both humans and AI agents.

Look up people and companies by email, phone, name, domain, LinkedIn, or ticker symbol. Search across 1.5B+ contacts and 200M+ companies using SQL syntax. Clean, hash, and validate data fields before or after enrichment. Track credit usage and manage your configuration — all from the terminal.

```bash
pip install datalegion-cli
datalegion-cli config set api_key legion_your_key_here
datalegion-cli person enrich --email john@example.com
```

## Features

- **Fully async** — async from entry point to HTTP client, powered by `asyncio` and `httpx`
- **Agent-friendly** — all output is JSON to stdout, logs go to stderr, supports `--stdin` for piping
- **Encrypted config** — API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
- **Auto-update** — checks GitHub releases and self-updates via Homebrew, GitHub release, git pull, or pip/uv
- **Multiple install methods** — Homebrew, GitHub release, pip/uv (with private index support), or from source

## Installation

### Homebrew

```bash
brew install datalegion-ai/tap/datalegion-cli
```

### From PyPI (or private index)

```bash
uv pip install datalegion-cli
```

Or with pip:

```bash
pip install datalegion-cli
```

To install from a private index:

```bash
uv pip install datalegion-cli --extra-index-url https://your-private-index.com/simple
```

### From GitHub release

Download the `.whl` from the [latest release](https://github.com/datalegion-ai/datalegion-cli/releases/latest) and install:

```bash
uv pip install datalegion_cli-*.whl
```

### From source

```bash
git clone https://github.com/datalegion-ai/datalegion-cli.git
cd datalegion-cli
uv sync
```

## Configuration

Set your API key (stored encrypted on disk):

```bash
datalegion-cli config set api_key legion_your_key_here
```

Or via environment variable (takes precedence over file config):

```bash
export LEGION_API_KEY=legion_your_key_here
```

### Other config options

```bash
# Set the API base URL
datalegion-cli config set api_base_url https://api.datalegion.ai

# Set install method for auto-update (brew, github, git, or pip)
datalegion-cli config set install_method brew

# View all config
datalegion-cli config list

# Show config file path
datalegion-cli config path
```

Config is stored at `~/.datalegion/config.toml`. Override the location with `LEGION_CONFIG_DIR`.

### Install method detection

The `update` command auto-detects how the CLI was installed:

| Method | Detection | Update strategy |
|--------|-----------|-----------------|
| `brew` | `brew list` finds the formula | `brew upgrade` |
| `github` | Set via config | Downloads `.whl` from GitHub release |
| `git` | `.git` directory in parent tree | `git pull --ff-only` + `uv sync` |
| `pip` | Default fallback | `uv pip install --upgrade` |

You can override detection by setting `install_method` in config. For pip installs from a private index, set the `LEGION_PIP_INDEX_URL` environment variable.

## Usage

### Person enrichment

```bash
# By email
datalegion-cli person enrich --email john@example.com

# By name + company
datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "NYC"

# By LinkedIn
datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"

# Multiple results with minimum confidence
datalegion-cli person enrich --email john@example.com --multiple --min-confidence high

# Select specific fields
datalegion-cli person enrich --email john@example.com --fields "full_name,emails,phones"
```

### Person search

```bash
# SQL-based search
datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
```

### Company enrichment

```bash
# By domain
datalegion-cli company enrich --domain google.com

# By ticker symbol
datalegion-cli company enrich --ticker AAPL

# By name with industry context
datalegion-cli company enrich --name "Stripe" --industry "Financial Services"
```

### Company search

```bash
# SQL-based search
datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
```

### Utility commands

```bash
# Clean and normalize fields
datalegion-cli utility clean '{"email": "John.Doe+tag@gmail.com", "phone": "(555) 123-4567"}'

# Hash an email for privacy-preserving lookups
datalegion-cli utility hash john@example.com

# Validate fields before enrichment
datalegion-cli utility validate --email "test@example.com" --phone "+15551234567"
```

### Credits

```bash
# Check balance
datalegion-cli credits balance

# View usage history
datalegion-cli credits usage --from 2026-01-01 --to 2026-03-01
```

### Other commands

```bash
# Check for updates
datalegion-cli update --check

# Self-update
datalegion-cli update

# Show version
datalegion-cli version
```

## Agent / automation usage

The CLI is designed to be called by AI agents and scripts. Key patterns:

```bash
# All output is JSON to stdout — parse it directly
datalegion-cli person enrich --email john@example.com | jq '.matches[0].full_name'

# Pipe JSON payloads via stdin
echo '{"email":"john@example.com","company":"Acme"}' | datalegion-cli person enrich --stdin

# Suppress logs with --quiet (only JSON on stdout)
datalegion-cli --quiet person enrich --email john@example.com

# Errors are also JSON
datalegion-cli person enrich --email bad 2>/dev/null
# {"ok": false, "error": "bad_request", "message": "..."}
```

## Global flags

| Flag | Description |
|------|-------------|
| `--verbose` / `-v` | Enable debug logging to stderr |
| `--quiet` / `-q` | Suppress all log output |
| `--help` | Show help for any command |

## Development

```bash
# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

# Build wheel
uv build
```

## License

MIT