alter agents

A managed agent is a first-class identity for an AI workload, with its own keys and its own audit attribution. These commands manage agents and their key lifecycle.

alter agents list       [--status ...] [--type ...] [--provider ...] [--search ...]
alter agents create     --name <name> --scopes <json> [--display-name ...] [--type ...] [--input ...]
alter agents show       --agent <agent-id>
alter agents audit      --agent <agent-id> [--limit ...] [--offset ...]
alter agents registry-list  [--limit ...] [--offset ...]
alter agents registry-show  --agent <actor-id>
alter agents update     --agent <agent-id> [--display-name ...] [--metadata ...] [--scopes <json> --expected-version <n>] [--grace-seconds <n>]
alter agents suspend    --agent <agent-id> [--yes]
alter agents resume     --agent <agent-id> [--yes]
alter agents revoke     --agent <agent-id> [--yes]
alter agents mint-key        --agent <agent-id>
alter agents list-keys       --agent <agent-id>
alter agents revoke-key      --agent <agent-id> --key <key-id> [--force] [--yes]
alter agents deprecate-key   --agent <agent-id> --key <key-id>
alter agents undeprecate-key --agent <agent-id> --key <key-id>

All commands are app-scoped — pass --app <id> (or the app’s name), or link a workspace / set ALTER_APP_ID. Reads (list / show / list-keys) need dashboard_agents:read; create, metadata-only update, mint-key, deprecate-key, and undeprecate-key need dashboard_agents:write; scope updates, suspend, resume, revoke, and revoke-key need dashboard_agents:admin. audit needs dashboard_audit:read (it reads the audit log, not the agent registry).

Note

Both agents create and agents mint-key return an API key that is shown once. Capture it when printed.

list

Flag	Default	Description
--status <list>	all	Comma-separated filter: active, inactive, revoked.
--type <type>	all	agent or service.
--provider <provider>	all	Agents whose scopes include this provider.
--search <query>	—	Substring match on name / display name.
--limit <n>	10	Page size (1–10).
--offset <n>	0	Pagination offset.

alter agents list --status active --type service

Every output format emits the agent rows themselves — --output json is the rows array, matching every other list command. When more agents remain, the command prints the next --offset to run on stderr, so a | jq pipeline keeps clean data on stdout.

audit

Paginated audit feed for one agent — the portal actions taken against it (create / update / revoke and key lifecycle), newest first. Needs dashboard_audit:read.

Flag	Default	Description
--limit <n>	50	Page size (1–500).
--offset <n>	0	Pagination offset.
--output <format>	table	json, jsonl, or table.

alter agents audit --agent <agent-id> --output table

registry-list / registry-show

The read-only agent registry — agents seen in audit data, with activity stats (last activity, 30-day count). This is distinct from agents list / show, which manage the configured agent identities; the registry is the observability view. Both need dashboard_agents:read.

registry-list uses --limit 50 by default (range 1–200) and --offset 0. As with list and audit, every format emits the registry rows themselves (json is the array) and the next --offset prints to stderr when more remain.

alter agents registry-list
alter agents registry-show --agent <actor-id>

create

Create a managed agent. --name and a --scopes object are required unless you supply --input; input bodies must contain the same scope map. An empty object (--scopes '{}') provisions a deny-all agent that cannot access any provider until scopes are added.

Flag	Required	Description
--name <name>	yes	Stable identifier: starts with a lowercase letter or digit, then lowercase letters, digits, -, or _ (maximum 255 characters).
--display-name <name>	no	Human-readable name.
--type <type>	no	agent (default) or service.
--scopes <json>	yes	JSON object mapping provider ids to non-empty scope arrays (maximum 12 KiB compact JSON). {} is allowed and means no provider access.
--input <path>	no	JSON body from a file (@path) or stdin (-); replaces the per-field flags.

alter agents create --name nightly-sync --type service \
  --display-name "Nightly Sync" \
  --scopes '{"google":["openid","email"]}'

show

alter agents show --agent <agent-id>

update

Update labels, metadata, or the full capability allowlist. Scope changes require dashboard_agents:admin and the current version from alter agents show; this prevents a stale full-allowlist replacement from restoring access another operator removed. Broadening applies immediately; narrowing uses --grace-seconds or the 24-hour deployment default.

Flag	Description
--display-name <name>	New display name.
--metadata <json>	Replacement metadata object.
--scopes <json>	Full provider-to-scope allowlist (maximum 12 KiB compact JSON). {} narrows to no provider access.
--expected-version <n>	Positive version from the latest agents show response; required with --scopes.
--grace-seconds <n>	Narrowing grace 0–604800; requires --scopes. Use 0 for immediate application.

alter agents update --agent <agent-id> --display-name "Nightly Sync (EU)"
alter agents update --agent <agent-id> \
  --scopes '{"google":["openid"]}' \
  --expected-version <version-from-agents-show> \
  --grace-seconds 3600

If the agent changes before the update commits, the command exits with a conflict. Run agents show again, reconcile the complete desired allowlist against the fresh record, and retry with its new version.

revoke

Revoke an agent. This cascade-revokes all of its keys. Revocation is recoverable — you can re-create an agent with the same scopes — so the prompt is a simple y/N (skip with --yes).

alter agents revoke --agent <agent-id>

suspend / resume

Pause an agent without revoking it, then restore it later.

alter agents suspend --agent <agent-id>
alter agents resume --agent <agent-id>

• suspend flips the agent to inactive. Existing keys and grants stay attached, but the agent’s credential calls start failing with agent_inactive; agent.me() keeps working for self-diagnostics.
• resume flips the agent back to active. Any overdue pending scope narrowing applies on the next auth check or sweeper pass after resume.

Both commands prompt with y/N; pass --yes to skip the prompt.

Key lifecycle

An agent can hold several keys, which lets you rotate without downtime: mint the new key, deploy it, then revoke the old one.

# Mint a fresh key (plaintext shown once)
alter agents mint-key --agent <agent-id>

# List every key (active / deprecated / revoked) with last-used timestamps
alter agents list-keys --agent <agent-id>

# Revoke one key
alter agents revoke-key --agent <agent-id> --key <key-id>

revoke-key accepts --force to override the last-active-key guard (leaving the agent with no active key) and --yes to skip the prompt.

Before revoking, you can deprecate a key to signal it should be retired. A deprecated key still authenticates — the backend just returns an advisory deprecation header to callers so they can migrate first. It is fully reversible, so there is no prompt.

# Mark a key deprecated (still works; advisory only)
alter agents deprecate-key --agent <agent-id> --key <key-id>

# Undo it
alter agents undeprecate-key --agent <agent-id> --key <key-id>

Recipes

Rotate an agent’s key without downtime

# 1. Mint a fresh key (printed once) and deploy it to the agent.
alter agents mint-key --agent <agent-id>
# 2. Confirm the agent is calling with the new key — check the LAST USED column.
alter agents list-keys --agent <agent-id>
# 3. Revoke the superseded key.
alter agents revoke-key --agent <agent-id> --key <old-key-id>

Related

• alter keys — app-level runtime keys
• alter managed-secrets grants — give an agent a backend credential
• Agents