> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# dome agents

> Manage agent registrations, lifecycle, and API keys

| Command                         |                                                     |
| ------------------------------- | --------------------------------------------------- |
| [Register](#register)           | `dome agents register`                              |
| [List](#list)                   | `dome agents list`                                  |
| [Get](#get)                     | `dome agents get [name-or-id]`                      |
| [Update](#update)               | `dome agents update [name-or-id]`                   |
| [Suspend](#suspend)             | `dome agents suspend [name-or-id]`                  |
| [Reactivate](#reactivate)       | `dome agents reactivate [name-or-id]`               |
| [Revoke](#revoke)               | `dome agents revoke [name-or-id]`                   |
| [Delete](#delete)               | `dome agents delete [name-or-id]`                   |
| [Create key](#create-key)       | `dome agents create-key [name-or-id]`               |
| [List keys](#list-keys)         | `dome agents list-keys [name-or-id]`                |
| [Rotate key](#rotate-key)       | `dome agents rotate-key [name-or-id] [key-name]`    |
| [Revoke key](#revoke-key)       | `dome agents revoke-key [name-or-id] [key-name]`    |
| [Assign-policy](#assign-policy) | `dome agents assign-policy [name-or-id] [files...]` |
| [Get-policies](#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`.

```bash theme={"system"}
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](/connect/gateways) 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.

```yaml agent.yaml theme={"system"}
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
```

```bash theme={"system"}
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.

```bash theme={"system"}
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.

```text Output theme={"system"}
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](/connect/gateways) 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 |

```text Output theme={"system"}
✓ 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.