Metadata-Version: 2.4
Name: datalegion-cli
Version: 1.1.1
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 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