Command line

Automation

The CLI is built for cron, CI, and shell scripts: key-in-environment auth, predictable JSON output, optional file output, and exit codes your jobs can branch on. Results go to stdout; warnings, progress, and the resolved account go to stderr.

Pass the key explicitly

In cron and CI, pass AGENT_CENTRAL_API_KEY on the job or pass a specific --profile. Do not rely on the active profile you use interactively. Add --no-color for clean logs.

# every morning, snapshot inventory health to a dated file
0 7 * * *  AGENT_CENTRAL_API_KEY=ac_live_...   agentcentral tools call get_inventory_health     --format json --no-color     --output /var/log/agentcentral/inventory-$(date +%F).json

Provide tool input

tools call accepts inline JSON, an @file, an existing file path, or - for stdin. Use files for repeatable jobs and stdin when another command prepares the input.

agentcentral tools call get_orders '{"limit":5}'
agentcentral tools call get_orders @args.json
echo '{"limit":5}' | agentcentral tools call get_orders -

Choose an output format

Use --format json for one structured result. Use --format ndjson when you want one row per line for streaming into jq or a load step. Use --output to write a result file and keep stdout quiet.

agentcentral tools call get_inventory_health --format ndjson   | jq -c 'select(.coverage_state == "low")'

Most list-style tools honor --limit. If the result is truncated at the allowed limit, the CLI warns on stderr so your job can treat the file as a sample instead of a complete export.

Exit codes

The CLI turns auth failures, validation errors, network issues, and tool errors into stable shell exit codes:

Code	Meaning
0	Success. A repeated write with the same idempotency key also exits 0 after confirming no new write was made.
1	Unexpected failure
2	Invalid CLI usage or flags
3	Missing, expired, or invalid key
4	The key or account does not allow the requested tool or action
5	Input validation failed, or a write submit was missing its idempotency key
6	Network failure or rate-limit failure after retries
7	The tool ran but reported an error or safety block
8	Request timeout
9	Write partially succeeded; inspect the returned counts

agentcentral tools call get_days_of_cover --format json --output cover.json
case $? in
  0) echo "ok" ;;
  3) echo "auth failed"; exit 3 ;;
  4) echo "key or account does not allow this request"; exit 4 ;;
  6) echo "network or rate-limit failure after retries"; exit 6 ;;
  8) echo "timeout"; exit 8 ;;
  *) echo "see stderr"; exit 1 ;;
esac

Rate limits and retries

Each key can make 120 requests per minute on the CLI path. When agentcentral returns a temporary failure or asks the client to wait, the CLI retries with capped backoff. Reads are safe to retry. Writes are only retried when you provide the same --idempotency-key.

Scheduled writes

For scheduled writes, derive a stable --idempotency-key from the run, such as the job name and date. If the job is retried, the same key prevents a second write from being applied.

# a retried scheduled write is safe when the key is stable
KEY="nightly-bid-sync-$(date +%F)"
agentcentral tools call update_keyword_bids   --input bids.json --yes --idempotency-key "$KEY"   --format json --no-color

For the full write flow, see write safety.