Skip to main content

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 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 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
  • Search warnings: when search or discover flags one of your filters (for example an industry name no stored value matches), the API's explanation is printed on stderr as search warning: ...; stdout stays JSON
  • Encrypted config: API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
  • Auto-update: checks PyPI for a newer release 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

Sign in with your Data Legion account (admin or developer role) and the CLI stores a key for this machine:

datalegion-cli login                 # opens a sign-in link; confirm the code it shows
datalegion-cli login --team-id 7     # when your account has several teams
datalegion-cli login --no-browser    # headless: prints the link to open on another device

The key belongs to this machine, named with a random id (cli- plus 8 hex characters) that the CLI generates on first login and keeps in its config, so nothing about the machine (such as its hostname) is sent. Pass --device <name> for a readable label instead. Signing in again replaces it, and you can disconnect it from Connected Apps in the dashboard.

Or set an API key yourself (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 The running Python is the formula's own venv under Homebrew's Cellar brew upgrade
github Set via config Downloads .whl from GitHub release
git An editable install from a git checkout (its direct_url.json) git pull --ff-only + uv sync in that checkout
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 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"

# By NPI (10-digit National Provider Identifier)
datalegion-cli person enrich --npi 1234567893

# Minimum confidence
datalegion-cli person enrich --email john@example.com --min-confidence high

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

Search with exactly one of --filters, --sql or --es-query (a positional query still works: SQL, or a query object when it is JSON).

# Filters on the record's own field names: a value or a list (any of them), {"gte": .., "lte": ..}, {"exists": true}
datalegion-cli person search --filters '{"job_title": ["vp of sales", "head of sales"], "state_code": "TX"}' --limit 5

# Groups and Boolean keywords
datalegion-cli person search --filters '{"and": [{"keywords": "(\"data engineer\" OR analyst) AND python NOT intern"}, {"or": [{"state_code": "TX"}, {"city": "boston"}]}]}' --limit 10

# SQL, or a query object in the Elasticsearch query syntax
datalegion-cli person search --sql "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
datalegion-cli person search --es-query '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100

For deep paging, pass each page's next_cursor back with --cursor; the last page has none. Company search takes the same inputs.

datalegion-cli person search --filters '{"state_code": "OH"}' --limit 100 --cursor "<next_cursor from the last page>"

count takes what search takes and prints how many records match, rounded, without returning any. It is free and works with zero credits left: it needs an active plan that includes search (10 a minute and 100 an hour; 5 and 30 on a free trial). Fields that identify one record (ids, names, emails, phones, URLs, domains, tickers) are refused: use enrich for one record.

datalegion-cli person count --filters '{"job_title": "nurse practitioner", "state_code": "TX"}'
# {"total": 16000, "total_status": "about"}

total_status is about, at_least (counting ran out of time: a lower bound) or under (fewer than 10).

Person Discovery (Beta)

# Natural-language search
datalegion-cli person discover "software engineers in San Francisco who know Rust" --limit 10

For the next page, pass the last page's next_cursor with --cursor and the same query: it reruns the same search. Company discover takes it too.

query="software engineers in San Francisco who know Rust"
cursor=""
while :; do
  # A failed page (a 429, 402 or 403) prints its error and stops the loop
  page=$(datalegion-cli person discover "$query" --limit 100 ${cursor:+--cursor} ${cursor:+"$cursor"}) || { printf '%s\n' "$page" >&2; break; }
  printf '%s\n' "$page" | jq -r '.matches[].person.legion_id'
  cursor=$(printf '%s\n' "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
  sleep 6  # Discover answers 10 requests a minute
done
[ -n "$cursor" ] && echo "stopped early; resume with --cursor $cursor" >&2

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"
datalegion-cli company search --filters '{"industry": "software development", "locations.city": "austin", "locations.primary": true}'
datalegion-cli company search --sql "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
datalegion-cli company count --filters '{"industry": "banking", "locations.country_code": "GB"}'

Company Discovery (Beta)

# Natural-language search
datalegion-cli company discover "fintech startups in New York with under 50 employees"

Utility Commands

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

# Report a data issue on a record (no credit cost; include --correct or --comment)
datalegion-cli utility report person --legion-id abc123 --issue-type outdated \
    --issue-level field --field job_title --observed "CTO" --correct "CEO"

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 john@example.com | jq '.matches[0].person.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": "..."}

Sandbox

Try commands without spending credits: --sandbox (or LEGION_SANDBOX=1, or datalegion-cli config set sandbox true) makes enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.

datalegion-cli --sandbox person enrich --email anyone@example.com

Global Flags

Flag Description
--verbose / -v Enable debug logging to stderr
--quiet / -q Suppress all log output
--sandbox Return sample records from enrich, search and discover, using no credits
--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

Metadata

Release files for datalegion-cli 1.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for datalegion-cli 1.10.0
File Size Uploaded Provenance Actions
datalegion_cli-1.10.0.tar.gz 39.7 kB Without provenance Details for datalegion_cli-1.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for datalegion-cli 1.10.0
File Interpreter ABI Platform Actions
datalegion_cli-1.10.0-py3-none-any.whl Python 3 none any Details for datalegion_cli-1.10.0-py3-none-any.whl

Total release size: 70.5 kB

Release files / datalegion_cli-1.10.0.tar.gz

Download URL datalegion_cli-1.10.0.tar.gz
Size 39.7 kB
Tags Source
SHA-256 checksum
How to use checksums
371422500b7b4d17fcf06e6b716f12aee0bf452118005585fc6eb2050df70a61
BLAKE2b-256 checksum
How to use checksums
f7d4fae623a019ac0c22ee04bfbf27dca4e495767b287fa066e60f31b64c4389
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / datalegion_cli-1.10.0-py3-none-any.whl

Download URL datalegion_cli-1.10.0-py3-none-any.whl
Size 30.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a9d8b9074ec5a7e941426ef7c188d02b2fed469c62237ab2a79a95e936fdb62
BLAKE2b-256 checksum
How to use checksums
195ae51a22e20d3b836558f74bcb249b6cd3b4ce6917a961462bdd2212fca758
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for datalegion-cli 1.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page