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"
# SQL-based search
datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5

query can also be an Elasticsearch-style query object as JSON (bool, term, terms, match, match_phrase, range, exists, prefix, wildcard, nested), on the response's own field names. For deep paging, pass each page's next_cursor back with --cursor; the last page has none. Company search takes both too.

datalegion-cli person search '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100
datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor "<next_cursor from the last page>"

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"
# SQL-based search
datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"

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.9.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.9.0
File Size Uploaded Provenance Actions
datalegion_cli-1.9.0.tar.gz 38.1 kB Without provenance Details for datalegion_cli-1.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 67.4 kB

Release files / datalegion_cli-1.9.0.tar.gz

Download URL datalegion_cli-1.9.0.tar.gz
Size 38.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2bdcc370de78d34531a6a74a02e3746f39003198b7a4eb916152a75f69f94d8b
BLAKE2b-256 checksum
How to use checksums
80b904789b263242385efc56e1aacd7f00509bdff6c27880623e6faae5cef510
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.9.0-py3-none-any.whl

Download URL datalegion_cli-1.9.0-py3-none-any.whl
Size 29.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e427aeca0247f097e38348810594ee7d5fa4317722167a63f16211d5f7b98ba
BLAKE2b-256 checksum
How to use checksums
79b4e023797367d23d3c848640a6d27d1104dfdb8cd1f91d1b4682b3910a4ce0
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.9.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