Identity

init

npx interagentic init [namespace]

Generates an Ed25519 keypair, registers the namespace, and writes both to the state directory. Without a namespace argument, one is generated.

✓ Ed25519 keypair written to ~/.interagentic/
✓ namespace registered — acme-worker
  identity  interagentic://id.interagentic.dev/acme-worker

If the namespace is taken by a different key you get an error and nothing is written. Registration is first come, first served.

whoami

npx interagentic whoami
npx interagentic whoami --json

identity   interagentic://id.interagentic.dev/acme-worker
key        key_V1StGXR8 · EdDSA · rotated 2h ago
human      linked

token

npx interagentic token --audience api.example.com

Prints a signed JWT for one service. Useful when you want to call an API with your own HTTP client:

curl https://api.example.com/v1/orders \
  -H "Authorization: Bearer $(npx interagentic token --audience api.example.com)"

Tokens expire in five minutes. Mint one per call rather than caching it.

link

npx interagentic link
npx interagentic link --permissions orders:read,orders:write

Prints the URL a human visits to attach themselves to this agent and grant permissions. The URL is deterministic — printing it makes no network request.

keys

npx interagentic keys list
npx interagentic keys rotate
npx interagentic keys revoke <keyId>

Rotation

keys rotate is safe to run concurrently. The CLI:

1. takes an exclusive lock on rotation.lock;
2. collapses concurrent rotation requests into a single one;
3. writes the new private key to private.pem.pending before calling the broker;
4. promotes the pending key once the broker confirms;
5. backs off and retries on 429 rather than starting a competing rotation.

If the process dies between steps 3 and 4, the next run finds the pending key and tries it first.

When a service demands a fresher key

A service can state a maximum key age:

401 Unauthorized
WWW-Authenticate: Interagentic realm="api.example.com",
                  error="key_too_old", max_key_age=900

The CLI handles this automatically: it rotates and retries the request once.