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

# idyl agent

> Manage Agents in a Namespace

Manage stable Agent definitions in the selected Namespace and Subnet.
Metadata changes leave published Revisions and existing Actors unchanged.
Deleting an Agent deletes its Actors as their Runs recorded.

## Usage

```bash theme={null}
idyl agent
```

## Aliases

* `agents`

## Commands

| Command | Description |
| - | - |
| `idyl agent create` | Create an Agent |
| `idyl agent delete` | Delete an Agent and its Actors |
| `idyl agent edit` | Update Agent metadata |
| `idyl agent get` | Read an Agent |
| `idyl agent list` | List Agents |
| `idyl agent revision` | Publish, read and delete immutable Agent Revisions |

## Inherited flags

| Flag | Description |
| - | - |
| `-a <string>, --account-id <string>` | Account ID to use, overriding the current context. |
| `-c <string>, --context <string>` | Use the named context for this command. |
| `--homedir <string>` | Override the configuration directory. Defaults to \~/.config/idyl. |
| `-n <string>, --namespace <string>` | Namespace to address, overriding the entered context. |
| `--network <string>` | Override the Network for this command. |
| `-p <string>, --profile <string>` | Override the access profile for this command. |
| `-s <string>, --subnet <string>` | Subnet to use for this command, overriding the current context. |

## Subcommand reference

### `idyl agent create`

Create an Agent

#### Usage

```bash theme={null}
idyl agent create <name> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `--annotation <stringToString>` | Agent annotations as key=value pairs; replaces the annotations map when supplied. |
| `--label <stringToString>` | Agent labels as key=value pairs; replaces the labels map when supplied. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent delete`

Delete an Agent from the selected Namespace and Subnet.

The Agent moves to terminating, which closes new Revisions, Runs and inputs.
Its Actors are then deleted progressively, each disposing of its Computer as
its Run recorded. The Agent is removed, and its name released, once no Actor
remains. Repeating the command is safe while the Agent terminates. With --id
the operand is the stable Agent ID, never a later Agent that reuses the name.

You will be prompted for confirmation unless the --yes flag is provided.

#### Usage

```bash theme={null}
idyl agent delete <name-or-id> [flags]
```

#### Aliases

* `rm`

#### Flags

| Flag | Description |
| - | - |
| `--id` | Address the stable Agent ID instead of its name. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
idyl agent delete analysis
idyl agent delete 01890a5d-ac96-774b-bcce-b302099a8061 --id --yes -o json
```

### `idyl agent edit`

Update Agent metadata

#### Usage

```bash theme={null}
idyl agent edit <name-or-id> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `--annotation <stringToString>` | Agent annotations as key=value pairs; replaces the annotations map when supplied. |
| `--clear-annotations` | Remove all Agent annotations. |
| `--clear-labels` | Remove all Agent labels. |
| `--id` | Address the stable Agent ID instead of its name. |
| `--label <stringToString>` | Agent labels as key=value pairs; replaces the labels map when supplied. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent get`

Read an Agent

#### Usage

```bash theme={null}
idyl agent get <name-or-id> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `--id` | Address the stable Agent ID instead of its name. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent list`

List Agents in the selected Namespace and Subnet, in stable ID order.
Use --continue with the returned cursor for the next page. Metadata can
change between pages. JSON and YAML retain the exact totalCount string.

#### Usage

```bash theme={null}
idyl agent list [flags]
```

#### Aliases

* `ls`

#### Flags

| Flag | Description |
| - | - |
| `--continue <string>` | Opaque cursor from the previous page. |
| `--limit <uint>` | Maximum items in one page; zero uses the service default. Default: `0`. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent revision`

Publish, read and delete immutable Agent Revisions

#### Usage

```bash theme={null}
idyl agent revision
```

#### Aliases

* `revisions`

#### Commands

| Command | Description |
| - | - |
| `idyl agent revision delete` | Delete a Revision from new instantiation |
| `idyl agent revision get` | Read Revision publication progress |
| `idyl agent revision instantiate` | Admit a fixed population from a pinned Revision |
| `idyl agent revision list` | List an Agent's Revisions |
| `idyl agent revision publish` | Publish a Revision from selected saved files |

### `idyl agent revision delete`

Delete a Revision so it admits no new Run.

A deleted Revision reports the deleted state. Actors already pinned to it keep
its immutable definition, and its saved template remains while existing Actors
or reads still need it.

You will be prompted for confirmation unless the --yes flag is provided.

#### Usage

```bash theme={null}
idyl agent revision delete <agent> <revision-id> [flags]
```

#### Aliases

* `rm`

#### Flags

| Flag | Description |
| - | - |
| `--id` | Address the stable Agent ID instead of its name. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
idyl agent revision delete analysis 01890a5d-ac96-774b-bcce-b302099a8061
idyl agent revision delete analysis 01890a5d-ac96-774b-bcce-b302099a8061 --yes -o json
```

### `idyl agent revision get`

Read Revision publication progress

#### Usage

```bash theme={null}
idyl agent revision get <agent> <revision-id> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `--id` | Address the stable Agent ID instead of its name. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent revision instantiate`

Admit a durable Run and return its creation progress before every Actor is ready.
Count is an exact unsigned decimal string, including zero. Record-only creation
allocates no Actor execution. Optional initial JSON input waits for each fixed
member. Choose what later Actor deletion does with its Computer explicitly.

#### Usage

```bash theme={null}
idyl agent revision instantiate <revision-id> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `--count <string>` | Required. Exact number of durable members, including zero. |
| `--disposition <string>` | Required. Computer disposition on Actor deletion: delete or retain. |
| `--idempotency-key <string>` | Required. Stable admission key; reuse it for the same request. |
| `--initial-input <string>` | Optional initial input as a JSON file. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent revision list`

List one cursor page of an Agent's Revisions, oldest first, deleted ones included.
Use --continue with the returned cursor for the next page. JSON and YAML retain
the exact totalCount string.

#### Usage

```bash theme={null}
idyl agent revision list <agent> [flags]
```

#### Aliases

* `ls`

#### Flags

| Flag | Description |
| - | - |
| `--continue <string>` | Opaque cursor from the previous page. |
| `--id` | Address the stable Agent ID instead of its name. |
| `--limit <uint>` | Maximum items in one page; zero uses the service default. Default: `0`. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |

### `idyl agent revision publish`

Publish an immutable Revision from a canonical publication request file.
The request names a saved source VersionRef, explicit selected paths, program
argv, execution settings and an idempotencyKey. Reuse the same request and key
when retrying. A returned publishing state is durable progress, not readiness.

#### Usage

```bash theme={null}
idyl agent revision publish <agent> [flags]
```

#### Flags

| Flag | Description |
| - | - |
| `-f <string>, --file <string>` | Required. Canonical publication request in JSON or YAML. |
| `--id` | Address the stable Agent ID instead of its name. |
| `-o <string>, --output <string>` | Output format: table, json, yaml. Default: `table`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.