CLI Reference

Installation

pip install databar

After installing, the databar command is available in your terminal.

databar --help
databar --version

Authentication

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

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:

{"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 <uuid> and task <task-id> 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.

# Pipe JSON output to jq (note .data)
databar enrich list --format json | jq '.data[].name'

# Save rows to CSV
databar table rows <uuid> --format csv --out rows.csv

Enrichments

databar enrich list
databar enrich list --query "linkedin"
databar enrich list --format json

# Shows parameters, response fields, pricing
databar enrich get 123
databar enrich get 123 --format json

# 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

# 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

# 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

databar waterfall list
databar waterfall list --query "email"
databar waterfall list --format json

databar waterfall get email_getter
databar waterfall get email_getter --format json

# Uses all available providers by default
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

databar waterfall bulk email_getter --input leads.csv
databar waterfall bulk email_getter --input leads.csv --out results.csv

Tables

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"

# List columns
databar table columns <uuid>
databar table columns <uuid> --format json

# Get rows
databar table rows <uuid>
databar table rows <uuid> --page 2 --per-page 500
databar table rows <uuid> --format csv --out rows.csv

# From inline JSON array
databar table insert <uuid> \
  --data '[{"email":"alice@example.com","name":"Alice"}]'

# From CSV file
databar table insert <uuid> --input data.csv

# Auto-create unknown columns
databar table insert <uuid> --input data.csv --allow-new-columns

# With deduplication
databar table insert <uuid> --input data.csv --dedupe-keys email

# Multiple dedupe keys
databar table insert <uuid> --input data.csv --dedupe-keys "email,linkedin_url"

# Rows must include an "id" field (the row UUID)
databar table patch <uuid> \
  --data '[{"id":"row-uuid","name":"Updated Name"}]'

# From CSV (must have "id" column)
databar table patch <uuid> --input updates.csv

# Only fill empty cells (don't overwrite existing values)
databar table patch <uuid> --input updates.csv --no-overwrite

# Insert or update matched by key column
databar table upsert <uuid> --key-col email \
  --data '[{"email":"alice@example.com","name":"Alice"}]'

# From CSV
databar table upsert <uuid> --key-col email --input data.csv

# List enrichments configured on a table
databar table enrichments <uuid>

# Add an enrichment to a table
databar table add-enrichment <uuid> \
  --enrichment-id 123 \
  --mapping '{"email": "email_column"}'

# Run an enrichment on all table rows
databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>

# Run only on empty rows
databar table run-enrichment <uuid> --enrichment-id <id> --run-strategy empty_only

Tasks

For long-running operations, tasks can be checked manually or polled until completion:

databar task get <task-id>
databar task get <task-id> --format json

# Blocks until the task finishes or times out (~5 minutes)
databar task get <task-id> --poll
databar task get <task-id> --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:

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

databar-ai/databar-python

The CLI is open source. View source, report issues, and contribute on GitHub.

Getting Started

Overview

SDKs

Workspace

Tables

Headless

User

Installation

Authentication

Output formats

Enrichments

Waterfalls

Tables

Tasks

AI agent usage

Environment variables

Source code

databar-ai/databar-python

​Installation

​Authentication

​Output formats

​Enrichments

​Waterfalls

​Tables

​Tasks

​AI agent usage

​Environment variables

​Source code

databar-ai/databar-python

Installation

Authentication

Output formats

Enrichments

Waterfalls

Tables

Tasks

AI agent usage

Environment variables

Source code