> ## Documentation Index > Fetch the complete documentation index at: https://docs.databar.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > The Databar CLI lets you run enrichments, manage tables, and automate workflows directly from your terminal or AI agent. ## Installation ```bash theme={null} pip install databar ``` After installing, the `databar` command is available in your terminal. ```bash theme={null} databar --help databar --version ``` *** ## Authentication ```bash theme={null} # Save your API key (prompted securely) databar login # Or pass it directly databar login --api-key your-key-here # Verify your key databar whoami ``` Your key is saved to `~/.databar/config` with `600` permissions (owner read-only). You can also set the `DATABAR_API_KEY` environment variable — it takes priority over the config file: ```bash theme={null} export DATABAR_API_KEY=your-key-here ``` *** ## Output formats Every command supports `--format` with three options: | Flag | Output | Best for | | - | - | - | | `--format table` | Rich terminal table (default) | Human viewing | | `--format json` | Envelope JSON on stdout | Piping, scripting, AI agents | | `--format csv` | CSV to stdout or `--out file.csv` | Spreadsheets, data pipelines | `--format json` always prints one object on stdout: ```json theme={null} {"ok": true, "data": ...} {"ok": false, "error": {"code": "auth_invalid", "message": "...", "hint": "..."}} ``` Read the payload from `.data`. On failure, check `.error.code` and the exit code: | Exit | Meaning | | - | - | | 0 | Success | | 2 | Usage / bad args | | 3 | Auth (missing or invalid key) | | 4 | Not found | | 5 | Validation | | 1 | Other failure (rate limit, server, task failed, …) | `table ` and `task ` must be UUIDs (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Malformed identifiers fail client-side with exit `5` / `code: validation` (not a 404). `--out` paths are resolved; null bytes are rejected; a note is printed if the path leaves the current directory. ```bash theme={null} # Pipe JSON output to jq (note .data) databar enrich list --format json | jq '.data[].name' # Save rows to CSV databar table rows --format csv --out rows.csv ``` *** ## Enrichments ```bash List enrichments theme={null} databar enrich list databar enrich list --query "linkedin" databar enrich list --format json ``` ```bash Get enrichment details theme={null} # Shows parameters, response fields, pricing databar enrich get 123 databar enrich get 123 --format json ``` ```bash Run a single enrichment theme={null} # Submits and polls until complete databar enrich run 123 --params '{"email": "alice@example.com"}' # JSON output (pipe-friendly) databar enrich run 123 --params '{"email": "alice@example.com"}' --format json # Raw result without formatting databar enrich run 123 --params '{"email": "alice@example.com"}' --raw ``` ```bash Bulk run from CSV theme={null} # Input CSV must have column headers matching enrichment param names databar enrich bulk 123 --input leads.csv databar enrich bulk 123 --input leads.csv --format csv --out results.csv ``` ```bash Get parameter choices theme={null} # For select/multiselect parameters databar enrich choices 123 country databar enrich choices 123 country --query "united" databar enrich choices 123 country --page 2 --limit 100 ``` *** ## Waterfalls ```bash List waterfalls theme={null} databar waterfall list databar waterfall list --query "email" databar waterfall list --format json ``` ```bash Get waterfall details theme={null} databar waterfall get email_getter databar waterfall get email_getter --format json ``` ```bash Run a waterfall theme={null} # Uses the providers enabled by default (the "default" column in `waterfall get`) databar waterfall run email_getter \ --params '{"linkedin_url": "https://linkedin.com/in/alice"}' # Specify providers explicitly (comma-separated IDs) databar waterfall run email_getter \ --params '{"linkedin_url": "https://linkedin.com/in/alice"}' \ --providers 10,11 # With email verification databar waterfall run email_getter \ --params '{"linkedin_url": "https://linkedin.com/in/alice"}' \ --email-verifier 99 ``` ```bash Bulk run from CSV theme={null} databar waterfall bulk email_getter --input leads.csv databar waterfall bulk email_getter --input leads.csv --out results.csv ``` *** ## Tables ```bash List and create tables theme={null} databar table list databar table list --format json # Create empty table databar table create --name "My Leads" # Create with predefined columns databar table create --name "My Leads" --columns "email,name,company,linkedin_url" ``` ```bash Inspect a table theme={null} # List columns databar table columns databar table columns --format json # Get rows databar table rows databar table rows --page 2 --per-page 500 databar table rows --format csv --out rows.csv ``` ```bash Insert rows theme={null} # From inline JSON array databar table insert \ --data '[{"email":"alice@example.com","name":"Alice"}]' # From CSV file databar table insert --input data.csv # Auto-create unknown columns databar table insert --input data.csv --allow-new-columns # With deduplication databar table insert --input data.csv --dedupe-keys email # Multiple dedupe keys databar table insert --input data.csv --dedupe-keys "email,linkedin_url" ``` ```bash Update rows theme={null} # Rows must include an "id" field (the row UUID) databar table patch \ --data '[{"id":"row-uuid","name":"Updated Name"}]' # From CSV (must have "id" column) databar table patch --input updates.csv # Only fill empty cells (don't overwrite existing values) databar table patch --input updates.csv --no-overwrite ``` ```bash Upsert rows theme={null} # Insert or update matched by key column databar table upsert --key-col email \ --data '[{"email":"alice@example.com","name":"Alice"}]' # From CSV databar table upsert --key-col email --input data.csv ``` ```bash Table enrichments theme={null} # List enrichments configured on a table databar table enrichments # Add an enrichment to a table databar table add-enrichment \ --enrichment-id 123 \ --mapping '{"email": "email_column"}' # Run an enrichment on all table rows databar table run-enrichment --enrichment-id # Run only on empty rows databar table run-enrichment --enrichment-id --run-strategy empty_only ``` *** ## Tasks For long-running operations, tasks can be checked manually or polled until completion: ```bash Check task status theme={null} databar task get databar task get --format json ``` ```bash Poll until complete theme={null} # Blocks until the task finishes or times out (~5 minutes) databar task get --poll databar task get --poll --format json ``` *** ## AI agent usage The CLI is designed to be invoked by AI agents (Claude Code, Cursor, etc.) with `--format json` for machine-readable output: ```bash theme={null} # Self-discovery — agent finds the right enrichment databar enrich list --format json | jq '.data[] | select(.name | test("linkedin"; "i"))' # Get parameters for an enrichment databar enrich get 123 --format json # Run and get structured result databar enrich run 123 --params '{"email": "alice@example.com"}' --format json # Full table pipeline databar table rows --format json | jq '.data[].email' ``` Exit codes: `0` on success; `2` usage, `3` auth, `4` not found, `5` validation, `1` other. With `--format json`, both success and failure are one JSON object on stdout (`ok` / `data` or `error`). Table and task identifiers must be UUIDs — malformed values fail with validation (exit 5), not a 404. *** ## Environment variables | Variable | Description | | - | - | | `DATABAR_API_KEY` | Your Databar API key. Takes priority over `~/.databar/config`. | *** ## Source code The CLI is open source. View source, report issues, and contribute on GitHub. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.