argorant 0.11.0 → 0.13.0

package/README.md

@@ -34,8 +34,11 @@ CI, and agents.
 | `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 |
@@ -43,7 +46,28 @@ CI, and agents.
 | `verify <email>` / `verify --file emails.csv -o out.csv` | Verify your own addresses (verification pool; recent re-checks free) | pool |
 | `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 | - |
+| `campaigns …` | Email campaigns, see below | - |
+| `account` | Plan, credits, requests per minute, campaign emails, scopes | free |
+| `lists ls \| create \| show \| people \| rename \| rm \| export` | Saved lists, a page at a time ([details](#lists-exports-credits-and-webhooks)) | free, export 1 credit per valid contact |
+| `exports ls \| status \| download` | Your exports, newest first | free |
+| `companies count \| search \| people` | Companies that match your filters | free |
+| `lookup industries \| countries \| keywords \| technologies \| titles [text]` | The exact labels to use in filters | free |
+| `credits packs \| quote \| buy \| purchases` | Buy a credit pack; asks first, then the saved card or a payment link | the pack price |
+| `webhooks ls \| add \| set \| test \| deliveries \| rm` | Get events sent to your own server | free, Pro plan and up |
+
+## 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
@@ -188,6 +212,66 @@ needs a paid plan" apart from "something broke".
 command always wins over the stored one, `ARGORANT_API_BASE` overrides both,
 and `argorant logout` removes the file.
 
+## Lists, exports, credits and webhooks
+
+These commands call the API under `/api/v1` and work with any API key that has the right
+permissions. Lists come back a page at a time: `-n` sets the page size, `--cursor` continues
+where the last page ended (the command prints the next cursor), and `--all` reads every page.
+
+```sh
+npx argorant account                                     # plan, credits, requests per minute
+npx argorant lookup industries soft                      # exact labels for --industry
+npx argorant lookup titles "head of"
+npx argorant companies count --country Germany --employees 11-50,51-200
+npx argorant companies search saas --country Germany -n 10
+
+npx argorant lists                                       # your saved lists, newest first
+npx argorant lists create --name "DACH CFOs" --title CFO --country Germany,Austria,Switzerland
+npx argorant lists show 1240
+npx argorant lists people 1240 --all --json              # the people in it, contact details hidden
+npx argorant lists rename 1240 --name "DACH finance leaders"
+npx argorant lists export 1240 -n 500 -o cfos.csv        # 1 credit per valid contact
+npx argorant lists export 1240 --include-phones          # plus 10 credits per phone number returned
+npx argorant lists rm 1240 --yes
+
+npx argorant exports                                     # your exports, newest first
+npx argorant exports status 5521
+npx argorant exports download 5521 -o leads.csv
+
+npx argorant credits packs                               # 500, 5,000, 25,000 and 100,000 credits
+npx argorant credits quote 5000                          # the price, nothing is bought
+npx argorant credits buy 5000                            # asks first, then pays (see below)
+npx argorant credits purchases
+
+npx argorant webhooks add https://example.com/hooks/argorant --events reply.received,reply.positive
+npx argorant webhooks                                    # your webhooks and every event you can pick
+npx argorant webhooks test 3
+npx argorant webhooks deliveries 3
+npx argorant webhooks set 3 --inactive
+npx argorant webhooks rm 3 --yes
+```
+
+`credits buy` shows the quote first and only buys after a yes: at a terminal it asks, anywhere
+else it needs `--yes`. When your workspace saved its card for API and agent purchases and the
+purchase fits the limits you set in Settings, that card is charged right away. Otherwise you get a
+payment link to pay yourself, and the credits are added once the payment goes through.
+`--pay-with link` always gives the link. Bought credits stay valid for 365 days.
+
+`lists rm` and `webhooks rm` work the same way: they ask at a terminal and need `--yes` anywhere
+else. A webhook's signing secret is shown once, when you add it.
+
+### Safe retries and support
+
+Every change the CLI makes through `/api/v1` carries an `Idempotency-Key`. If a command fails
+halfway (a dropped connection, a closed laptop), run it again with your own key to get the
+first answer back instead of doing the work twice:
+
+```sh
+npx argorant credits buy 5000 --yes --idempotency-key buy-5000-oct
+```
+
+Errors show the server's message and a request id. Quote the request id if you contact support.
+
 ## Campaigns and inboxes
 
 Email outreach from the terminal, with any Argorant API key. Nothing sends until you launch.