argorant 0.10.0 → 0.12.0

package/README.md

@@ -1,7 +1,8 @@
 # argorant
 
 Search, count, reveal, export, and verify B2B contacts from the Argorant
-database — from your terminal, scripts, or coding agent. No install required.
+database, and find work emails by name and company domain, from your
+terminal, scripts, or coding agent. No install required.
 
 ```sh
 npx argorant count "fintech CFOs in germany"
@@ -9,7 +10,7 @@ npx argorant count "fintech CFOs in germany"
 
 Company lookups, counts, and masked searches spend **zero contact credits on
 an active plan**. Reveals and exports draw on your Argorant workspace
-quota/credits — the same pool as the app, API, and MCP server.
+quota/credits - the same pool as the app, API, and MCP server.
 
 ## Authenticate
 
@@ -19,34 +20,115 @@ Create an API key at **app.argorant.com/profile** (API keys), then:
 npx argorant login            # paste your ag_live_ key (stored in ~/.argorant)
 ```
 
-Or set `ARGORANT_API_KEY=ag_live_…` in your environment — ideal for scripts,
+Or set `ARGORANT_API_KEY=ag_live_…` in your environment - ideal for scripts,
 CI, and agents.
 
 ## Commands
 
 | Command | What it does | Cost |
 | --- | --- | --- |
-| `login [key]` | Save an API key | — |
-| `logout` | Forget the saved key and base (`~/.argorant/config.json`) | — |
+| `login [key]` | Save an API key | - |
+| `logout` | Forget the saved key and base (`~/.argorant/config.json`) | - |
 | `whoami` | Account, scopes, daily quota | free |
 | `count "<query>"` | Count matching contacts | free |
 | `company <company.com> -n 5` | Count people at a company, split business-email coverage, preview masked roles | free |
 | `search "<query>" -n 10` | Preview matches (masked identity, details redacted) | free |
 | `sample <company.com> [-o sample.csv]` | Read a website and build 25 distinct, live-valid company leads from it | free sample |
-| `reveal "<query>" -n 25` | Reveal full contact details (name, email, phone, LinkedIn) | quota |
-| `export "<query>" -n 1000 -o leads.csv` | Verified CSV export, polled until ready | quota |
+| `reveal "<query>" -n 25` | Reveal full contact details (name, work email, LinkedIn) | 1 credit per new working email |
+| `reveal "<query>" -n 25 --phones` | Same, plus each person's phone number (direct dial or mobile) | + 10 credits per number found |
+| `enrich --email <a@b.com> [--phones]` | The person behind an address, optionally with their phone number | 1 credit per match, + 10 if a number is found |
+| `export "<query>" -n 1000 -o leads.csv` | Verified CSV export, polled until ready | 1 credit per working email |
+| `export "<query>" -n 1000 --phones -o leads.csv` | Same, with phone numbers in the file | + 10 credits per number in the file |
 | `export status <job_id> [--batch]` | Status of an export you already created | free |
 | `export download <job_id> [--batch] -o leads.csv` | Re-download a finished export | free |
 | `list create --name "<n>" [filters]` | Save a reusable filtered list (server counts it) | free |
 | `list status <id>` | A saved list's size and mode | free |
 | `verify <email>` / `verify --file emails.csv -o out.csv` | Verify your own addresses (verification pool; recent re-checks free) | pool |
-| `campaigns …` | Live outbound campaigns — **operator keys only**, see below | — |
+| `find "<first last>" --domain <d>` / `find --file people.csv -o found.csv` | Find a person's work email from a name and company domain, one or a whole list ([details](#find-emails)) | 1 credit found, 0.25 nothing found |
+| `find status \| download \| resume \| cancel <job_id>`, `find pricing` | Manage a find job; show prices, balance and limits | free |
+| `campaigns …` | Live outbound campaigns - **operator keys only**, see below | - |
+
+## Phone numbers
+
+Phone numbers are never included unless you ask for them with `--phones` (reveal, enrich, export).
+A phone number costs 10 credits, and only when a number is actually returned. People without a number
+cost nothing, and numbers you already unlocked (in the app, the API or the connector) are free. Phone
+numbers come with the Pro plan and higher. The CLI shows the price before it spends anything, and the
+result says per person whether a number came back and what it cost. Company and HQ numbers stay free.
+
+```sh
+npx argorant reveal --title CFO --domain stripe.com -n 5 --phones
+npx argorant enrich --email patrick@stripe.com --phones --json
+npx argorant export --title CFO --country Germany -n 200 --phones -o cfos.csv
+```
 
 Exports above 50,000 rows are created as a multi-chunk batch: the CLI polls
 `export status --batch` for you and writes one file per chunk
 (`leads-part1.csv`, `leads-part2.csv`, …). The batch id is printed so you can
 re-download any time with `export download <batch_id> --batch`.
 
+## Find emails
+
+Give a name and the company's domain, get the person's work email.
+
+```sh
+npx argorant find "Jane Doe" --domain acme.com
+npx argorant find --first Jane --last Doe --domain acme.com
+# jane.doe@acme.com  ·  Confirmed  ·  confidence 95  ·  1 credit
+```
+
+Each lookup prints one line: the email (or `no email found`), its status, the
+confidence and what it cost. Statuses:
+
+| Status | Meaning | Cost |
+| --- | --- | --- |
+| Confirmed | Address found and confirmed | 1 credit |
+| Unconfirmed, catch-all domain | The domain accepts every address, so the best address is returned without confirmation | 1 credit |
+| Not found | No address found for this person | 0.25 credit |
+| No mail server | The domain does not receive email | free |
+| Try again later | No answer for this domain right now; run it again later | free |
+
+Invalid rows and every failed request (out of credits, limits, a busy
+server) are free too. A 0.25 charge takes one whole credit and keeps the rest
+as prepaid no-result lookups, which cover your next three misses. Run
+`argorant find pricing` for the live prices, your balance, prepaid lookups and
+limits.
+
+A whole list runs as a job. The file is a CSV with a header row and the
+columns `first_name`, `last_name` and `domain`; an optional `ref` column is
+passed through to the results:
+
+```sh
+npx argorant find --file people.csv -o found.csv --max-credits 200 --name "Q4 list"
+```
+
+The CLI prints the job id, shows progress (processed/total, found, charged)
+and saves the results CSV when the job is done (`argorant-found.csv` by
+default). Columns: `row, ref, first_name, last_name, domain, email, status,
+confirmed, confidence, credits_charged`. The output path is checked before the
+job is created. On a terminal the CLI asks first, showing the prices and the
+maximum charge; with `--yes`, `--json` or no TTY it starts right away.
+Duplicate rows are removed before anything is charged. `--max-credits` caps
+the job: it pauses at the cap instead of spending more.
+
+A job pauses when your credits run out, when it reaches `--max-credits`, at
+the daily limit, or when almost none of the recent lookups found anything. The
+CLI says why and still saves what was found so far. Ctrl-C only stops
+watching; the job keeps running.
+
+```sh
+argorant find status <job_id>                      # progress and counts
+argorant find download <job_id> -o found.csv       # the results CSV, any time
+argorant find resume <job_id> [--max-credits 300]  # continue a paused job
+argorant find cancel <job_id>                      # stop; rows not processed yet are not charged
+```
+
+Exit codes: a single `find` exits `1` when no email came back, so scripts can
+branch without parsing. A `find --file` job that pauses exits `5` when out of
+credits and `4` at the daily limit or when slowed down; a job that stops at
+your own `--max-credits` cap exits `0`. Errors use the codes below (`5` out of
+credits, `4` rate limit with the wait time in the message).
+
 ## Filters
 
 Combine free text with structured filters:
@@ -57,7 +139,7 @@ Combine free text with structured filters:
 --has-phone --has-linkedin --has-email --verified-only
 ```
 
-`--keywords` is the widest, most reliable filter (comma = OR) — prefer it over
+`--keywords` is the widest, most reliable filter (comma = OR) - prefer it over
 `--industry`. `--country`/`--geography` accept regions (Europe, EMEA, DACH,
 Nordics, APAC, LATAM, GCC…).
 
@@ -84,13 +166,14 @@ npx argorant company stripe.com --json
 npx argorant reveal "heads of procurement" --country Germany -n 25 --json --yes
 ```
 
-### Non-interactive behaviour — read this before scripting `reveal`/`export`
+### Non-interactive behaviour - read this before scripting `reveal`/`export`
 
-`reveal`, `export`, and `verify --file` ask for confirmation **only** when
-stdin is a TTY and neither `-y/--yes` nor `--json` was passed. In CI, in a
-pipe, or inside an agent loop there is **no prompt at all** — these commands
-spend credits immediately. The prompt is a convenience for humans at a
-terminal, never a safety net. Check your `-n` before you run them.
+`reveal`, `export`, `verify --file` and `find --file` ask for confirmation
+**only** when stdin is a TTY and neither `-y/--yes` nor `--json` was passed.
+In CI, in a pipe, or inside an agent loop there is **no prompt at all**, these
+commands spend credits immediately. A single `find` never asks; each lookup
+costs at most 1 credit. The prompt is a convenience for humans at a terminal,
+never a safety net. Check your `-n` and `--max-credits` before you run them.
 
 Related guardrails, so a mistake stays cheap:
 
@@ -108,9 +191,9 @@ Related guardrails, so a mistake stays cheap:
 | `0` | success |
 | `1` | generic error (bad usage, network, failed job) |
 | `2` | not authenticated (no key, or the key was rejected) |
-| `3` | forbidden — the key lacks the required scope |
+| `3` | forbidden - the key lacks the required scope |
 | `4` | rate limit or daily quota reached |
-| `5` | plan upgrade required (HTTP 402); the message carries the upgrade URL |
+| `5` | plan upgrade required or out of credits (HTTP 402); the message carries the upgrade URL |
 
 Exit `5` is deliberately distinct from `1`: an agent can tell "this account
 needs a paid plan" apart from "something broke".