@keelapi/cli

Connect an agent to Keel from the terminal. Dry-run by default — nothing is written without --apply, and the runtime key never lands in a tracked file.

Recommended: one command from Authority

In Authority, choose Connect agent, enter the agent name, and copy the one-command setup command. It has this shape:

npx @keelapi/cli@latest agents connect \
  --setup ks_setup_… \
  --agent "Support Triage" \
  --apply --test

The setup token is short-lived, single-use, and scoped to the Keel project. The command creates the agent binding, writes the runtime key only to a gitignored .env, and calls the free identity check. It never makes a model call.

Bring-your-own-key

Mint a runtime key in the dashboard (Authority → Connect agent → Issue runtime key), then:

# preview exactly what would change (framework auto-detected)
npx @keelapi/cli agents connect --runtime-key keel_sk_… --agent "Support Triage"

# write it: secret -> gitignored .env, placeholders -> .env.example
npx @keelapi/cli agents connect --runtime-key keel_sk_… --agent "Support Triage" --apply

# check what the key is bound to (verified vs claimed)
npx @keelapi/cli agents whoami --runtime-key keel_sk_…

The key can also come from the KEEL_RUNTIME_KEY environment variable instead of --runtime-key.

What --apply does (safely)

• Upserts KEEL_RUNTIME_KEY (secret), KEEL_AGENT_ID/KEEL_AGENT_NAME, and the proxy base URLs into .env — idempotent, never touching unrelated keys.
• Ensures .env is in .gitignore; hard-fails if .env is already git-tracked (won't help you commit a secret).
• Backs up the prior .env to .env.keel.bak; restore with --undo.
• Writes .env.example with the secret blanked and public values filled.
• Prints the client-wiring snippet for the detected framework (uses @keelapi/identity); it does not rewrite your source.
• Sends a non-secret deployment fingerprint to Keel so repeated connects from the same deployment can be grouped without trusting agent names.

Flags

--mode verified (default, needs a runtime key = proof) · --mode visibility (claim headers only — attribution, not enforceable) · --framework auto · --deployment-fingerprint <hash> (optional override) · --dir <path> · --test (run the identity check after apply) · --undo.

Backend dependency status

• --setup ks_setup_… uses /v1/cli/agents/connect. Dry-run never consumes the one-time token; only --apply exchanges it.
• agents whoami / --test calls /v1/identity/whoami and reports the actual verified identity. A missing endpoint is reported as "verify pending", not guessed as success.

See ../../DESIGN.md.