argorant 0.12.0 → 0.13.0

package/README.md

@@ -46,7 +46,14 @@ 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
 
@@ -205,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.