dome agents

Command
Register	`dome agents register`
List	`dome agents list`
Get	`dome agents get [name-or-id]`
Update	`dome agents update [name-or-id]`
Suspend	`dome agents suspend [name-or-id]`
Reactivate	`dome agents reactivate [name-or-id]`
Revoke	`dome agents revoke [name-or-id]`
Delete	`dome agents delete [name-or-id]`
Create key	`dome agents create-key [name-or-id]`
List keys	`dome agents list-keys [name-or-id]`
Rotate key	`dome agents rotate-key [name-or-id] [key-name]`
Revoke key	`dome agents revoke-key [name-or-id] [key-name]`
Assign-policy	`dome agents assign-policy [name-or-id] [files...]`
Get-policies	`dome agents get-policies [name-or-id]`

Register

dome agents register Register a new agent in the current workspace. Pass fields with per-field flags or load the full definition from a JSON/YAML file with --file.

dome agents register --name <name> [flags]
dome agents register --file <path>

Flag	Type	Required	Description
`--file`, `-f`	string	Yes*	Path to a JSON/YAML file with the full agent definition. Use `-` for stdin. Mutually exclusive with per-field flags
`--name`	string	Yes*	Agent name
`--capabilities`	string[]	No	Custom capability strings (repeatable). System capabilities `llm:invoke`, `mcp:call`, and `mcp:discover` are derived automatically from the selections below
`--parent-id`	string	No	Parent agent ID
`--metadata`	key=value	No	Agent metadata (repeatable)
`--if-not-exists`	bool	No	Return existing agent if name is taken
`--pool`	string[]	No	LLM pool the agent may route to (repeatable). Emits a `permit` against `Dome::LLMModel` matched via `resource.pool == "<name>"` in the agent’s generated bundle
`--model`	string[]	No	LLM model connection the agent may invoke directly (repeatable, advanced — pools are preferred). Emits a `permit` against `Dome::LLMModel`
`--tool`	string[]	No	MCP tool the agent may call, as `<connection>/<tool>` (repeatable). Emits `mcp:call` and `mcp:discover` permits against `Dome::MCPTool`
`--gateway`	string[]	No	Gateway ID (UUID) the agent may reach (repeatable). Admits the agent at the Gateway endpoint and generates a membership-conditioned permit.
`--actas-allowed-group`	string[]	No	Group the agent’s verified act-as identity may belong to (repeatable). Emits a `forbid` unless the verified group matches
`--actas-allowed-email`	string[]	No	Email the agent may act on behalf of (repeatable). Emits a `forbid` unless the verified email matches
`--actas-allowed-subject`	string[]	No	Subject the agent may act on behalf of (repeatable). Emits a `forbid` unless the verified subject matches
`--actas-method`	string	No	Act-as verification: `none`, `oidc`, `hmac`
`--actas-required`	bool	No	Require act-as header on every request
`--actas-provider`	string	No	Workspace verification provider ID
`--actas-oidc-url`	string	No	Inline OIDC discovery URL
`--actas-hmac-secret`	string	No	Inline HMAC shared secret
`--actas-config-name`	string	No	Label for agent-specific verification config
`--pool`	string[]	No	LLM pool name the agent may route to (repeatable)
`--model`	string[]	No	LLM model connection name the agent may invoke directly (advanced; repeatable)
`--tool`	string[]	No	MCP tool the agent may call as `<connection>/<tool>` (repeatable)
`--actas-allowed-group`	string[]	No	Group claim the agent’s verified act-as identity may belong to (repeatable)
`--actas-allowed-email`	string[]	No	Email the agent may act on behalf of (repeatable)
`--actas-allowed-subject`	string[]	No	Subject the agent may act on behalf of (repeatable)

Populating --pool, --model, or --tool triggers generation of an agent-scope kind='generated' rule bundle and auto-derives the corresponding capabilities (llm:invoke, mcp:call, mcp:discover). Leaving all three --actas-allowed-* lists empty means “any verified identity is acceptable”; populating any one restricts the agent via a forbid-unless rule. Pool, model, tool, and --actas-allowed-* flags populate the agent’s generated rule bundle. Update operations that change any of these fields require rules.deploy in addition to agent.register. * Provide either --name (per-field mode) or --file. The two modes cannot be combined.

Register from a file

Use --file to register from a single JSON or YAML document. The file shape mirrors the RegisterAgentRequest proto — the same schema the SDKs and Terraform provider consume — so a typo in a field name fails fast rather than silently dropping. The workspace is always taken from the active context; a workspace_id in the file is ignored.

agent.yaml

name: claude-research
capabilities: [read]
allowed_pool_names: [openai-prod]
allowed_tools: [github/list_repos]
actas_config:
  method: oidc
  required: true
  oidc_discovery_url: https://idp.example.com/.well-known/openid-configuration

dome agents register --file agent.yaml

# JSON works too
dome agents register -f agent.json

# Read from stdin
printf '{"name":"x"}' | dome agents register -f -

List

dome agents list List agents in the current workspace.

dome agents list [flags]

Flag	Type	Description
`--status`	string	Filter by status: `active`, `provisioned`, `suspended`, `revoked`
`--limit`	int	Maximum results (default: 100)

Get

dome agents get [name-or-id] Get details for a specific agent. Pass --gateway <id> to select an accessible Gateway and include its complete protocol endpoints. Without the flag, the command returns agent metadata only.

Output

Name:    data-pipeline-agent
ID:      a1b2c3d4-…
Status:  active
Gateway ID:  {{GATEWAY_ID}}
Gateway URL: https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}
MCP URL:     https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp

Flag	Type	Description
`--gateway`	string	Gateway ID used to resolve endpoints; required when the agent can access more than one Gateway

Update

dome agents update [name-or-id] Update an agent’s capabilities, metadata, or act-as config.

Flag	Type	Description
`--capabilities`	string[]	Updated custom capabilities
`--metadata`	key=value	Updated metadata
`--pool`	string[]	Replace the agent’s allowed LLM pool list
`--model`	string[]	Replace the agent’s allowed direct-model list
`--tool`	string[]	Replace the agent’s allowed MCP tool list (`<connection>/<tool>`)
`--gateway`	string[]	Replace the agent’s allowed Gateway ID list (UUIDs; repeatable)
`--actas-allowed-group`	string[]	Replace the agent’s act-as allowed-groups list
`--actas-allowed-email`	string[]	Replace the agent’s act-as allowed-emails list
`--actas-allowed-subject`	string[]	Replace the agent’s act-as allowed-subjects list
`--actas-method`	string	Act-as verification: `none`, `oidc`, `hmac`
`--actas-required`	bool	Require act-as header
`--actas-provider`	string	Workspace verification provider ID
`--actas-oidc-url`	string	Inline OIDC discovery URL
`--actas-hmac-secret`	string	Inline HMAC shared secret
`--actas-config-name`	string	Label for agent-specific verification config
`--pool`	string[]	Replace the agent’s allowed LLM pool list (repeatable)
`--model`	string[]	Replace the agent’s allowed direct-model list (advanced; repeatable)
`--tool`	string[]	Replace the agent’s allowed MCP tool list (repeatable; each `<connection>/<tool>`)
`--actas-allowed-group`	string[]	Replace the agent’s act-as allowed-groups list (repeatable)
`--actas-allowed-email`	string[]	Replace the agent’s act-as allowed-emails list (repeatable)
`--actas-allowed-subject`	string[]	Replace the agent’s act-as allowed-subjects list (repeatable)

The --pool, --model, --tool, and --actas-allowed-* flags use PUT semantics: whatever you send IS the new state, including an empty value meaning “clear”. To update only one field, get the agent first and pass the current values back. Changing any of these four-pillar fields (or --actas-method / --actas-required) regenerates the agent’s kind='generated' rule bundle and therefore requires the rules.deploy permission in addition to agent.register. Identity-only updates (name, metadata, capabilities) pass through on agent.register alone. Changing any pool, model, tool, or --actas-allowed-* field regenerates the agent’s rule bundle and requires rules.deploy in addition to agent.register. Identity-only updates (name, metadata, capabilities) require only agent.register.

Suspend

dome agents suspend [name-or-id] Suspend an agent temporarily.

Flag	Type	Description
`--reason`	string	Suspension reason
`--cascade`	bool	Also suspend child agents

Reactivate

dome agents reactivate [name-or-id] Reactivate a suspended agent.

Revoke

dome agents revoke [name-or-id] Permanently revoke an agent. Always cascades to all descendants.

Flag	Type	Description
`--reason`	string	Revocation reason

Delete

dome agents delete [name-or-id] Permanently hard-delete a revoked agent and all its data. Requires the agent to be in a revoked state.

Flag	Type	Description
`--reason`	string	Deletion reason
`--cascade`	bool	Also delete descendant agents

Assign-policy

dome agents assign-policy [name-or-id] [files...] Deploy Cedar rules scoped to a specific agent.

Get-policies

dome agents get-policies [name-or-id] Get Cedar rules assigned to an agent.

Agent API Keys

Create-key

dome agents create-key [name-or-id] Create an agent authentication key. Prints the token and the selected Gateway’s complete endpoints once.

Flag	Type	Required	Description
`--name`	string	Yes	Key name
`--gateway`	string	No	Gateway ID used to resolve endpoints; required when the agent can access more than one Gateway

Output

✓ API key "default" created for agent my-first-agent
✓ Token: dome_…
Gateway ID:  {{GATEWAY_ID}}
Gateway URL: https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}
MCP URL:     https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp
ℹ Save this token — it will not be shown again.

Use the URL for the protocol your application speaks. JSON output returns gatewayId and gatewayEndpoints.

List-keys

dome agents list-keys [name-or-id] List API keys for an agent.

Rotate-key

dome agents rotate-key [name-or-id] [key-name] Rotate an agent’s API key — revokes the old secret and issues a new one. Use --gateway <id> to select the Gateway when the agent can access more than one. Output includes gatewayId and gatewayEndpoints.

Revoke-key

dome agents revoke-key [name-or-id] [key-name] Revoke an agent’s API key permanently.

Overview

Connect

Govern

Operate

Settings

Developer

Session

Standalone

dome agents

Register

Register from a file

List

Get

Update

Suspend

Reactivate

Revoke

Delete

Assign-policy

Get-policies

Agent API Keys

Create-key

List-keys

Rotate-key

Revoke-key

​Register

​Register from a file

​List

​Get

​Update

​Suspend

​Reactivate

​Revoke

​Delete

​Assign-policy

​Get-policies

​Agent API Keys

​Create-key

​List-keys

​Rotate-key

​Revoke-key

Register

Register from a file

List

Get

Update

Suspend

Reactivate

Revoke

Delete

Assign-policy

Get-policies

Agent API Keys

Create-key

List-keys

Rotate-key

Revoke-key