Overview
Installing the CLI, global flags, state on disk, and environment variables.
npx interagentic <command> [options]There is nothing to install and nothing to log into. The first command that needs an identity creates one.
npm install -g interagentic # optionalCommand groups
| Command | Purpose |
|---|---|
init, whoami, link, keys | Identity and key management |
<domain> <command…> | Call a compatible service |
curl | Call anything else, with credential placeholders |
providers | Named provider actions |
credits | Approvals and statements |
Global flags
| Flag | Effect |
|---|---|
--json | Machine-readable output. Turns off markdown rendering. |
--broker <url> | Use a different identity broker for this call |
--state-dir <path> | Use a different state directory |
--debug | Print the requests being made |
--help | Help for the current command or group |
--json is the flag to reach for inside another program: every command that
prints a table also prints structured JSON, and errors become
{ "error": { "code", "message" } } on stderr.
State on disk
State lives in ~/.interagentic/, created with mode 0700.
| File | Mode | Contents |
|---|---|---|
identity.json | 0600 | Broker, namespace, key id, algorithm, rotation time |
private.pem | 0600 | The private key |
private.pem.pending | 0600 | Write-ahead log for an in-flight rotation |
rotation.lock | 0600 | Cross-process lock held during rotation |
Treat ~/.interagentic/private.pem the way you would an SSH private key. Anyone
holding it can act as your agent until the key is rotated — and using a
rotated-out key locks the namespace, which is the point.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
INTERAGENTIC_BROKER | https://id.interagentic.dev | Identity broker |
INTERAGENTIC_STATE_DIR | ~/.interagentic | State directory |
INTERAGENTIC_PROXY_URL | hosted proxy | Credential proxy for curl |
ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY | — | Only needed to generate or repair a provider action |
In CI, set INTERAGENTIC_STATE_DIR to a path inside the job's workspace so each
run gets its own identity rather than sharing one key across concurrent jobs.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, including printing help for a command group |
1 | The request was made and failed |
2 | Unknown command or bad arguments — nothing was sent |
3 | A human is required; an approval URL was printed |