> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/agent.md).

# observal agent

Create, compose, publish, install, and govern agents. An agent bundles MCP servers, skills, hooks, prompts, and sandboxes into one versioned Registry object.

Canonical identities use `namespace/slug`. Commands also accept UUIDs, unambiguous bare names, aliases, and row numbers from the latest Agent list.

## Commands

| Command          | Purpose                                                   |
| ---------------- | --------------------------------------------------------- |
| `create`         | Create from flags, JSON, or an interactive wizard         |
| `bulk-create`    | Validate or create multiple agents from JSON              |
| `list`           | List approved visible agents                              |
| `my`             | List agents owned or co-authored by the user              |
| `show`           | Show an agent and its composition                         |
| `install`        | Generate an installation config without writing files     |
| `pull`           | Generate and write a complete harness installation        |
| `archive`        | Archive an agent                                          |
| `delete`         | Compatibility alias for `archive`                         |
| `unarchive`      | Restore an archived agent                                 |
| `init`           | Create a local `observal-agent.yaml`                      |
| `add`            | Add a Registry component UUID to local YAML               |
| `build`          | Validate local composition and target scope               |
| `publish`        | Create, update, save, or submit an agent                  |
| `release`        | Publish a reviewed version bump                           |
| `versions`       | List version history                                      |
| `outdated`       | Show which pinned components have newer approved releases |
| `transfer-owner` | Transfer ownership                                        |
| `co-authors`     | List, add, or remove co-authors                           |

Every leaf command supports `--output table|json`. JSON success output contains no Rich text, prompt, banner, or spinner. JSON failures leave stdout empty and write one categorized object to stderr.

## Create

Use complete flags for automation:

```bash
observal agent create \
  --name reviewer \
  --description 'Reviews changes' \
  --prompt 'Review carefully.' \
  --model claude-sonnet-4 \
  --harness kiro \
  --output json
```

Other modes:

```bash
observal agent create --from-file agent.json --output json
observal agent create
```

The no-flag form is interactive and cannot run in JSON mode. Flag mode requires `--name` and either `--prompt` or `--prompt-file`. Versions must be semantic versions and every repeated `--harness` must be registered.

`--team HANDLE --visibility team` creates a private teamspace agent. `--visibility team` requires `--team`.

JSON returns the direct server Agent object.

## Bulk create

Input may be an array or an object containing an `agents` array:

```json
{
  "agents": [
    {
      "name": "reviewer",
      "version": "1.0.0",
      "owner": "alice",
      "prompt": "Review carefully.",
      "model_name": "claude-sonnet-4",
      "components": []
    }
  ]
}
```

```bash
observal agent bulk-create --from-file agents.json --dry-run --output json
observal agent bulk-create --from-file agents.json --yes --output json
```

Input contains 1-50 agents. The CLI rejects malformed fields and duplicate canonical names before HTTP, and the server applies the same duplicate rules. JSON mode requires either `--dry-run` or `--yes`. Results include per-agent statuses, summary counts, and `partial`. Item errors set `partial: true` and exit with code 11; skips alone remain successful.

## List, my, and show

```bash
observal agent list --search 'incident response' --output json
observal agent list --namespace alice --page 2 --limit 20 --output json
observal agent list --team platform --output json
observal agent my --output json
observal agent show alice/reviewer --output json
```

`list` JSON is paginated:

```json
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 50
}
```

The most recent `list` or `my` result is cached for row-number references. Empty results clear stale Agent rows. `--interactive` is human-only and cannot be combined with JSON.

`my` returns the standard `items`, `total`, `page`, and `page_size` envelope, including pending, approved, rejected, and archived agents. Empty results use `items: []`.

`show` returns the direct Agent object, including component links and success criteria.

## Generate installation config

`install` asks the server to generate config but does not write it:

```bash
observal agent install alice/reviewer --harness kiro --output json
```

JSON returns the complete server installation result. Legacy `--raw` prints only `config_snippet`; new automation should use the shared output option.

Use [`observal agent pull`](/cli-reference/pull.md) to write and track the generated installation.

## Archive, delete, and restore

```bash
observal agent archive alice/reviewer --yes --output json
observal agent delete alice/reviewer --yes --output json
observal agent unarchive alice/reviewer --yes --output json
```

`delete` is an alias for the same reversible archive operation. JSON mode never prompts and requires `--yes`. JSON returns the direct updated Agent object.

## Local authoring workflow

### Initialize

```bash
observal agent init \
  --dir ./reviewer \
  --name reviewer \
  --description 'Reviews changes' \
  --prompt-file ./PROMPT.md \
  --model claude-sonnet-4 \
  --harness kiro \
  --output json
```

The no-flag form is interactive. JSON mode requires complete flags and refuses to overwrite an existing definition. Writes are atomic.

#### From a working session

```bash
observal agent init --from-capabilities --name pr-review-flow --dir ./pr-review-flow --output json
observal agent init --from-capabilities --since 3d --name data-helper --output json
```

`--from-capabilities` pre-fills `components` and `supported_harnesses` from the resources recorded in the capability lock for the current directory (see [`observal discover`](/cli-reference/discover.md)): everything loaded with `discover use` and every component installed here in the last 24 hours (`--since` accepts `45m`, `2h`, `3d`, `1w`). In JSON mode a default description and prompt are filled in when omitted. Agents cannot nest other agents, so a pulled agent is reported under `from_capabilities.skipped_agents` rather than added. Exit code `5` when nothing was used in the window.

JSON returns:

```json
{
  "path": "/work/reviewer/observal-agent.yaml",
  "agent": {
    "name": "reviewer",
    "version": "1.0.0"
  }
}
```

### Add components

Find a component in Registry JSON, then copy its UUID:

```bash
observal registry skill list --search review --output json
observal agent add skill 22222222-2222-2222-2222-222222222222 --dir ./reviewer --output json
```

Valid types are `mcp`, `skill`, `hook`, `prompt`, and `sandbox`. Duplicate type and UUID pairs return conflict exit code 6. Invalid types or IDs return validation exit code 7.

Pin an exact component release with `--version`:

```bash
observal agent add mcp 33333333-3333-3333-3333-333333333333 --version 1.4.2 --dir ./reviewer --output json
```

This writes `version: 1.4.2` on the component entry. Without a version, the Agent keeps the version its current release pins, or pins the latest approved release when it first gains the component. Versions are matched exactly; `latest` and ranges are not accepted. A release pins approved versions only; a draft may also pin a component release still in review, but only one you can read (your own component, or as an admin or reviewer).

JSON returns the YAML path and added component.

### Build

```bash
observal agent build --dir ./reviewer --output json
observal agent build --dir ./reviewer --team platform --visibility team --output json
```

Build verifies every component, checks that any pinned component `version` exists, and validates whether private components are visible to the target owner. A successful JSON result contains `valid`, `agent`, `components`, and `issues`. Invalid composition exits with code 7 and leaves JSON stdout empty; the stderr error includes the same repairable data under `error.result`.

### Publish

```bash
observal agent publish --dir ./reviewer --output json
observal agent publish --dir ./reviewer --draft --output json
observal agent publish --submit alice/reviewer --output json
observal agent publish --dir ./reviewer --update --bump minor --output json
```

`--draft` and `--submit` are mutually exclusive. Scope changes cannot be combined with `--update`; use ownership transfer or a separate visibility operation. Non-interactive updates may use `--bump patch|minor|major`.

`--update` edits the latest version in place, so it only works while that version is a draft, pending, or rejected. An approved version is immutable: installs and locks depend on it. The server answers conflict exit code 6 and points to `observal agent release`, which publishes a new version for review.

JSON returns the direct created, saved, submitted, or updated Agent object.

## Release and versions

```bash
observal agent release alice/reviewer --bump patch --dir ./reviewer --output json
observal agent versions alice/reviewer --page 1 --page-size 50 --output json
```

Release obtains the server's semantic-version suggestion, submits the complete YAML snapshot, then updates local YAML atomically only after the server accepts the release. A failed server request leaves the local version unchanged.

Every release pins each component to an exact version, and those pins are what every pull of the release installs. A release keeps the pins of the Agent's current release, so components never move unless the author asks:

* give a component a `version` in the YAML to pin that release;
* pass `--refresh-components` to move every other component to its latest approved release.

```bash
observal agent release alice/reviewer --bump minor --dir ./reviewer --refresh-components --output json
```

Approval freezes the release's lock. The review gate checks that each pinned component version is approved.

## Check component pins

```bash
observal agent outdated alice/reviewer
observal agent outdated alice/reviewer --version 1.2.0 --output json
```

Lists each component the Agent version pins with its pinned version, its latest approved release, and a status: `current`, `outdated`, or `unlocked` (Agent versions released before pinning). Archived components are marked. Defaults to the latest Agent version.

JSON returns `agent_id`, `qualified_name`, `version`, `components`, and a `summary` with `total`, `outdated`, `unlocked`, and `archived` counts. Consumers keep installing the pins; this is the author's cue to release a refreshed version.

Versions JSON returns the direct paginated server object. Page size is 1 through 100.

## Transfer ownership

```bash
observal agent transfer-owner alice/reviewer bob --yes --output json
```

The username may optionally begin with `@`. JSON mode requires `--yes` and returns the direct server result.

## Co-authors

Co-authors can edit and publish the same Agent:

```bash
observal agent co-authors list alice/reviewer --output json
observal agent co-authors add alice/reviewer dev@example.com --output json
observal agent co-authors add alice/reviewer @dev --output json
observal agent co-authors remove alice/reviewer 550e8400-e29b-41d4-a716-446655440000 --output json
```

List returns the standard list envelope. Add returns the added user. Remove requires the user UUID returned by list and returns the direct deletion result.

## Pull

```bash
observal agent pull alice/reviewer --harness kiro --no-prompt --output json
```

Pull writes harness files, records the exact Agent and component versions in `observal.lock` and the local lockfile, and reports every file and setup action. Later pulls keep the locked version until `--upgrade` or `--version`. See the [Pull reference](/cli-reference/pull.md) for pinning, strict mode, path, secret, merge, dry-run, and JSON behavior.

## Exit codes

Common Agent failures use:

| Code | Meaning                                                                         |
| ---- | ------------------------------------------------------------------------------- |
| 3    | Authentication required or failed                                               |
| 4    | Permission denied                                                               |
| 5    | Agent, component, or local definition not found                                 |
| 6    | Existing definition, duplicate component, or unsafe config merge conflict       |
| 7    | Invalid name, version, harness, component, scope, or command combination        |
| 8    | Server rate limit                                                               |
| 9    | Server, filesystem, lockfile, generated config, or setup dependency unavailable |
| 10   | CLI and server version mismatch                                                 |
| 11   | Bulk operation returned one or more item errors                                 |

## Related

* [`observal agent pull`](/cli-reference/pull.md): install into a harness
* [`observal registry`](/cli-reference/registry.md): manage Agent components
* [`observal registry models`](/cli-reference/models.md): inspect exact harness model IDs


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.observal.io/cli-reference/agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.