Metadata-Version: 2.2
Name: iblead-cli
Version: 1.0.0
Summary: Official IBLead CLI — search, export and watch Google Maps leads from your terminal.
Author-email: IBLead <contact@iblead.com>
Project-URL: Homepage, https://app.iblead.com
Project-URL: Documentation, https://github.com/iblead/iblead-cli#readme
Project-URL: Repository, https://github.com/iblead/iblead-cli
Project-URL: Issues, https://github.com/iblead/iblead-cli/issues
Keywords: iblead,google-maps,lead-generation,scraping,cli,b2b
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.28

# IBLead CLI

Official command-line client for the [IBLead API](https://app.iblead.com) — search, export and watch Google Maps leads directly from your terminal.

```bash
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

```bash
pip install iblead-cli
```

Requires Python 3.9+.

## Authenticate

Grab an API key from [app.iblead.com/dashboard/api](https://app.iblead.com/dashboard/api), then:

```bash
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

```bash
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)

```bash
# 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

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

### Watches (saved searches)

```bash
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)

```bash
# 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

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

### Metadata

```bash
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:

```bash
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](https://app.iblead.com)
- Source: [github.com/iblead/iblead-cli](https://github.com/iblead/iblead-cli)
- Issues: [github.com/iblead/iblead-cli/issues](https://github.com/iblead/iblead-cli/issues)

## License

MIT. See [LICENSE](./LICENSE).
