feat(cli): docker agent view — inspect any agent reference without running it

[krisfoster]

Overview

Add a `docker agent view` command to the Diagnose group that resolves any agent reference and shows what's inside: name, source, model, description, instruction, and toolsets. Works with everything `docker agent run` accepts. No model calls, no model credentials needed.

Motivation

There's no straightforward way to inspect an agent before running it. If someone shares an OCI reference or a URL, you either run it blind or go digging through the source YAML yourself. A few things exist today, but none of them quite do the job:

• `docker agent debug config `: resolves and dumps the canonical YAML after schema migration. Useful for debugging how a config is parsed, but not designed to answer "what does this agent actually do?" at a glance. The whole `debug` group is also hidden from `--help`.
• `docker agent run --dry-run`: loads the team but only prints `"Dry run mode enabled. Agent initialized but will not execute."` — no config output at all.
• The `?` key in the `--agent-picker` TUI: shows a YAML overlay, but only inside the interactive picker. You can't script it.

`docker agent view` addresses this. It's oriented around human understanding of what an agent does, not debugging how the config is parsed. It also makes local file inspection feel consistent with OCI and URL refs: you can't `cat` an OCI image or a remote URL, so a single command that works across all reference types is genuinely useful. It promotes an already-working hidden code path to a first-class surface, one that's actually visible in `--help`.

The CLI already has `docker agent models` and `docker agent toolsets` to discover available models and toolset types. There's no equivalent for agents themselves.

Use cases

1. Someone finds `agentcatalog/review-pr` in a blog post and wants to know what model it uses and what tools it has before running it.
2. A team shares an agent via URL; a colleague checks the model before running it in a pipeline: `docker agent view https://example.com/agent.yaml --format json | jq '.agents[].model'`
3. A developer maintains a multi-agent `team.yaml` and wants a quick summary of all agents and their models without wading through the raw YAML.

Proposed solution

New top-level command `docker agent view` in the Diagnose group (same group as `docker agent models` and `docker agent toolsets`).

Signature:
```
docker agent view |
```

Accepts the same addressing mechanisms as `docker agent run`: local file (`.yaml`, `.yml`, `.hcl`), local directory, OCI reference, HTTPS URL, built-in name, or user alias. Requires an explicit argument — running `docker agent view` with no argument prints help.

Flags:

Flag	Default	Description
`--format`	`table`	Output format: `table`, `yaml`, `json`
`--agent`, `-a`	(first agent)	Show a specific agent from a multi-agent config

Single agent, default output:
```
$ docker agent view agentcatalog/pirate

Agent: pirate
Source: agentcatalog/pirate (OCI)
Model: openai/gpt-4o
Description: A swashbuckling pirate assistant

Instruction:
You are a helpful pirate who answers questions in the style of a 17th century
buccaneer. Always say "Arr!" at least once per response. Never break character.

Toolsets:
filesystem
shell

Multi-agent: no
```

Multi-agent config:
```
$ docker agent view ./team.yaml

Source: ./team.yaml (local file)
Default: root

AGENT MODEL DESCRIPTION
root anthropic/claude-sonnet-4 Orchestrates the team
reviewer openai/gpt-4o Reviews pull requests
coder dmr/ai/qwen3 Writes code

Use --agent / -a to inspect a specific agent in detail.
```

Directory:
```
$ docker agent view ./my-agents/

Source: ./my-agents/ (directory)

FILE AGENTS
coder.yaml coder
reviewer.yaml reviewer
team.yaml root, reviewer, coder
```

`--format yaml` outputs the canonical parsed YAML after schema migration. See the note on env-var expansion below.

`--format json`:
```json
{
"source": "agentcatalog/pirate",
"source_type": "oci",
"agents": [
{
"name": "pirate",
"model": "openai/gpt-4o",
"description": "A swashbuckling pirate assistant",
"instruction": "You are a helpful pirate who answers questions in the style of a 17th century buccaneer...",
"toolsets": [
{"type": "filesystem"},
{"type": "shell"}
]
}
]
}
```

`source_type` is one of: `local`, `directory`, `oci`, `url`, `builtin`, `alias`. For an alias, the value reflects what the alias resolves to, not the alias name itself.

Note: toolset entries reflect the YAML declaration (type name and ref, if any), not the individual tool functions each toolset exposes at runtime. Use `docker agent debug toolsets ` for fully resolved tool names.

Design notes

OCI references make a network call. `docker agent view` on an OCI reference checks the remote registry for digest updates before serving from the local cache — the same behaviour as `docker agent run`. Results are memoised within a session, but cold calls pay a network round-trip. `view` is fast for local files and built-ins; OCI and URL refs depend on network conditions.

Env-var expansion in `--format yaml` and `--format json`. `config.Load()` expands `${VAR}` references in the config before output. This means both formats show resolved values rather than the original template strings. If your config references env vars that contain sensitive values (account IDs, tokens in base URLs), the expanded output will contain those values in plain text. Be careful when sharing this output.

Multi-agent configs with external sub-agents. If a multi-agent config references external agents by OCI ref or URL, `docker agent view` shows the reference string only — it does not pull or inspect the sub-agents. Run `docker agent view ` separately on each sub-agent reference to inspect it.

Alternatives

• `docker agent debug config `: does the core job but is hidden, YAML-only, and designed for debugging config parsing rather than understanding what an agent does. Adding `--format table|json` to it would conflate two different concerns in a hidden command.
• `docker agent run --dry-run`: initialises the team but produces no config output, and triggers toolset initialisation that may need credentials.
• The `--agent-picker` TUI overlay: interactive-only and not scriptable.

Implementation notes

The resolution path (`config.Resolve()` → `config.Load()`) is already used by `docker agent debug config` and needs no model credentials or toolset initialisation. `docker agent view` reuses that path and adds table and JSON renderers on top. It deliberately doesn't call `teamloader.Load()`, which initialises toolsets and may require API keys.

A note on this issue

This issue was drafted with the help of Claude, including research into the existing codebase to identify the hidden `debug config` subcommand and the agent picker YAML overlay before proposing anything new.

Related issues

• Feature Request: docker agent toolsets - list built-in toolset types #3613: `docker agent toolsets` — closed, implemented in `cmd/root/toolsets.go`. Same pattern: a discoverability command in the Diagnose group.
• Hidden `docker agent debug config`: the underlying implementation this promotes.

[dgageot]

This already exists with this syntax: docker agent debug config XXXX

[krisfoster]

docker agent debug doesn't show up in the help. Would a good solution then be to add this to the help output? I think it is genuinely useful. thanks!