The Argorant CLI (npx argorant) is a thin layer over the same REST API the app, the automation platforms and the connector use. It has no dependencies of its own, it keeps no data on your machine apart from an optional saved key, and every action lands in your normal Argorant account. This page explains how it is put together and the rules that keep it safe in scripts. For a tour of the commands, read The Argorant CLI.
Install or run it on demand
It needs Node.js 16 or newer. Pick one of two ways:
# runs the latest version each time, nothing to install
npx argorant count "fintech CFOs in germany"
# installs the argorant command for good
npm install -g argorant
argorant count "fintech CFOs in germany"
In CI, npx argorant is usually the better choice, because every run uses the current version. On npm the package is called argorant.
Where the key comes from
The CLI looks for a key in this order and uses the first one it finds:
- The environment variable
ARGORANT_API_KEY. - The key saved by
argorant loginin~/.argorant/config.json. The file is written so only your user can read it.
If neither is there, every command that needs the account stops with no API key and exit code 2. A key that the server refuses gives the same exit code.
# a terminal you use yourself
npx argorant login # paste the key, it is hidden while you type
npx argorant whoami # account, permissions, today's limits
# CI or an agent: no file, only the environment
export ARGORANT_API_KEY=ag_live_xxxxxxxxxxxxxxxxxxxxxxxx
npx argorant whoami --json
argorant logout deletes the saved file. It warns you when ARGORANT_API_KEY is still set, because that key keeps working until you unset it.
The CLI talks to https://argorant.com by default. --base on a command or ARGORANT_API_BASE in the environment point it somewhere else; you only need that if our support asks you to.
The rule about spending
reveal, export, lists export, verify --file and find --file show the cost and ask for a yes only when all of these are true:
- the command runs in a real terminal (stdin is a TTY),
- you did not pass
-yor--yes, - you did not pass
--json.
In CI, in a pipe, or inside an agent there is no question at all. These commands spend straight away. The question is a convenience for people at a keyboard, never a safety net. The safety net is the number you pass with -n, and for find --file the cap you pass with --max-credits.

argorant help prints them.Two actions never run without an explicit yes, even in a script: lists rm and webhooks rm. At a terminal they ask. Anywhere else they need --yes.
Guardrails that are always on
- A
-nthat is not a number stops the command instead of falling back to a default. - A flag that needs a value, followed straight by another flag (
--title --country), stops the command instead of reading the next flag as the value. exportchecks that it can write the output file before it creates the job. If anything goes wrong after the job was charged, it prints theexport downloadcommand that gets the file back for free.- Every change the CLI makes carries an idempotency key. Pass your own with
--idempotency-keyand running the same command again replays the first answer instead of doing the work twice. - Errors print the server's message and a request id. Quote the request id if you contact support.
Scripting it
Use --json for output a program can read, and branch on the exit code rather than on text:
npx argorant export --title CFO --country Germany -n 200 -o cfos.csv --json
case $? in
0) echo "file ready" ;;
2|3) echo "key problem, stop and tell a person" ;;
4) echo "limit reached, try again later" ;;
5) echo "needs credits or a plan, ask the account owner" ;;
*) echo "something else failed" ;;
esac
| Exit code | Meaning | What a script should do |
|---|---|---|
0 | Success | Carry on |
1 | General error, or nothing found by find or enrich | Log it, do not retry blindly |
2 | No key, or the key was rejected | Stop and fix the key |
3 | The key lacks the permission | Stop |
4 | Rate limit or daily limit | Wait; the message says how long |
5 | Out of credits or plan needed | Stop and tell the account owner; the message has the link |
Inside a coding agent
Claude Code, Codex and similar agents can run the CLI in their terminal. Give the agent the key through the environment, never in the chat. Tell it to count and search first, to show you the -n and the expected cost, and to wait for your yes before any command that spends. Require explicit approval of the scope, row limit and credit budget before reveal, person enrichment or a new export, and before launching a campaign or sending a reply. Client tool labels are not a universal confirmation guarantee; non-interactive CLI commands can spend immediately.
Limits
Each API key may send 30 requests a minute during the trial and without a plan (60 through an AI assistant), 60 on Starter, 240 on Pro, 600 on Scale and 1,200 on Hyperscale, and up to a quarter of that, at least 15, in any 10 seconds. Searches and counts are free. On a plan they have no daily limit, only a speed limit per account: 30 a minute on Starter, 60 on Pro, 90 on Scale, 120 on Hyperscale. During the trial and without a plan they are limited per account, across all its keys and the connector: through an AI assistant 20 a minute, 1,000 counts and 1,000 search rows a day; through an API key or the command line 10 a minute, 500 counts and 500 search rows a day. During the trial and without a plan, each key also has daily limits of 100 revealed people and 50,000 export rows; on a plan, credits bound reveals and exports. Daily limits reset at midnight UTC; saved lists, exports and campaigns handle bigger numbers. Account entitlement, scopes and the action's credit budget remain authoritative.
Common mistakes
- Assuming the prompt protects you in CI. It does not appear there. Set
-non every spending command. - An old key in the environment.
ARGORANT_API_KEYwins overargorant login. Ifwhoamishows the wrong account, check the variable. - Retrying exit code 5. It will keep failing until the account has credits or a plan.
- Writing the key into a script file. Use your CI's secret store and pass it as an environment variable.
What happens next
Everything the CLI does shows up in the app under Lists and Exports and in your credit balance. The full reference with every flag is at docs.argorant.com/docs/guides/cli.