datalegion-cli 1.1.0

CLI for the Data Legion API — agent-friendly, fully async

datalegion-cli

The official command-line interface for the Data Legion 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.

pip install datalegion-cli
datalegion-cli config set api_key legion_your_key_here
datalegion-cli person enrich --email [e-mail]

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

brew install datalegion-ai/tap/datalegion-cli

From PyPI (or private index)

uv pip install datalegion-cli

Or with pip:

pip install datalegion-cli

To install from a private index:

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

From GitHub release

Download the .whl from the latest release and install:

uv pip install datalegion_cli-*.whl

From source

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

Configuration

Set your API key (stored encrypted on disk):

datalegion-cli config set api_key legion_your_key_here

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

export LEGION_API_KEY=legion_your_key_here

Other config options

# 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

# By email
datalegion-cli person enrich --email [e-mail]

# 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 [e-mail] --multiple --min-confidence high

# Select specific fields
datalegion-cli person enrich --email [e-mail] --fields "full_name,emails,phones"

Person search

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

Company enrichment

# 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

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

Utility commands

# Clean and normalize fields
datalegion-cli utility clean '{"email": "[e-mail]", "phone": "[phone]"}'

# Hash an email for privacy-preserving lookups
datalegion-cli utility hash [e-mail]

# Validate fields before enrichment
datalegion-cli utility validate --email "[e-mail]" --phone "[phone]"

Credits

# Check balance
datalegion-cli credits balance

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

Other commands

# 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:

# All output is JSON to stdout — parse it directly
datalegion-cli person enrich --email [e-mail] | jq '.matches[0].full_name'

# Pipe JSON payloads via stdin
echo '{"email":"[e-mail]","company":"Acme"}' | datalegion-cli person enrich --stdin

# Suppress logs with --quiet (only JSON on stdout)
datalegion-cli --quiet person enrich --email [e-mail]

# 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

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

# Build wheel
uv build

License

MIT