Argorant Help
EN|DEargorant.comOpen Argorant
Help/AI agents & API

The CLI: install, shape and safety model

Published by Argorant

How the Argorant CLI is built, where it gets its key, when it asks before spending and when it does not, and how to script it safely in CI and agents.

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:

  1. The environment variable ARGORANT_API_KEY.
  2. The key saved by argorant login in ~/.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 -y or --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.

A terminal showing the NON-INTERACTIVE USE and EXIT CODES sections of argorant help
The same rule and the exit codes, as 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 -n that 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.
  • export checks that it can write the output file before it creates the job. If anything goes wrong after the job was charged, it prints the export download command that gets the file back for free.
  • Every change the CLI makes carries an idempotency key. Pass your own with --idempotency-key and 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 codeMeaningWhat a script should do
0SuccessCarry on
1General error, or nothing found by find or enrichLog it, do not retry blindly
2No key, or the key was rejectedStop and fix the key
3The key lacks the permissionStop
4Rate limit or daily limitWait; the message says how long
5Out of credits or plan neededStop 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 -n on every spending command.
  • An old key in the environment. ARGORANT_API_KEY wins over argorant login. If whoami shows 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.

Related
The Argorant CLICLI: login, logout and where the key livesCLI exit codes and what to do with eachSpending guardrails: instructions that keep an agent cheap

Still stuck? support@argorant.com

Help homeargorant.comPricingRoadmap
support@argorant.com