iblead-cli 1.0.0

Official IBLead CLI — search, export and watch Google Maps leads from your terminal.

IBLead CLI

Official command-line client for the IBLead API — search, export and watch Google Maps leads directly from your terminal.

pip install iblead-cli
iblead login
iblead export run --country FR --category Restaurant --no-reviews -o out.csv

Why a CLI

• One-liner exports. iblead export run launches an async export, polls the job, downloads the CSV — three API calls collapsed into one command.
• Composable. Pipe CSV/JSON output into jq, csvkit, Airflow, cron, GitHub Actions. Scriptable from day one.
• Zone search. Draw a rectangle or free polygon, save it as a WKT file, pass --bbox @zone.wkt to any search or export.
• No web UI needed. All 25+ public API endpoints wrapped: search, lookup, export, watches, credits, categories, cities.

Install

pip install iblead-cli

Requires Python 3.9+.

Authenticate

Grab an API key from app.iblead.com/dashboard/api, then:

iblead login

The key is stored in ~/.config/iblead/credentials (chmod 600). You can also set IBLEAD_API_KEY as an env var — it takes precedence over the file.

Common commands

Search

iblead search --country FR --category Restaurant --has-email -n 50 -f csv > leads.csv
iblead search --bbox @paris.wkt --min-rating 4.5 -f table

Export (async, with polling + download)

# Simple export — blocks until the file lands on disk
iblead export run --country FR --category Restaurant --limit 5000 -o restos.csv

# Zone-based, no reviews (~50x smaller file)
iblead export run --country FR --bbox @idf.wkt --no-reviews -o idf.csv

# Fire and forget — print the job_id and exit
iblead export run --country FR --category Hotel --no-wait

# Check job status later
iblead export status <job_id> --watch
iblead export download <job_id> -o hotels.csv

Lookup

iblead lookup one "0x47e66e1f06e2b70d:0x40b82c3688c9460"
iblead lookup bulk --file ids.txt
cat ids.txt | iblead lookup bulk

Watches (saved searches)

iblead watch create --country FR --category Restaurant --has-email --auto-notify
iblead watch list
iblead watch new <watch_id>
iblead watch unlock <watch_id> --limit 100

Zone / polygon helpers (offline)

# Build a WKT rectangle
iblead zone rectangle --min-lat 48.85 --min-lon 2.33 --max-lat 48.87 --max-lon 2.36 > paris.wkt

# Validate a WKT polygon (4-1000 points, closed ring, coord bounds)
iblead zone validate paris.wkt

Account

iblead credits      # balance + daily export usage
iblead whoami       # account info

Metadata

iblead categories
iblead subcategories --category Restaurant
iblead countries
iblead cities --country FR --search paris

Output formats

• --format json (default for most commands) — machine-readable
• --format csv — flat CSV, nested fields JSON-encoded
• --format table — terminal-friendly

Exit codes

Code	Meaning
0	Success
1	Usage / client error
2	Auth failed (401)
3	Forbidden (403)
4	Insufficient credits
5	Rate limited (429)
6	Server error (5xx)
7	Other HTTP error

Handy for shell scripts:

iblead export run --country FR -o out.csv && echo "done" || echo "failed with $?"

Environment variables

Variable	Purpose
IBLEAD_API_KEY	API key (overrides the credentials file)
IBLEAD_API_URL	Override API base URL (default: https://app.iblead.com/api/v1)

Configuration

File	Purpose
~/.config/iblead/credentials	Stored API key (chmod 600)

Links

• API docs: app.iblead.com
• Source: github.com/iblead/iblead-cli
• Issues: github.com/iblead/iblead-cli/issues

License

MIT. See LICENSE.