forked from cleveragents/cleveragents-core
17988 lines
749 KiB
Markdown
17988 lines
749 KiB
Markdown
## CLI Commands
|
||
|
||
!!! adr "Architecture Decision"
|
||
The CLI command structure, output rendering, and interaction patterns are defined in [ADR-021: CLI and Output Rendering](adr/ADR-021-cli-and-output-rendering.md).
|
||
|
||
### Command Synopsis
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: cyan; font-weight: 600;">agents|cleveragents</span> [<span style="color: cyan;">--data-dir</span> <span style="color: #66cc66;"><DATA_PATH></span>] [<span style="color: cyan;">--config-path</span> <span style="color: #66cc66;"><CONFIG_PATH></span>]
|
||
[<span style="color: cyan;">--format</span> (<span style="color: magenta;">rich|color|table|plain|json|yaml</span>)]
|
||
[<span style="color: cyan;">--help</span>|<span style="color: yellow;">-h</span>] [<span style="color: cyan;">--version</span>]
|
||
[<span style="color: cyan;">--install-completion</span> [<span style="color: #66cc66;"><INST_SHELL></span>]] [<span style="color: cyan;">--show-completion</span> [<span style="color: #66cc66;"><SHOW_SHELL></span>]]
|
||
[<span style="color: yellow;">-v</span>...] <span style="color: #66cc66;"><COMMAND></span> [<span style="color: #66cc66;"><ARGS></span>...]
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> version
|
||
<span style="color: cyan; font-weight: 600;">agents</span> info
|
||
<span style="color: cyan; font-weight: 600;">agents</span> diagnostics
|
||
<span style="color: cyan; font-weight: 600;">agents</span> init [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>]
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session create [<span style="color: cyan;">--actor</span> <span style="color: #66cc66;"><ACTOR></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session list
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session show <span style="color: #66cc66;"><SESSION_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session delete [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><SESSION_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session export [(<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><FILE></span>] <span style="color: #66cc66;"><SESSION_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session import (<span style="color: magenta;"><span style="color: cyan;">--input</span>|<span style="color: yellow;">-i</span></span>) <span style="color: #66cc66;"><FILE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: cyan;">--session</span> <span style="color: #66cc66;"><SESSION_ID></span> [<span style="color: cyan;">--actor</span> <span style="color: #66cc66;"><ACTOR></span>] [<span style="color: cyan;">--stream</span>] <span style="color: #66cc66;"><PROMPT></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project create [(<span style="color: magenta;"><span style="color: cyan;">--description</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><DESC></span>] [<span style="color: cyan;">--resource</span> <span style="color: #66cc66;"><RESOURCE></span>]...
|
||
[<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;"><INVARIANT></span>]... [<span style="color: cyan;">--invariant-actor</span> <span style="color: #66cc66;"><ACTOR></span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project link-resource [<span style="color: cyan;">--read-only</span>] <span style="color: #66cc66;"><PROJECT></span> <span style="color: #66cc66;"><RESOURCE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project unlink-resource [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PROJECT></span> <span style="color: #66cc66;"><RESOURCE_NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) NS] [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project show <span style="color: #66cc66;"><PROJECT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project delete [<span style="color: cyan;">--force</span>|<span style="color: yellow;">-f</span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project context set[<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--include-resource</span> <span style="color: #66cc66;"><INCLUDE_RESOURCE></span>]...
|
||
[<span style="color: cyan;">--exclude-resource</span> <span style="color: #66cc66;"><EXCLUDE_RESOURCE></span>]...
|
||
[<span style="color: cyan;">--include-path</span> <span style="color: #66cc66;"><INCLUDE_GLOB></span>]...
|
||
[<span style="color: cyan;">--exclude-path</span> <span style="color: #66cc66;"><EXCLUDE_GLOB></span>]...
|
||
[<span style="color: cyan;">--hot-max-tokens</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--warm-max-decisions</span> <span style="color: #66cc66;"><N_WARM_MAX></span>]
|
||
[<span style="color: cyan;">--cold-max-decisions</span> <span style="color: #66cc66;"><N_COLD_MAX></span>]
|
||
[<span style="color: cyan;">--query-limit</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--max-file-size</span> <span style="color: #66cc66;"><MAX_FILE_BYTES></span>]
|
||
[<span style="color: cyan;">--max-total-size</span> <span style="color: #66cc66;"><MAX_TOTAL_BYTES></span>]
|
||
[<span style="color: cyan;">--summarize</span>|<span style="color: cyan;">--no-summarize</span>]
|
||
[<span style="color: cyan;">--summary-max-tokens</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]...
|
||
[<span style="color: cyan;">--default-breadth</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--default-depth</span> <span style="color: #66cc66;"><INT_OR_NAME></span>]
|
||
[<span style="color: cyan;">--depth-gradient</span> <span style="color: #66cc66;"><HOP:INT_OR_NAME></span>]...
|
||
[<span style="color: cyan;">--skeleton-ratio</span> <span style="color: #66cc66;"><FLOAT></span>]
|
||
[<span style="color: cyan;">--temporal-scope</span> (<span style="color: magenta;">current|recent|all</span>)]
|
||
[<span style="color: cyan;">--auto-refresh</span>|<span style="color: cyan;">--no-auto-refresh</span>]
|
||
[<span style="color: cyan;">--execution-environment</span> <span style="color: #66cc66;"><RESOURCE_NAME></span>]
|
||
[<span style="color: cyan;">--execution-env-priority</span> (<span style="color: magenta;">fallback|override</span>)]
|
||
[<span style="color: cyan;">--clear</span>] <span style="color: #66cc66;"><PROJECT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project context show [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
<span style="color: #66cc66;"><PROJECT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project context inspect [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]
|
||
[<span style="color: cyan;">--focus</span> <span style="color: #66cc66;"><UKO_URI></span>]...
|
||
[<span style="color: cyan;">--breadth</span> <span style="color: #66cc66;"><N></span>] [<span style="color: cyan;">--depth</span> <span style="color: #66cc66;"><INT_OR_NAME></span>]
|
||
<span style="color: #66cc66;"><PROJECT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> project context simulate [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--budget</span> <span style="color: #66cc66;"><TOKENS></span>]
|
||
[<span style="color: cyan;">--focus</span> <span style="color: #66cc66;"><UKO_URI></span>]...
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]...
|
||
<span style="color: #66cc66;"><PROJECT></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> validation attach [<span style="color: cyan;">--project</span> <span style="color: #66cc66;"><PROJECT></span>|<span style="color: cyan;">--plan</span> <span style="color: #66cc66;"><PLAN_ID></span>]
|
||
<span style="color: #66cc66;"><RESOURCE></span> <span style="color: #66cc66;"><VALIDATION></span> [<span style="color: #66cc66;"><ARGS></span>...]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> validation detach [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><ATTACHMENT_ID></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor run [(<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><OUTPUT_FILE></span>]
|
||
[<span style="color: yellow;">-v</span>...] [<span style="color: cyan;">--unsafe</span>|<span style="color: yellow;">-u</span>] [<span style="color: cyan;">--context</span> <span style="color: #66cc66;"><CONTEXT_NAME></span>]
|
||
[<span style="color: cyan;">--context-dir</span> <span style="color: #66cc66;"><CONTEXT_PATH></span>] [<span style="color: cyan;">--load-context</span> <span style="color: #66cc66;"><LOAD_CONTEXT_NAME></span>]
|
||
[(<span style="color: magenta;"><span style="color: cyan;">--temperature</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TEMP></span>] [<span style="color: cyan;">--allow-rxpy-in-run-mode</span>]
|
||
[<span style="color: cyan;">--skill</span> <span style="color: #66cc66;"><SKILL></span>]... <span style="color: #66cc66;"><NAME></span> <span style="color: #66cc66;"><PROMPT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor remove <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor list
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor show <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] (<span style="color: magenta;"><span style="color: cyan;">--all</span>|<span style="color: yellow;">-a</span>|<span style="color: #66cc66;"><NAME></span></span>)
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context list [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context show <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context export (<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><FILE></span> <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context import [<span style="color: cyan;">--update</span>] (<span style="color: magenta;"><span style="color: cyan;">--input</span>|<span style="color: yellow;">-i</span></span>) <span style="color: #66cc66;"><FILE></span> [<span style="color: #66cc66;"><NAME></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> actor context clear [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] (<span style="color: magenta;"><span style="color: cyan;">--all</span>|<span style="color: yellow;">-a</span>|<span style="color: #66cc66;"><NAME></span></span>)
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> skill remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> skill list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--source</span> <span style="color: #66cc66;"><SOURCE></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> skill show <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> skill tools <span style="color: #66cc66;"><NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> tool remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> tool list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--source</span> <span style="color: #66cc66;"><SOURCE></span>] [<span style="color: cyan;">--type</span> (<span style="color: magenta;">tool|validation</span>)] [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> tool show <span style="color: #66cc66;"><NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> lsp add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> lsp remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> lsp list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--language</span> <span style="color: #66cc66;"><LANG></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> lsp show <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> lsp serve [<span style="color: cyan;">--log-level</span> <span style="color: #66cc66;"><LEVEL></span>]
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource type add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource type remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource type list [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource type show <span style="color: #66cc66;"><NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource add [(<span style="color: magenta;"><span style="color: cyan;">--description</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><DESC></span>] [<span style="color: cyan;">--update</span>] <span style="color: #66cc66;"><TYPE></span> <span style="color: #66cc66;"><NAME></span> [type-specific-flags...]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource list [<span style="color: cyan;">--all</span>] [(<span style="color: magenta;"><span style="color: cyan;">--type</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TYPE></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource show <span style="color: #66cc66;"><RESOURCE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource inspect [<span style="color: cyan;">--tree</span>] [<span style="color: cyan;">--file</span> <span style="color: #66cc66;"><PATH></span>] <span style="color: #66cc66;"><RESOURCE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource tree [(<span style="color: magenta;"><span style="color: cyan;">--depth</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><N></span>] [(<span style="color: magenta;"><span style="color: cyan;">--type</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TYPE></span>] <span style="color: #66cc66;"><RESOURCE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource link-child <span style="color: #66cc66;"><PARENT></span> <span style="color: #66cc66;"><CHILD></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource unlink-child [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PARENT></span> <span style="color: #66cc66;"><CHILD></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource stop <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> resource rebuild <span style="color: #66cc66;"><NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan list [<span style="color: cyan;">--phase</span> <span style="color: #66cc66;"><PHASE></span>] [<span style="color: cyan;">--state</span> <span style="color: #66cc66;"><STATE></span>] [<span style="color: cyan;">--project</span> <span style="color: #66cc66;"><PROJECT></span>]
|
||
[<span style="color: cyan;">--action</span> <span style="color: #66cc66;"><ACTION></span>] [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan use [<span style="color: cyan;">--automation-profile</span> <span style="color: #66cc66;"><PROFILE></span>]
|
||
[<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;"><INVARIANT></span>]...
|
||
[<span style="color: cyan;">--strategy-actor</span> <span style="color: #66cc66;"><STRATEGY_ACTOR></span>]
|
||
[<span style="color: cyan;">--execution-actor</span> <span style="color: #66cc66;"><EXEC_ACTOR></span>]
|
||
[<span style="color: cyan;">--estimation-actor</span> <span style="color: #66cc66;"><EST_ACTOR></span>]
|
||
[<span style="color: cyan;">--invariant-actor</span> <span style="color: #66cc66;"><INV_ACTOR></span>]
|
||
[<span style="color: cyan;">--execution-environment</span> <span style="color: #66cc66;"><RESOURCE_NAME></span>]
|
||
[<span style="color: cyan;">--execution-env-priority</span> (<span style="color: magenta;">fallback|override</span>)]
|
||
[<span style="color: cyan;">--arg</span>/<span style="color: yellow;">-a</span> name=value]...
|
||
<span style="color: #66cc66;"><ACTION></span> <span style="color: #66cc66;"><PROJECT></span>...
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan execute <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan apply [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan status <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan cancel [(<span style="color: magenta;"><span style="color: cyan;">--reason</span>|<span style="color: yellow;">-r</span></span>) <span style="color: #66cc66;"><REASON></span>] <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan tree [<span style="color: cyan;">--show-superseded</span>] <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan explain [<span style="color: cyan;">--show-context</span>] [<span style="color: cyan;">--show-reasoning</span>] <span style="color: #66cc66;"><DECISION_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan correct <span style="color: cyan;">--mode</span> (<span style="color: magenta;">revert|append</span>) (<span style="color: magenta;"><span style="color: cyan;">--guidance</span>|<span style="color: yellow;">-g</span></span>) <span style="color: #66cc66;"><GUIDANCE></span>
|
||
[<span style="color: cyan;">--dry-run</span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><DECISION_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan diff (<span style="color: magenta;"><span style="color: cyan;">--correction</span> <span style="color: #66cc66;"><CORRECTION_ATTEMPT_ID></span>|<span style="color: #66cc66;"><PLAN_ID></span></span>)
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan artifacts <span style="color: #66cc66;"><PLAN_ID></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan prompt <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><GUIDANCE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> plan rollback [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><CHECKPOINT_ID></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><CFG_FILE></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> action list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [(<span style="color: magenta;"><span style="color: cyan;">--state</span>|<span style="color: yellow;">-s</span></span>) <span style="color: #66cc66;"><STATE></span>] [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> action show <span style="color: #66cc66;"><ACTION_NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> action archive <span style="color: #66cc66;"><ACTION_NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> automation-profile add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> automation-profile remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> automation-profile list [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> automation-profile show <span style="color: #66cc66;"><NAME></span>
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> config set <span style="color: #66cc66;"><key></span> <span style="color: #66cc66;"><value></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> config get <span style="color: #66cc66;"><key></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> config list [<span style="color: cyan;">--filter-values</span> <span style="color: #66cc66;"><REGEX></span>] [<span style="color: #66cc66;"><REGEX></span>]
|
||
|
||
<span style="color: cyan; font-weight: 600;">agents</span> invariant add [<span style="color: cyan;">--global</span>] [(<span style="color: cyan;">--project</span>|<span style="color: yellow;">-p</span>) PROJECT] [<span style="color: cyan;">--plan</span> PLAN_ID]...
|
||
[<span style="color: cyan;">--action</span> ACTION]... <span style="color: #66cc66;"><INVARIANT_TEXT></span>
|
||
<span style="color: cyan; font-weight: 600;">agents</span> invariant list [<span style="color: cyan;">--global</span>] [(<span style="color: cyan;">--project</span>|<span style="color: yellow;">-p</span>) PROJECT] [<span style="color: cyan;">--plan</span> PLAN_ID] [<span style="color: cyan;">--action</span> ACTION]
|
||
[<span style="color: cyan;">--effective</span>] [<span style="color: #66cc66;"><REGEX></span>]
|
||
<span style="color: cyan; font-weight: 600;">agents</span> invariant remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><INVARIANT_ID></span>
|
||
</code></pre></div>
|
||
|
||
### Command Reference
|
||
|
||
!!! info "Output Format Tabs"
|
||
Each command example below is shown in multiple output formats using content tabs. Select a tab to see how the same command renders in that format. The `table` format is visually identical to `rich` in static documentation (the difference is live animation). The `color` format has the same layout as `plain` but with ANSI color codes applied to headers, keys, and values. See **Output Rendering Framework** for full format specifications.
|
||
|
||
#### Global Options
|
||
|
||
!!! note "Purpose"
|
||
|
||
Configure global state locations and shell integration for every command.
|
||
|
||
**Arguments**
|
||
|
||
- `--data-dir PATH`: Overrides the global data directory (database, caches, sessions, logs). When omitted, the default data location is used.
|
||
- `--config-path PATH`: Overrides the global configuration file path. When omitted, the default config path is used.
|
||
- `--format rich|color|table|plain|json|yaml`: Set the output rendering format for all subcommands. When omitted, the value is read from the global config key `core.format`. If not set in config either, defaults to `rich`. See **Output Rendering Framework** for full details on each format.
|
||
|
||
??? tip "Available Output Formats"
|
||
|
||
| Format | Description | Best For |
|
||
| :----- | :---------- | :------- |
|
||
| `rich` | Modern rich CLI elements with dynamic effects, animated spinners, progress bars, and generous color | Interactive terminal use **(default)** |
|
||
| `color` | Plain scrolling text with ANSI color codes | Terminals that support color but not advanced rendering |
|
||
| `table` | ASCII box-drawing characters to create structured tables and panels with color | Structured visual output similar to examples in this document |
|
||
| `plain` | Plain text with no color codes or non-ASCII characters | Piping into files, logs, or non-terminal consumers |
|
||
| `json` | Structured JSON output for programmatic consumption | Scripts, CI/CD pipelines, programmatic consumption |
|
||
| `yaml` | Structured YAML output for programmatic consumption | Configuration, programmatic consumption |
|
||
- `--help`, `-h`: Print help for the current command.
|
||
- `--version`: Print the version and exit.
|
||
- `--install-completion [SHELL]`: Install shell completion for the given shell.
|
||
- `--show-completion [SHELL]`: Show the completion script for the given shell.
|
||
- `-v`: Increase log verbosity for a single invocation (repeatable). By default (no `-v`), only normal command output is shown on stdout; logging output is suppressed except on fatal errors where the application exits entirely and displays the error. Each additional `-v` raises the verbosity one level: `-v` = ERROR (non-fatal, recoverable errors), `-vv` = WARN (warnings that may indicate a degraded system but are not necessarily errors), `-vvv` = INFO (routine informative messages useful to common users), `-vvvv` = DEBUG (coarse debugging output), `-vvvvv` = TRACE (the most granular logging level available). Increased verbosity writes to both the log file and stderr by default, keeping log output separate from normal program output on stdout. The destination for log output raised by `-v` is configurable: it can be sent to the terminal (stderr by default, or redirected to another stream such as stdin or a device), to the log file only, or to both. See `core.log.terminal`, `core.log.terminal-stream`, and `core.log.file-enabled` configuration keys for details. This flag does not persist — it only affects the current invocation.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--data-dir</span> /srv/cleveragents <span style="color: cyan;">--config-path</span> /srv/cleveragents/config.toml info
|
||
|
||
╭─ System Snapshot ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">CleverAgents</span> 1.0.0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> local │
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> ready │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Paths ───────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /srv/cleveragents │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /srv/cleveragents/config.toml │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> /srv/cleveragents/logs │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> /srv/cleveragents/cache │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Database:</span> /srv/cleveragents/agents.db │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Runtime ──────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">PID:</span> 4127 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Uptime:</span> 00:14:32 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Python:</span> 3.13.1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Host:</span> devbox.local │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> linux │
|
||
╰────────────────────╯
|
||
|
||
╭─ Projects & Sessions ─╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Projects:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> 1 active │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> 3 │
|
||
╰───────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents --data-dir /srv/cleveragents --config-path /srv/cleveragents/config.toml info
|
||
|
||
System Snapshot
|
||
CleverAgents 1.0.0
|
||
Mode: local
|
||
Automation: review
|
||
Status: ready
|
||
|
||
Paths
|
||
Data Dir: /srv/cleveragents
|
||
Config: /srv/cleveragents/config.toml
|
||
Logs: /srv/cleveragents/logs
|
||
Cache: /srv/cleveragents/cache
|
||
Database: /srv/cleveragents/agents.db
|
||
|
||
Runtime
|
||
PID: 4127
|
||
Uptime: 00:14:32
|
||
Python: 3.13.1
|
||
Host: devbox.local
|
||
Platform: linux
|
||
|
||
Projects & Sessions
|
||
Projects: 2
|
||
Sessions: 1 active
|
||
Active Plans: 0
|
||
Actors: 3
|
||
|
||
[OK] Environment loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "info",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"system_snapshot": {
|
||
"name": "CleverAgents",
|
||
"version": "1.0.0",
|
||
"mode": "local",
|
||
"automation": "review",
|
||
"status": "ready"
|
||
},
|
||
"paths": {
|
||
"data_dir": "/srv/cleveragents",
|
||
"config": "/srv/cleveragents/config.toml",
|
||
"logs": "/srv/cleveragents/logs",
|
||
"cache": "/srv/cleveragents/cache",
|
||
"database": "/srv/cleveragents/agents.db"
|
||
},
|
||
"runtime": {
|
||
"pid": 4127,
|
||
"uptime": "00:14:32",
|
||
"python": "3.13.1",
|
||
"host": "devbox.local",
|
||
"platform": "linux"
|
||
},
|
||
"projects_and_sessions": {
|
||
"projects": 2,
|
||
"sessions": "1 active",
|
||
"active_plans": 0,
|
||
"actors": 3
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 12
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Environment loaded" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: info
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
system_snapshot:
|
||
name: CleverAgents
|
||
version: "1.0.0"
|
||
mode: local
|
||
automation: review
|
||
status: ready
|
||
paths:
|
||
data_dir: /srv/cleveragents
|
||
config: /srv/cleveragents/config.toml
|
||
logs: /srv/cleveragents/logs
|
||
cache: /srv/cleveragents/cache
|
||
database: /srv/cleveragents/agents.db
|
||
runtime:
|
||
pid: 4127
|
||
uptime: "00:14:32"
|
||
python: "3.13.1"
|
||
host: devbox.local
|
||
platform: linux
|
||
projects_and_sessions:
|
||
projects: 2
|
||
sessions: 1 active
|
||
active_plans: 0
|
||
actors: 3
|
||
timing:
|
||
duration_ms: 12
|
||
messages:
|
||
- level: ok
|
||
text: Environment loaded
|
||
```
|
||
|
||
#### agents version
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> version</code></pre></div>
|
||
|
||
**Purpose**
|
||
Print the current CLI version.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> version
|
||
|
||
╭─ CLI Version ────╮
|
||
│ <span style="color: cyan; font-weight: 600;">CleverAgents CLI</span> │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Version:</span> 1.0.0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Channel:</span> stable │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Python:</span> 3.13 │
|
||
╰──────────────────╯
|
||
|
||
╭─ Build ────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Build Date:</span> 2026-02-08 │
|
||
│ <span style="color: magenta; font-weight: 600;">Commit:</span> a17c3f9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Schema:</span> v3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> linux-x86_64 │
|
||
╰────────────────────────╯
|
||
|
||
╭─ Dependencies ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">LangGraph:</span> 0.2.60 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">LangChain:</span> 0.3.18 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">MCP SDK:</span> 1.4.0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Pydantic:</span> 2.10.4 │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Version reported
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents version
|
||
|
||
CLI Version
|
||
CleverAgents CLI
|
||
Version: 1.0.0
|
||
Channel: stable
|
||
Python: 3.13
|
||
|
||
Build
|
||
Build Date: 2026-02-08
|
||
Commit: a17c3f9
|
||
Schema: v3
|
||
Platform: linux-x86_64
|
||
|
||
Dependencies
|
||
LangGraph: 0.2.60
|
||
LangChain: 0.3.18
|
||
MCP SDK: 1.4.0
|
||
Pydantic: 2.10.4
|
||
|
||
[OK] Version reported
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "version",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"cli": {
|
||
"name": "CleverAgents CLI",
|
||
"version": "1.0.0",
|
||
"channel": "stable",
|
||
"python": "3.13"
|
||
},
|
||
"build": {
|
||
"build_date": "2026-02-08",
|
||
"commit": "a17c3f9",
|
||
"schema": "v3",
|
||
"platform": "linux-x86_64"
|
||
},
|
||
"dependencies": {
|
||
"langgraph": "0.2.60",
|
||
"langchain": "0.3.18",
|
||
"mcp_sdk": "1.4.0",
|
||
"pydantic": "2.10.4"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 8
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Version reported" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: version
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
cli:
|
||
name: CleverAgents CLI
|
||
version: "1.0.0"
|
||
channel: stable
|
||
python: "3.13"
|
||
build:
|
||
build_date: "2026-02-08"
|
||
commit: a17c3f9
|
||
schema: v3
|
||
platform: linux-x86_64
|
||
dependencies:
|
||
langgraph: "0.2.60"
|
||
langchain: "0.3.18"
|
||
mcp_sdk: "1.4.0"
|
||
pydantic: "2.10.4"
|
||
timing:
|
||
duration_ms: 8
|
||
messages:
|
||
- level: ok
|
||
text: Version reported
|
||
```
|
||
|
||
#### agents info
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> info</code></pre></div>
|
||
|
||
**Purpose**
|
||
Show configuration and runtime information useful for debugging or support.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> info
|
||
|
||
╭─ Environment ───────────────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /home/alex/.cleveragents │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> sqlite:///home/alex/.cleveragents/cleveragents.db │
|
||
│ <span style="color: yellow; font-weight: 600;">Server Mode:</span> disabled │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Platform:</span> Linux 6.8.0 (x86_64) │
|
||
╰─────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Runtime ─────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Providers:</span> 3 configured │
|
||
│ <span style="color: yellow; font-weight: 600;">Sessions:</span> 2 active │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 1 │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Storage ─────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> 118 MB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> 42 MB │
|
||
│ <span style="color: yellow; font-weight: 600;">Backups:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">DB Size:</span> 8 MB │
|
||
╰───────────────╯
|
||
|
||
╭─ Indexing ─────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Text Index:</span> ready │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Vector Index:</span> ready │
|
||
│ <span style="color: yellow; font-weight: 600;">Graph Store:</span> disabled │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 1,247 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment details ready
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents info
|
||
|
||
Environment
|
||
Data Dir: /home/alex/.cleveragents
|
||
Config: /home/alex/.cleveragents/config.toml
|
||
Database: sqlite:///home/alex/.cleveragents/cleveragents.db
|
||
Server Mode: disabled
|
||
Platform: Linux 6.8.0 (x86_64)
|
||
|
||
Runtime
|
||
Automation: review
|
||
Providers: 3 configured
|
||
Sessions: 2 active
|
||
Active Plans: 1
|
||
|
||
Storage
|
||
Cache: 118 MB
|
||
Logs: 42 MB
|
||
Backups: 3
|
||
DB Size: 8 MB
|
||
|
||
Indexing
|
||
Text Index: ready
|
||
Vector Index: ready
|
||
Graph Store: disabled
|
||
Indexed Files: 1,247
|
||
|
||
[OK] Environment details ready
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "info",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"environment": {
|
||
"data_dir": "/home/alex/.cleveragents",
|
||
"config": "/home/alex/.cleveragents/config.toml",
|
||
"database": "sqlite:///home/alex/.cleveragents/cleveragents.db",
|
||
"server_mode": "disabled",
|
||
"platform": "Linux 6.8.0 (x86_64)"
|
||
},
|
||
"runtime": {
|
||
"automation": "review",
|
||
"providers": 3,
|
||
"sessions": "2 active",
|
||
"active_plans": 1
|
||
},
|
||
"storage": {
|
||
"cache_mb": 118,
|
||
"logs_mb": 42,
|
||
"backups": 3,
|
||
"db_size_mb": 8
|
||
},
|
||
"indexing": {
|
||
"text_index": "ready",
|
||
"vector_index": "ready",
|
||
"graph_store": "disabled",
|
||
"indexed_files": 1247
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 18
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Environment details ready" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: info
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
environment:
|
||
data_dir: /home/alex/.cleveragents
|
||
config: /home/alex/.cleveragents/config.toml
|
||
database: sqlite:///home/alex/.cleveragents/cleveragents.db
|
||
server_mode: disabled
|
||
platform: Linux 6.8.0 (x86_64)
|
||
runtime:
|
||
automation: review
|
||
providers: 3
|
||
sessions: 2 active
|
||
active_plans: 1
|
||
storage:
|
||
cache_mb: 118
|
||
logs_mb: 42
|
||
backups: 3
|
||
db_size_mb: 8
|
||
indexing:
|
||
text_index: ready
|
||
vector_index: ready
|
||
graph_store: disabled
|
||
indexed_files: 1247
|
||
timing:
|
||
duration_ms: 18
|
||
messages:
|
||
- level: ok
|
||
text: Environment details ready
|
||
```
|
||
|
||
#### agents diagnostics
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> diagnostics</code></pre></div>
|
||
|
||
**Purpose**
|
||
Run health checks for configuration, providers, and filesystem permissions.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
|
||
|
||
╭─ Checks ────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
|
||
│ <span style="opacity: 0.7;">─────────────── ────── ──────────────</span> │
|
||
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
|
||
│ Database <span style="color: #66cc66; font-weight: 600;">OK</span> writable │
|
||
│ OPENAI_API_KEY <span style="color: yellow; font-weight: 600;">WARN</span> missing │
|
||
│ Anthropic key <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
|
||
│ Disk space <span style="color: #66cc66; font-weight: 600;">OK</span> 2.1 GB free │
|
||
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
|
||
│ Vector index <span style="color: #66cc66; font-weight: 600;">OK</span> faiss (CPU) │
|
||
│ Graph store <span style="color: yellow; font-weight: 600;">WARN</span> not configured │
|
||
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
|
||
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Summary ─────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
|
||
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 2 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 0.6s │
|
||
╰───────────────────╯
|
||
|
||
╭─ Recommendations ─────────────────────────────────────────────╮
|
||
│ - Set OPENAI_API_KEY to enable OpenAI models │
|
||
│ - Configure a graph store backend for structural code queries │
|
||
│ - Verify provider credentials via config │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: yellow; font-weight: 600;">⚠ WARN</span> 2 warnings require attention
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents diagnostics
|
||
|
||
Checks
|
||
Check Status Details
|
||
--------------- ------ --------------
|
||
Config file OK readable
|
||
Database OK writable
|
||
OPENAI_API_KEY WARN missing
|
||
Anthropic key OK configured
|
||
Disk space OK 2.1 GB free
|
||
Text index OK tantivy 0.22
|
||
Vector index OK faiss (CPU)
|
||
Graph store WARN not configured
|
||
File permissions OK data dir r/w
|
||
Git OK git 2.43.0
|
||
|
||
Summary
|
||
Checks: 10 total
|
||
Warnings: 2
|
||
Errors: 0
|
||
Duration: 0.6s
|
||
|
||
Recommendations
|
||
- Set OPENAI_API_KEY to enable OpenAI models
|
||
- Configure a graph store backend for structural code queries
|
||
- Verify provider credentials via config
|
||
|
||
[WARN] 2 warnings require attention
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "diagnostics",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"checks": [
|
||
{ "check": "Config file", "status": "ok", "details": "readable" },
|
||
{ "check": "Database", "status": "ok", "details": "writable" },
|
||
{ "check": "OPENAI_API_KEY", "status": "warn", "details": "missing" },
|
||
{ "check": "Anthropic key", "status": "ok", "details": "configured" },
|
||
{ "check": "Disk space", "status": "ok", "details": "2.1 GB free" },
|
||
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
|
||
{ "check": "Vector index", "status": "ok", "details": "faiss (CPU)" },
|
||
{ "check": "Graph store", "status": "warn", "details": "not configured" },
|
||
{ "check": "File permissions", "status": "ok", "details": "data dir r/w" },
|
||
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
|
||
],
|
||
"summary": {
|
||
"total": 10,
|
||
"warnings": 2,
|
||
"errors": 0,
|
||
"duration_s": 0.6
|
||
},
|
||
"recommendations": [
|
||
"Set OPENAI_API_KEY to enable OpenAI models",
|
||
"Configure a graph store backend for structural code queries",
|
||
"Verify provider credentials via config"
|
||
]
|
||
},
|
||
"timing": {
|
||
"duration_ms": 600
|
||
},
|
||
"messages": [
|
||
{ "level": "warn", "text": "2 warnings require attention" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: diagnostics
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
checks:
|
||
- check: Config file
|
||
status: ok
|
||
details: readable
|
||
- check: Database
|
||
status: ok
|
||
details: writable
|
||
- check: OPENAI_API_KEY
|
||
status: warn
|
||
details: missing
|
||
- check: Anthropic key
|
||
status: ok
|
||
details: configured
|
||
- check: Disk space
|
||
status: ok
|
||
details: 2.1 GB free
|
||
- check: Text index
|
||
status: ok
|
||
details: tantivy 0.22
|
||
- check: Vector index
|
||
status: ok
|
||
details: faiss (CPU)
|
||
- check: Graph store
|
||
status: warn
|
||
details: not configured
|
||
- check: File permissions
|
||
status: ok
|
||
details: data dir r/w
|
||
- check: Git
|
||
status: ok
|
||
details: git 2.43.0
|
||
summary:
|
||
total: 10
|
||
warnings: 2
|
||
errors: 0
|
||
duration_s: 0.6
|
||
recommendations:
|
||
- Set OPENAI_API_KEY to enable OpenAI models
|
||
- Configure a graph store backend for structural code queries
|
||
- Verify provider credentials via config
|
||
timing:
|
||
duration_ms: 600
|
||
messages:
|
||
- level: warn
|
||
text: 2 warnings require attention
|
||
```
|
||
|
||
When critical checks fail, diagnostics reports errors:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> diagnostics
|
||
|
||
╭─ Checks ────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Check</span> <span style="color: cyan; font-weight: 600;">Status</span> <span style="color: cyan; font-weight: 600;">Details</span> │
|
||
│ <span style="opacity: 0.7;">─────────────── ─────── ────────────────────</span> │
|
||
│ Config file <span style="color: #66cc66; font-weight: 600;">OK</span> readable │
|
||
│ Database <span style="color: #ff6666; font-weight: 600;">ERROR</span> locked by another process │
|
||
│ OPENAI_API_KEY <span style="color: #66cc66; font-weight: 600;">OK</span> configured │
|
||
│ Anthropic key <span style="color: #ff6666; font-weight: 600;">ERROR</span> invalid key format │
|
||
│ Disk space <span style="color: yellow; font-weight: 600;">WARN</span> 312 MB free (low) │
|
||
│ Text index <span style="color: #66cc66; font-weight: 600;">OK</span> tantivy 0.22 │
|
||
│ Vector index <span style="color: #ff6666; font-weight: 600;">ERROR</span> FAISS library not found │
|
||
│ Graph store <span style="color: #66cc66; font-weight: 600;">OK</span> neo4j 5.15 │
|
||
│ File permissions <span style="color: #66cc66; font-weight: 600;">OK</span> data dir r/w │
|
||
│ Git <span style="color: #66cc66; font-weight: 600;">OK</span> git 2.43.0 │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ─────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checks:</span> 10 total │
|
||
│ <span style="color: yellow; font-weight: 600;">Warnings:</span> 1 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Errors:</span> 3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 1.2s │
|
||
╰───────────────────╯
|
||
|
||
╭─ Errors (must fix) ─────────────────────────────────────────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">1.</span> Database is locked by PID 12847 — stop the other process or │
|
||
│ delete the lock file at ~/.cleveragents/agents.db-lock │
|
||
│ <span style="color: #ff6666; font-weight: 600;">2.</span> Anthropic key starts with <span style="color: #66cc66;">"pk-"</span> — expected <span style="color: #66cc66;">"sk-ant-"</span> prefix │
|
||
│ Run: agents config set provider.anthropic.api-key <correct-key> │
|
||
│ <span style="color: #ff6666; font-weight: 600;">3.</span> FAISS library not installed — vector search will not work │
|
||
│ Run: pip install faiss-cpu │
|
||
╰─────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> 3 errors must be resolved before CleverAgents can operate
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents diagnostics
|
||
|
||
Checks
|
||
Check Status Details
|
||
--------------- ------- ------------------------
|
||
Config file OK readable
|
||
Database ERROR locked by another process
|
||
OPENAI_API_KEY OK configured
|
||
Anthropic key ERROR invalid key format
|
||
Disk space WARN 312 MB free (low)
|
||
Text index OK tantivy 0.22
|
||
Vector index ERROR FAISS library not found
|
||
Graph store OK neo4j 5.15
|
||
File permissions OK data dir r/w
|
||
Git OK git 2.43.0
|
||
|
||
Summary
|
||
Checks: 10 total
|
||
Warnings: 1
|
||
Errors: 3
|
||
Duration: 1.2s
|
||
|
||
Errors (must fix)
|
||
1. Database is locked by PID 12847 -- stop the other process or
|
||
delete the lock file at ~/.cleveragents/agents.db-lock
|
||
2. Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
|
||
Run: agents config set provider.anthropic.api-key <correct-key>
|
||
3. FAISS library not installed -- vector search will not work
|
||
Run: pip install faiss-cpu
|
||
|
||
[ERROR] 3 errors must be resolved before CleverAgents can operate
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "diagnostics",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"checks": [
|
||
{ "check": "Config file", "status": "ok", "details": "readable" },
|
||
{ "check": "Database", "status": "error", "details": "locked by another process" },
|
||
{ "check": "OPENAI_API_KEY", "status": "ok", "details": "configured" },
|
||
{ "check": "Anthropic key", "status": "error", "details": "invalid key format" },
|
||
{ "check": "Disk space", "status": "warn", "details": "312 MB free (low)" },
|
||
{ "check": "Text index", "status": "ok", "details": "tantivy 0.22" },
|
||
{ "check": "Vector index", "status": "error", "details": "FAISS library not found" },
|
||
{ "check": "Graph store", "status": "ok", "details": "neo4j 5.15" },
|
||
{ "check": "File permissions", "status": "ok", "details": "data dir r/w" },
|
||
{ "check": "Git", "status": "ok", "details": "git 2.43.0" }
|
||
],
|
||
"summary": {
|
||
"total": 10,
|
||
"warnings": 1,
|
||
"errors": 3,
|
||
"duration_s": 1.2
|
||
},
|
||
"errors": [
|
||
{
|
||
"index": 1,
|
||
"message": "Database is locked by PID 12847 -- stop the other process or delete the lock file at ~/.cleveragents/agents.db-lock"
|
||
},
|
||
{
|
||
"index": 2,
|
||
"message": "Anthropic key starts with \"pk-\" -- expected \"sk-ant-\" prefix",
|
||
"fix": "agents config set provider.anthropic.api-key <correct-key>"
|
||
},
|
||
{
|
||
"index": 3,
|
||
"message": "FAISS library not installed -- vector search will not work",
|
||
"fix": "pip install faiss-cpu"
|
||
}
|
||
]
|
||
},
|
||
"timing": {
|
||
"duration_ms": 1200
|
||
},
|
||
"messages": [
|
||
{ "level": "error", "text": "3 errors must be resolved before CleverAgents can operate" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: diagnostics
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
checks:
|
||
- check: Config file
|
||
status: ok
|
||
details: readable
|
||
- check: Database
|
||
status: error
|
||
details: locked by another process
|
||
- check: OPENAI_API_KEY
|
||
status: ok
|
||
details: configured
|
||
- check: Anthropic key
|
||
status: error
|
||
details: invalid key format
|
||
- check: Disk space
|
||
status: warn
|
||
details: 312 MB free (low)
|
||
- check: Text index
|
||
status: ok
|
||
details: tantivy 0.22
|
||
- check: Vector index
|
||
status: error
|
||
details: FAISS library not found
|
||
- check: Graph store
|
||
status: ok
|
||
details: neo4j 5.15
|
||
- check: File permissions
|
||
status: ok
|
||
details: data dir r/w
|
||
- check: Git
|
||
status: ok
|
||
details: git 2.43.0
|
||
summary:
|
||
total: 10
|
||
warnings: 1
|
||
errors: 3
|
||
duration_s: 1.2
|
||
errors:
|
||
- index: 1
|
||
message: >-
|
||
Database is locked by PID 12847 -- stop the other process or
|
||
delete the lock file at ~/.cleveragents/agents.db-lock
|
||
- index: 2
|
||
message: Anthropic key starts with "pk-" -- expected "sk-ant-" prefix
|
||
fix: agents config set provider.anthropic.api-key <correct-key>
|
||
- index: 3
|
||
message: FAISS library not installed -- vector search will not work
|
||
fix: pip install faiss-cpu
|
||
timing:
|
||
duration_ms: 1200
|
||
messages:
|
||
- level: error
|
||
text: 3 errors must be resolved before CleverAgents can operate
|
||
```
|
||
|
||
#### agents init
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> init [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>]</code></pre></div>
|
||
|
||
!!! danger "Destructive Operation"
|
||
|
||
This command ==wipes all existing data== and re-creates the global config and database. A backup is created automatically, but all sessions, plans, and registry entries will be removed.
|
||
|
||
**Purpose**
|
||
Initialize or reset the global CleverAgents environment. This wipes any existing data and re-creates the global config and database.
|
||
|
||
**Arguments**
|
||
|
||
- `--yes`: Skip the confirmation prompt and proceed with the wipe.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> init
|
||
|
||
<span style="color: yellow; font-weight: 600;">Warning</span>: This will remove all data in /home/alex/.cleveragents
|
||
Continue? [y/N]: y
|
||
|
||
╭─ Environment Reset ────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> /home/alex/.cleveragents/cleveragents.db │
|
||
│ <span style="color: yellow; font-weight: 600;">Backup:</span> /home/alex/.cleveragents.backup-2026-02-08 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> ready │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Defaults ──────────────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Automation Profile:</span> supervised │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Built-in Profiles:</span> 8 loaded │
|
||
╰─────────────────────────────────────────────╯
|
||
|
||
╭─ Created ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> config.toml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> cleveragents.db │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> logs/ │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cache:</span> cache/ │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Backups:</span> backups/ │
|
||
╰───────────────────────────╯
|
||
|
||
╭─ Schema ───────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Version:</span> v3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Tables:</span> 12 created │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Migrations:</span> up to date │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Environment initialized
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents init
|
||
|
||
Warning: This will remove all data in /home/alex/.cleveragents
|
||
Continue? [y/N]: y
|
||
|
||
Environment Reset
|
||
Config: /home/alex/.cleveragents/config.toml
|
||
Database: /home/alex/.cleveragents/cleveragents.db
|
||
Backup: /home/alex/.cleveragents.backup-2026-02-08
|
||
Status: ready
|
||
|
||
Defaults
|
||
Automation Profile: supervised
|
||
Built-in Profiles: 8 loaded
|
||
|
||
Created
|
||
Config: config.toml
|
||
Database: cleveragents.db
|
||
Logs: logs/
|
||
Cache: cache/
|
||
Backups: backups/
|
||
|
||
Schema
|
||
Version: v3
|
||
Tables: 12 created
|
||
Migrations: up to date
|
||
|
||
[OK] Environment initialized
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "init",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"environment_reset": {
|
||
"config": "/home/alex/.cleveragents/config.toml",
|
||
"database": "/home/alex/.cleveragents/cleveragents.db",
|
||
"backup": "/home/alex/.cleveragents.backup-2026-02-08",
|
||
"status": "ready"
|
||
},
|
||
"defaults": {
|
||
"automation_profile": "supervised",
|
||
"builtin_profiles": 8
|
||
},
|
||
"created": {
|
||
"config": "config.toml",
|
||
"database": "cleveragents.db",
|
||
"logs": "logs/",
|
||
"cache": "cache/",
|
||
"backups": "backups/"
|
||
},
|
||
"schema": {
|
||
"version": "v3",
|
||
"tables": 12,
|
||
"migrations": "up to date"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 340
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Environment initialized" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: init
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
environment_reset:
|
||
config: /home/alex/.cleveragents/config.toml
|
||
database: /home/alex/.cleveragents/cleveragents.db
|
||
backup: /home/alex/.cleveragents.backup-2026-02-08
|
||
status: ready
|
||
defaults:
|
||
automation_profile: supervised
|
||
builtin_profiles: 8
|
||
created:
|
||
config: config.toml
|
||
database: cleveragents.db
|
||
logs: logs/
|
||
cache: cache/
|
||
backups: backups/
|
||
schema:
|
||
version: v3
|
||
tables: 12
|
||
migrations: up to date
|
||
timing:
|
||
duration_ms: 340
|
||
messages:
|
||
- level: ok
|
||
text: Environment initialized
|
||
```
|
||
|
||
Non-interactive initialization using `--yes` (useful in scripts and CI):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> init <span style="color: cyan;">--yes</span>
|
||
|
||
╭─ Initialized ──────────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Data Dir:</span> /home/alex/.cleveragents (created) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> /home/alex/.cleveragents/config.toml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Database:</span> initialized (schema v3) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Directories:</span> logs, cache, sessions, contexts │
|
||
╰────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Initialized (non-interactive)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents init --yes
|
||
|
||
Initialized
|
||
Data Dir: /home/alex/.cleveragents (created)
|
||
Config: /home/alex/.cleveragents/config.toml
|
||
Database: initialized (schema v3)
|
||
Directories: logs, cache, sessions, contexts
|
||
|
||
[OK] Initialized (non-interactive)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "init --yes",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"initialized": {
|
||
"data_dir": "/home/alex/.cleveragents",
|
||
"config": "/home/alex/.cleveragents/config.toml",
|
||
"database": "initialized (schema v3)",
|
||
"directories": ["logs", "cache", "sessions", "contexts"]
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 280
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Initialized (non-interactive)" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: init --yes
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
initialized:
|
||
data_dir: /home/alex/.cleveragents
|
||
config: /home/alex/.cleveragents/config.toml
|
||
database: initialized (schema v3)
|
||
directories:
|
||
- logs
|
||
- cache
|
||
- sessions
|
||
- contexts
|
||
timing:
|
||
duration_ms: 280
|
||
messages:
|
||
- level: ok
|
||
text: Initialized (non-interactive)
|
||
```
|
||
|
||
#### agents session
|
||
|
||
**Purpose**
|
||
Manage interactive sessions that hold a conversation history and orchestrator state.
|
||
|
||
##### agents session create
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session create [<span style="color: cyan;">--actor</span> <span style="color: #66cc66;"><ACTOR></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Create a new session for interactive work.
|
||
|
||
**Arguments**
|
||
|
||
- `--actor ACTOR`: Orchestrator actor to use for `session tell`.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session create <span style="color: cyan;">--actor</span> local/orchestrator
|
||
|
||
╭─ Session ───────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:44 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Namespace:</span> local │
|
||
╰─────────────────────────────────╯
|
||
|
||
╭─ Settings ─────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Streaming:</span> off │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> default │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Memory:</span> enabled │
|
||
│ <span style="color: yellow; font-weight: 600;">Max History:</span> 50 turns │
|
||
╰────────────────────────╯
|
||
|
||
╭─ Actor Details ───────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> anthropic │
|
||
│ <span style="color: magenta; font-weight: 600;">Model:</span> claude-3.5 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Temperature:</span> 0.7 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context Window:</span> 200K tokens │
|
||
╰───────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session created
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session create --actor local/orchestrator
|
||
|
||
Session
|
||
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Actor: local/orchestrator
|
||
Created: 2026-02-08 12:44
|
||
Namespace: local
|
||
|
||
Settings
|
||
Automation: review
|
||
Streaming: off
|
||
Context: default
|
||
Memory: enabled
|
||
Max History: 50 turns
|
||
|
||
Actor Details
|
||
Provider: anthropic
|
||
Model: claude-3.5
|
||
Temperature: 0.7
|
||
Context Window: 200K tokens
|
||
|
||
[OK] Session created
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session create --actor local/orchestrator",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"session": {
|
||
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"actor": "local/orchestrator",
|
||
"created": "2026-02-08T12:44:00Z",
|
||
"namespace": "local"
|
||
},
|
||
"settings": {
|
||
"automation": "review",
|
||
"streaming": "off",
|
||
"context": "default",
|
||
"memory": "enabled",
|
||
"max_history": 50
|
||
},
|
||
"actor_details": {
|
||
"provider": "anthropic",
|
||
"model": "claude-3.5",
|
||
"temperature": 0.7,
|
||
"context_window": "200K tokens"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 120 },
|
||
"messages": [{ "level": "ok", "text": "Session created" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session create --actor local/orchestrator
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
session:
|
||
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
actor: local/orchestrator
|
||
created: "2026-02-08T12:44:00Z"
|
||
namespace: local
|
||
settings:
|
||
automation: review
|
||
streaming: "off"
|
||
context: default
|
||
memory: enabled
|
||
max_history: 50
|
||
actor_details:
|
||
provider: anthropic
|
||
model: claude-3.5
|
||
temperature: 0.7
|
||
context_window: 200K tokens
|
||
timing:
|
||
duration_ms: 120
|
||
messages:
|
||
- level: ok
|
||
text: Session created
|
||
```
|
||
|
||
##### agents session list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session list</code></pre></div>
|
||
|
||
**Purpose**
|
||
List sessions available on the local machine.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table session list
|
||
|
||
╭─ Sessions ───────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Actor</span> <span style="color: cyan; font-weight: 600;">Messages</span> <span style="color: cyan; font-weight: 600;">Updated</span> │
|
||
│ <span style="opacity: 0.7;">──────── ─────────────── ────────────────── ──────── ────────────────</span> │
|
||
│ 01HXM2A6 weekly-planning local/orchestrator 6 2026-02-08 12:44 │
|
||
│ 01HXM1F2 refactor-sprint local/orchestrator 14 2026-02-07 18:11 │
|
||
╰──────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Most Recent:</span> weekly-planning │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Oldest:</span> refactor-sprint │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Messages:</span> 20 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 42 KB │
|
||
╰──────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 sessions listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents --format table session list
|
||
|
||
Sessions
|
||
ID Name Actor Messages Updated
|
||
-------- --------------- ------------------ -------- ----------------
|
||
01HXM2A6 weekly-planning local/orchestrator 6 2026-02-08 12:44
|
||
01HXM1F2 refactor-sprint local/orchestrator 14 2026-02-07 18:11
|
||
|
||
Summary
|
||
Total: 2
|
||
Most Recent: weekly-planning
|
||
Oldest: refactor-sprint
|
||
Total Messages: 20
|
||
Storage: 42 KB
|
||
|
||
[OK] 2 sessions listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents --format table session list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"sessions": [
|
||
{
|
||
"id": "01HXM2A6",
|
||
"name": "weekly-planning",
|
||
"actor": "local/orchestrator",
|
||
"messages": 6,
|
||
"updated": "2026-02-08T12:44:00Z"
|
||
},
|
||
{
|
||
"id": "01HXM1F2",
|
||
"name": "refactor-sprint",
|
||
"actor": "local/orchestrator",
|
||
"messages": 14,
|
||
"updated": "2026-02-07T18:11:00Z"
|
||
}
|
||
],
|
||
"summary": {
|
||
"total": 2,
|
||
"most_recent": "weekly-planning",
|
||
"oldest": "refactor-sprint",
|
||
"total_messages": 20,
|
||
"storage": "42 KB"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 85 },
|
||
"messages": [{ "level": "ok", "text": "2 sessions listed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents --format table session list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
sessions:
|
||
- id: 01HXM2A6
|
||
name: weekly-planning
|
||
actor: local/orchestrator
|
||
messages: 6
|
||
updated: "2026-02-08T12:44:00Z"
|
||
- id: 01HXM1F2
|
||
name: refactor-sprint
|
||
actor: local/orchestrator
|
||
messages: 14
|
||
updated: "2026-02-07T18:11:00Z"
|
||
summary:
|
||
total: 2
|
||
most_recent: weekly-planning
|
||
oldest: refactor-sprint
|
||
total_messages: 20
|
||
storage: 42 KB
|
||
timing:
|
||
duration_ms: 85
|
||
messages:
|
||
- level: ok
|
||
text: 2 sessions listed
|
||
```
|
||
|
||
##### agents session show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session show <span style="color: #66cc66;"><SESSION_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show details and recent messages for a session.
|
||
|
||
**Arguments**
|
||
|
||
- `<SESSION_ID>`: The session identifier.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
╭─ Session Summary ───────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
|
||
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:30 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 12:44 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> review │
|
||
╰─────────────────────────────────╯
|
||
|
||
╭─ Recent Messages ──────────────────────────────────╮
|
||
│ <span style="opacity: 0.7;">user</span> Create an action to refresh dependency locks │
|
||
│ <span style="opacity: 0.7;">assistant</span> Plan created, running commands... │
|
||
│ <span style="opacity: 0.7;">assistant</span> Completed 2 commands │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Linked Plans ────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> │
|
||
│ <span style="opacity: 0.7;">────────────────────────── ────── ────────</span> │
|
||
│ 01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete │
|
||
╰───────────────────────────────────────────────╯
|
||
|
||
╭─ Token Usage ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 3,420 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 1,185 │
|
||
│ <span style="color: yellow; font-weight: 600;">Estimated Cost:</span> $0.0184 │
|
||
╰────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session details loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
Session Summary
|
||
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Actor: local/orchestrator
|
||
Messages: 6
|
||
Created: 2026-02-08 12:30
|
||
Updated: 2026-02-08 12:44
|
||
Automation: review
|
||
|
||
Recent Messages
|
||
user Create an action to refresh dependency locks
|
||
assistant Plan created, running commands...
|
||
assistant Completed 2 commands
|
||
|
||
Linked Plans
|
||
Plan ID Phase State
|
||
-------------------------- ------- --------
|
||
01HXM8C2ZK4Q7C2B3F2R4VYV6J execute complete
|
||
|
||
Token Usage
|
||
Input Tokens: 3,420
|
||
Output Tokens: 1,185
|
||
Estimated Cost: $0.0184
|
||
|
||
[OK] Session details loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"session_summary": {
|
||
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"actor": "local/orchestrator",
|
||
"messages": 6,
|
||
"created": "2026-02-08T12:30:00Z",
|
||
"updated": "2026-02-08T12:44:00Z",
|
||
"automation": "review"
|
||
},
|
||
"recent_messages": [
|
||
{ "role": "user", "text": "Create an action to refresh dependency locks" },
|
||
{ "role": "assistant", "text": "Plan created, running commands..." },
|
||
{ "role": "assistant", "text": "Completed 2 commands" }
|
||
],
|
||
"linked_plans": [
|
||
{
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"state": "complete"
|
||
}
|
||
],
|
||
"token_usage": {
|
||
"input_tokens": 3420,
|
||
"output_tokens": 1185,
|
||
"estimated_cost": "$0.0184"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 95 },
|
||
"messages": [{ "level": "ok", "text": "Session details loaded" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session show 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
session_summary:
|
||
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
actor: local/orchestrator
|
||
messages: 6
|
||
created: "2026-02-08T12:30:00Z"
|
||
updated: "2026-02-08T12:44:00Z"
|
||
automation: review
|
||
recent_messages:
|
||
- role: user
|
||
text: Create an action to refresh dependency locks
|
||
- role: assistant
|
||
text: Plan created, running commands...
|
||
- role: assistant
|
||
text: Completed 2 commands
|
||
linked_plans:
|
||
- plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
phase: execute
|
||
state: complete
|
||
token_usage:
|
||
input_tokens: 3420
|
||
output_tokens: 1185
|
||
estimated_cost: "$0.0184"
|
||
timing:
|
||
duration_ms: 95
|
||
messages:
|
||
- level: ok
|
||
text: Session details loaded
|
||
```
|
||
|
||
##### agents session delete
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session delete [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><SESSION_ID></span></code></pre></div>
|
||
|
||
!!! danger "Irreversible Deletion"
|
||
This command ==permanently deletes== a session and its stored conversation history. Messages and context cannot be recovered after deletion. Use `--yes` to skip the confirmation prompt.
|
||
|
||
**Arguments**
|
||
|
||
- `<SESSION_ID>`: The session identifier.
|
||
- `--yes, -y`: Skip the confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
|
||
|
||
╭─ Deletion Summary ──────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 removed │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 18 KB freed │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Plans Orphaned:</span> 0 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Cleanup ───────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Backups:</span> none │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Logs:</span> preserved │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> cleared │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> none │
|
||
╰─────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Session deleted
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
Delete session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z? [y/N]: y
|
||
|
||
Deletion Summary
|
||
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Messages: 6 removed
|
||
Storage: 18 KB freed
|
||
Plans Orphaned: 0
|
||
|
||
Cleanup
|
||
Backups: none
|
||
Logs: preserved
|
||
Context: cleared
|
||
Checkpoints: none
|
||
|
||
[OK] Session deleted
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"deletion_summary": {
|
||
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"messages_removed": 6,
|
||
"storage_freed": "18 KB",
|
||
"plans_orphaned": 0
|
||
},
|
||
"cleanup": {
|
||
"backups": "none",
|
||
"logs": "preserved",
|
||
"context": "cleared",
|
||
"checkpoints": "none"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 62 },
|
||
"messages": [{ "level": "ok", "text": "Session deleted" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session delete 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
deletion_summary:
|
||
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
messages_removed: 6
|
||
storage_freed: 18 KB
|
||
plans_orphaned: 0
|
||
cleanup:
|
||
backups: none
|
||
logs: preserved
|
||
context: cleared
|
||
checkpoints: none
|
||
timing:
|
||
duration_ms: 62
|
||
messages:
|
||
- level: ok
|
||
text: Session deleted
|
||
```
|
||
|
||
##### agents session export
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session export [(<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><FILE></span>] <span style="color: #66cc66;"><SESSION_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Export a session as a portable JSON file.
|
||
|
||
**Arguments**
|
||
|
||
- `<SESSION_ID>`: The session identifier.
|
||
- `--output/-o FILE`: Output file path (optional).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session export <span style="color: cyan;">--output</span> /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
╭─ Session Export ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> /tmp/weekly-planning.json │
|
||
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Size:</span> 24 KB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Format:</span> JSON │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Contents ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Messages:</span> 6 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Plan References:</span> 1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Metadata Keys:</span> 2 │
|
||
│ <span style="color: yellow; font-weight: 600;">Actor Config:</span> included │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Schema Version:</span> v3 │
|
||
╰────────────────────────────╯
|
||
|
||
╭─ Integrity ──────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Checksum:</span> sha256:7a9b...42c1 │
|
||
│ <span style="color: yellow; font-weight: 600;">Encrypted:</span> no │
|
||
╰──────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Export completed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
Session Export
|
||
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Output: /tmp/weekly-planning.json
|
||
Messages: 6
|
||
Size: 24 KB
|
||
Format: JSON
|
||
|
||
Contents
|
||
Messages: 6
|
||
Plan References: 1
|
||
Metadata Keys: 2
|
||
Actor Config: included
|
||
Schema Version: v3
|
||
|
||
Integrity
|
||
Checksum: sha256:7a9b...42c1
|
||
Encrypted: no
|
||
|
||
[OK] Export completed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"session_export": {
|
||
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"output": "/tmp/weekly-planning.json",
|
||
"messages": 6,
|
||
"size": "24 KB",
|
||
"format": "JSON"
|
||
},
|
||
"contents": {
|
||
"messages": 6,
|
||
"plan_references": 1,
|
||
"metadata_keys": 2,
|
||
"actor_config": "included",
|
||
"schema_version": "v3"
|
||
},
|
||
"integrity": {
|
||
"checksum": "sha256:7a9b...42c1",
|
||
"encrypted": false
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 140 },
|
||
"messages": [{ "level": "ok", "text": "Export completed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session export --output /tmp/weekly-planning.json 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
session_export:
|
||
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
output: /tmp/weekly-planning.json
|
||
messages: 6
|
||
size: 24 KB
|
||
format: JSON
|
||
contents:
|
||
messages: 6
|
||
plan_references: 1
|
||
metadata_keys: 2
|
||
actor_config: included
|
||
schema_version: v3
|
||
integrity:
|
||
checksum: "sha256:7a9b...42c1"
|
||
encrypted: false
|
||
timing:
|
||
duration_ms: 140
|
||
messages:
|
||
- level: ok
|
||
text: Export completed
|
||
```
|
||
|
||
##### agents session import
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session import (<span style="color: magenta;"><span style="color: cyan;">--input</span>|<span style="color: yellow;">-i</span></span>) <span style="color: #66cc66;"><FILE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Import a session JSON file.
|
||
|
||
**Arguments**
|
||
|
||
- `--input/-i FILE`: Input JSON file.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session import <span style="color: cyan;">--input</span> /tmp/weekly-planning.json
|
||
|
||
╭─ Session Import ────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input:</span> /tmp/weekly-planning.json │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Session ID:</span> 01HXM3D3B2W4CQYQ3P4ZB8A5T1 │
|
||
│ <span style="color: yellow; font-weight: 600;">Messages:</span> 6 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Schema:</span> v3 │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Validation ────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checksum:</span> verified │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Schema:</span> compatible │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Actor Ref:</span> resolved │
|
||
╰─────────────────────────╯
|
||
|
||
╭─ Merge ──────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Existing:</span> none │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> create new │
|
||
╰──────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Import completed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session import --input /tmp/weekly-planning.json
|
||
|
||
Session Import
|
||
Input: /tmp/weekly-planning.json
|
||
Session ID: 01HXM3D3B2W4CQYQ3P4ZB8A5T1
|
||
Messages: 6
|
||
Schema: v3
|
||
|
||
Validation
|
||
Checksum: verified
|
||
Schema: compatible
|
||
Actor Ref: resolved
|
||
|
||
Merge
|
||
Existing: none
|
||
Strategy: create new
|
||
|
||
[OK] Import completed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session import --input /tmp/weekly-planning.json",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"session_import": {
|
||
"input": "/tmp/weekly-planning.json",
|
||
"session_id": "01HXM3D3B2W4CQYQ3P4ZB8A5T1",
|
||
"messages": 6,
|
||
"schema": "v3"
|
||
},
|
||
"validation": {
|
||
"checksum": "verified",
|
||
"schema": "compatible",
|
||
"actor_ref": "resolved"
|
||
},
|
||
"merge": {
|
||
"existing": "none",
|
||
"strategy": "create new"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 210 },
|
||
"messages": [{ "level": "ok", "text": "Import completed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session import --input /tmp/weekly-planning.json
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
session_import:
|
||
input: /tmp/weekly-planning.json
|
||
session_id: 01HXM3D3B2W4CQYQ3P4ZB8A5T1
|
||
messages: 6
|
||
schema: v3
|
||
validation:
|
||
checksum: verified
|
||
schema: compatible
|
||
actor_ref: resolved
|
||
merge:
|
||
existing: none
|
||
strategy: create new
|
||
timing:
|
||
duration_ms: 210
|
||
messages:
|
||
- level: ok
|
||
text: Import completed
|
||
```
|
||
|
||
##### agents session tell
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: cyan;">--session</span> <span style="color: #66cc66;"><SESSION_ID></span> [<span style="color: cyan;">--actor</span> <span style="color: #66cc66;"><ACTOR></span>] [<span style="color: cyan;">--stream</span>] <span style="color: #66cc66;"><PROMPT></span></code></pre></div>
|
||
|
||
!!! tip "Primary User Interface"
|
||
|
||
This is the main natural-language interface for interacting with CleverAgents. The orchestrator interprets your request and issues the necessary CleverAgents commands under the hood — creating actions, plans, or project changes as needed. Use `--stream` to see responses in real time.
|
||
|
||
**Purpose**
|
||
Send a natural-language request to the orchestrator. The orchestrator can create actions, plans, or project changes by issuing the necessary CleverAgents commands under the hood.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROMPT>`: Instruction text (positional argument).
|
||
- `--session SESSION_ID`: Session to use (required).
|
||
- `--actor ACTOR`: Override the session actor for this request.
|
||
- `--stream`: Stream progress as the orchestrator works.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: #66cc66;">"Create an action to refresh dependency locks and add it to the platform project"</span> \
|
||
<span style="color: cyan;">--session</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
╭─ Plan Request ──────────────────────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Actor:</span> local/orchestrator │
|
||
│ <span style="color: cyan; font-weight: 600;">Session:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> review │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Prompt:</span> Create an action to refresh dependency locks... │
|
||
╰─────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Commands Executed ─────────────────────────────────────────────────────────────────────────────────────────╮
|
||
│ - agents action create <span style="color: cyan;">--config</span> ./actions/refresh-locks.yaml │
|
||
│ - agents resource add git-checkout local/platform-repo <span style="color: cyan;">--path</span> /repos/platform │
|
||
│ - agents project link-resource local/platform local/platform-repo │
|
||
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Result ──────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Action:</span> local/refresh-locks │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/platform │
|
||
│ <span style="color: magenta; font-weight: 600;">Resource:</span> local/platform-repo │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Usage ─────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 1,842 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 624 │
|
||
│ <span style="color: yellow; font-weight: 600;">Cost:</span> $0.0094 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 3.2s │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 3 │
|
||
╰─────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Orchestrator completed 3 commands
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session tell "Create an action to refresh dependency locks and add it to the platform project" \
|
||
--session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
|
||
Plan Request
|
||
Actor: local/orchestrator
|
||
Session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Automation: review
|
||
Prompt: Create an action to refresh dependency locks...
|
||
|
||
Commands Executed
|
||
- agents action create --config ./actions/refresh-locks.yaml
|
||
- agents resource add git-checkout local/platform-repo --path /repos/platform
|
||
- agents project link-resource local/platform local/platform-repo
|
||
|
||
Result
|
||
Action: local/refresh-locks
|
||
Project: local/platform
|
||
Resource: local/platform-repo
|
||
|
||
Usage
|
||
Input Tokens: 1,842
|
||
Output Tokens: 624
|
||
Cost: $0.0094
|
||
Duration: 3.2s
|
||
Tool Calls: 3
|
||
|
||
[OK] Orchestrator completed 3 commands
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session tell \"Create an action to refresh dependency locks and add it to the platform project\" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_request": {
|
||
"actor": "local/orchestrator",
|
||
"session": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"automation": "review",
|
||
"prompt": "Create an action to refresh dependency locks..."
|
||
},
|
||
"commands_executed": [
|
||
"agents action create --config ./actions/refresh-locks.yaml",
|
||
"agents resource add git-checkout local/platform-repo --path /repos/platform",
|
||
"agents project link-resource local/platform local/platform-repo"
|
||
],
|
||
"result": {
|
||
"action": "local/refresh-locks",
|
||
"project": "local/platform",
|
||
"resource": "local/platform-repo"
|
||
},
|
||
"usage": {
|
||
"input_tokens": 1842,
|
||
"output_tokens": 624,
|
||
"cost": "$0.0094",
|
||
"duration_s": 3.2,
|
||
"tool_calls": 3
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 3200 },
|
||
"messages": [{ "level": "ok", "text": "Orchestrator completed 3 commands" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session tell "Create an action to refresh dependency locks and add it to the platform project" --session 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_request:
|
||
actor: local/orchestrator
|
||
session: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
automation: review
|
||
prompt: Create an action to refresh dependency locks...
|
||
commands_executed:
|
||
- agents action create --config ./actions/refresh-locks.yaml
|
||
- agents resource add git-checkout local/platform-repo --path /repos/platform
|
||
- agents project link-resource local/platform local/platform-repo
|
||
result:
|
||
action: local/refresh-locks
|
||
project: local/platform
|
||
resource: local/platform-repo
|
||
usage:
|
||
input_tokens: 1842
|
||
output_tokens: 624
|
||
cost: "$0.0094"
|
||
duration_s: 3.2
|
||
tool_calls: 3
|
||
timing:
|
||
duration_ms: 3200
|
||
messages:
|
||
- level: ok
|
||
text: Orchestrator completed 3 commands
|
||
```
|
||
|
||
Using `--stream` to see the response as it is generated (token by token):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> session tell <span style="color: cyan;">--session</span> 01HXM2A6K1 <span style="color: cyan;">--stream</span> <span style="color: #66cc66;">"What files were changed in the last plan?"</span>
|
||
|
||
╭─ Session ──────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM2A6K1P2E9Q9D4GQ7J4S7Z │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actor:</span> local/orchestrator │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> streaming │
|
||
╰────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66;">▍</span> The last plan (01HXM8C2ZK) modified 6 files in the auth module:
|
||
|
||
1. `src/auth/session.py` — refactored session validation
|
||
2. `src/auth/tokens.py` — updated token expiry to 7200s
|
||
3. `src/auth/__init__.py` — updated exports
|
||
4. `tests/test_auth.py` — added 12 new test cases
|
||
5. `tests/test_session.py` — updated session fixtures
|
||
6. `docs/auth.md` — updated API documentation
|
||
|
||
All changes passed validation (24/24 tests, lint clean).
|
||
|
||
╭─ Usage ──────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 1,240 (stream) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 3.1s │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 2 │
|
||
╰──────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Stream complete
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
|
||
|
||
Session
|
||
ID: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
Actor: local/orchestrator
|
||
Mode: streaming
|
||
|
||
The last plan (01HXM8C2ZK) modified 6 files in the auth module:
|
||
|
||
1. src/auth/session.py -- refactored session validation
|
||
2. src/auth/tokens.py -- updated token expiry to 7200s
|
||
3. src/auth/__init__.py -- updated exports
|
||
4. tests/test_auth.py -- added 12 new test cases
|
||
5. tests/test_session.py -- updated session fixtures
|
||
6. docs/auth.md -- updated API documentation
|
||
|
||
All changes passed validation (24/24 tests, lint clean).
|
||
|
||
Usage
|
||
Tokens: 1,240 (stream)
|
||
Duration: 3.1s
|
||
Tool Calls: 2
|
||
|
||
[OK] Stream complete
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents session tell --session 01HXM2A6K1 --stream \"What files were changed in the last plan?\"",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"session": {
|
||
"id": "01HXM2A6K1P2E9Q9D4GQ7J4S7Z",
|
||
"actor": "local/orchestrator",
|
||
"mode": "streaming"
|
||
},
|
||
"response": "The last plan (01HXM8C2ZK) modified 6 files in the auth module:\n\n1. src/auth/session.py \u2014 refactored session validation\n2. src/auth/tokens.py \u2014 updated token expiry to 7200s\n3. src/auth/__init__.py \u2014 updated exports\n4. tests/test_auth.py \u2014 added 12 new test cases\n5. tests/test_session.py \u2014 updated session fixtures\n6. docs/auth.md \u2014 updated API documentation\n\nAll changes passed validation (24/24 tests, lint clean).",
|
||
"files_changed": [
|
||
"src/auth/session.py",
|
||
"src/auth/tokens.py",
|
||
"src/auth/__init__.py",
|
||
"tests/test_auth.py",
|
||
"tests/test_session.py",
|
||
"docs/auth.md"
|
||
],
|
||
"usage": {
|
||
"tokens": 1240,
|
||
"duration_s": 3.1,
|
||
"tool_calls": 2
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 3100 },
|
||
"messages": [{ "level": "ok", "text": "Stream complete" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents session tell --session 01HXM2A6K1 --stream "What files were changed in the last plan?"
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
session:
|
||
id: 01HXM2A6K1P2E9Q9D4GQ7J4S7Z
|
||
actor: local/orchestrator
|
||
mode: streaming
|
||
response: >
|
||
The last plan (01HXM8C2ZK) modified 6 files in the auth module:
|
||
1. src/auth/session.py -- refactored session validation
|
||
2. src/auth/tokens.py -- updated token expiry to 7200s
|
||
3. src/auth/__init__.py -- updated exports
|
||
4. tests/test_auth.py -- added 12 new test cases
|
||
5. tests/test_session.py -- updated session fixtures
|
||
6. docs/auth.md -- updated API documentation
|
||
All changes passed validation (24/24 tests, lint clean).
|
||
files_changed:
|
||
- src/auth/session.py
|
||
- src/auth/tokens.py
|
||
- src/auth/__init__.py
|
||
- tests/test_auth.py
|
||
- tests/test_session.py
|
||
- docs/auth.md
|
||
usage:
|
||
tokens: 1240
|
||
duration_s: 3.1
|
||
tool_calls: 2
|
||
timing:
|
||
duration_ms: 3100
|
||
messages:
|
||
- level: ok
|
||
text: Stream complete
|
||
```
|
||
|
||
#### agents project
|
||
|
||
**Purpose**
|
||
Manage projects and their resources.
|
||
|
||
##### agents project create
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project create [(<span style="color: magenta;"><span style="color: cyan;">--description</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><DESC></span>] [<span style="color: cyan;">--resource</span> <span style="color: #66cc66;"><RESOURCE></span>]...
|
||
[<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;"><INVARIANT></span>]... [<span style="color: cyan;">--invariant-actor</span> <span style="color: #66cc66;"><ACTOR></span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Create a new project record.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Namespaced project name (positional argument).
|
||
- `--description/-d TEXT`: Optional description.
|
||
- `--resource RESOURCE`: Resource name or ULID to link to the project at creation time (repeatable).
|
||
- `--invariant TEXT`: Invariant to attach to this project (repeatable). These invariants apply to all plans targeting this project.
|
||
- `--invariant-actor ACTOR`: Invariant Reconciliation Actor for this project. Used to reconcile project-level invariants against global invariants for all plans targeting this project (unless the plan overrides it).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create <span style="color: cyan;">--description</span> <span style="color: #66cc66;">"Backend API"</span> local/api-service
|
||
|
||
╭─ Project ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Backend API │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> local │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:46 │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Paths ────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Root:</span> /repos/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /repos/api-service/.cleveragents │
|
||
╰────────────────────────────────────────────╯
|
||
|
||
╭─ Defaults ──────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> git_worktree │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Validations:</span> 0 │
|
||
│ <span style="color: yellow; font-weight: 600;">Context Filters:</span> none │
|
||
│ <span style="color: magenta; font-weight: 600;">Automation Profile:</span> (inherits global) │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Resources ──────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Indexed:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandboxable:</span> 0 │
|
||
╰──────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project create --description "Backend API" local/api-service
|
||
|
||
Project
|
||
Name: local/api-service
|
||
Description: Backend API
|
||
Type: local
|
||
Created: 2026-02-08 12:46
|
||
|
||
Paths
|
||
Root: /repos/api-service
|
||
Data Dir: /repos/api-service/.cleveragents
|
||
|
||
Defaults
|
||
Sandbox: git_worktree
|
||
Validations: 0
|
||
Context Filters: none
|
||
Automation Profile: (inherits global)
|
||
|
||
Resources
|
||
Total: 0
|
||
Indexed: 0
|
||
Sandboxable: 0
|
||
|
||
[OK] Project created
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project create --description \"Backend API\" local/api-service",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"project": {
|
||
"name": "local/api-service",
|
||
"description": "Backend API",
|
||
"type": "local",
|
||
"created": "2026-02-08T12:46:00Z"
|
||
},
|
||
"paths": {
|
||
"root": "/repos/api-service",
|
||
"data_dir": "/repos/api-service/.cleveragents"
|
||
},
|
||
"defaults": {
|
||
"sandbox": "git_worktree",
|
||
"validations": 0,
|
||
"context_filters": null,
|
||
"automation_profile": null
|
||
},
|
||
"resources": {
|
||
"total": 0,
|
||
"indexed": 0,
|
||
"sandboxable": 0
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 85 },
|
||
"messages": [{ "level": "ok", "text": "Project created" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project create --description "Backend API" local/api-service
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
project:
|
||
name: local/api-service
|
||
description: Backend API
|
||
type: local
|
||
created: "2026-02-08T12:46:00Z"
|
||
paths:
|
||
root: /repos/api-service
|
||
data_dir: /repos/api-service/.cleveragents
|
||
defaults:
|
||
sandbox: git_worktree
|
||
validations: 0
|
||
context_filters: null
|
||
automation_profile: null
|
||
resources:
|
||
total: 0
|
||
indexed: 0
|
||
sandboxable: 0
|
||
timing:
|
||
duration_ms: 85
|
||
messages:
|
||
- level: ok
|
||
text: Project created
|
||
```
|
||
|
||
Creating a project with resources and invariants in one command:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project create <span style="color: cyan;">-d</span> <span style="color: #66cc66;">"Frontend web application"</span> \
|
||
<span style="color: cyan;">--resource</span> local/web-repo <span style="color: cyan;">--resource</span> local/web-db \
|
||
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"All components must have unit tests"</span> \
|
||
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"CSS must pass stylelint checks"</span> \
|
||
<span style="color: cyan;">--invariant-actor</span> local/invariant-resolver \
|
||
local/web-app
|
||
|
||
╭─ Project Created ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/web-app │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Frontend web app │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Remote:</span> no │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Linked Resources ───────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> │
|
||
│ <span style="opacity: 0.7;">───────────────── ────────────── ─────────</span> │
|
||
│ local/web-repo git-checkout no │
|
||
│ local/web-db local/database no │
|
||
╰──────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Invariants ────────────────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">1.</span> All components must have unit tests │
|
||
│ <span style="color: magenta; font-weight: 600;">2.</span> CSS must pass stylelint checks │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Reconciliation Actor:</span> local/invariant-resolver │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project created
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project create -d "Frontend web application" \
|
||
--resource local/web-repo --resource local/web-db \
|
||
--invariant "All components must have unit tests" \
|
||
--invariant "CSS must pass stylelint checks" \
|
||
--invariant-actor local/invariant-resolver \
|
||
local/web-app
|
||
|
||
Project Created
|
||
Name: local/web-app
|
||
Description: Frontend web app
|
||
Remote: no
|
||
|
||
Linked Resources
|
||
Name Type Read-Only
|
||
----------------- -------------- ---------
|
||
local/web-repo git-checkout no
|
||
local/web-db local/database no
|
||
|
||
Invariants
|
||
1. All components must have unit tests
|
||
2. CSS must pass stylelint checks
|
||
Reconciliation Actor: local/invariant-resolver
|
||
|
||
[OK] Project created
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project create -d \"Frontend web application\" --resource local/web-repo --resource local/web-db --invariant \"All components must have unit tests\" --invariant \"CSS must pass stylelint checks\" --invariant-actor local/invariant-resolver local/web-app",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"project": {
|
||
"name": "local/web-app",
|
||
"description": "Frontend web app",
|
||
"remote": false
|
||
},
|
||
"linked_resources": [
|
||
{ "name": "local/web-repo", "type": "git-checkout", "read_only": false },
|
||
{ "name": "local/web-db", "type": "local/database", "read_only": false }
|
||
],
|
||
"invariants": {
|
||
"items": [
|
||
"All components must have unit tests",
|
||
"CSS must pass stylelint checks"
|
||
],
|
||
"reconciliation_actor": "local/invariant-resolver"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 120 },
|
||
"messages": [{ "level": "ok", "text": "Project created" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project create -d "Frontend web application" --resource local/web-repo --resource local/web-db --invariant "All components must have unit tests" --invariant "CSS must pass stylelint checks" --invariant-actor local/invariant-resolver local/web-app
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
project:
|
||
name: local/web-app
|
||
description: Frontend web app
|
||
remote: false
|
||
linked_resources:
|
||
- name: local/web-repo
|
||
type: git-checkout
|
||
read_only: false
|
||
- name: local/web-db
|
||
type: local/database
|
||
read_only: false
|
||
invariants:
|
||
items:
|
||
- All components must have unit tests
|
||
- CSS must pass stylelint checks
|
||
reconciliation_actor: local/invariant-resolver
|
||
timing:
|
||
duration_ms: 120
|
||
messages:
|
||
- level: ok
|
||
text: Project created
|
||
```
|
||
|
||
##### agents project link-resource
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project link-resource [<span style="color: cyan;">--read-only</span>] <span style="color: #66cc66;"><PROJECT></span> <span style="color: #66cc66;"><RESOURCE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Link a registered resource to a project. The resource must already be registered via `agents resource add`. A resource can be linked to multiple projects. Optionally, the resource can be marked as read-only within this project context, and given an alias for convenience.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument).
|
||
- `<RESOURCE>`: Resource name or ULID (positional argument).
|
||
- `--read-only`: Mark the resource as read-only within this project (even if the resource itself is writable).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/api-repo <span style="color: cyan;">--path</span> /repos/api <span style="color: cyan;">--branch</span> main
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project link-resource local/api-service local/api-repo
|
||
|
||
╭─ Resource Linked ───────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> no │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Access ─────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Read:</span> allowed │
|
||
│ <span style="color: yellow; font-weight: 600;">Write:</span> allowed │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Apply:</span> requires approval │
|
||
╰──────────────────────────╯
|
||
|
||
╭─ Indexing ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Status:</span> indexing... │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Files Found:</span> 347 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Language:</span> Python (primary) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimated Time:</span> ~20 seconds │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource linked to project
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource add git-checkout local/api-repo --path /repos/api --branch main
|
||
$ agents project link-resource local/api-service local/api-repo
|
||
|
||
Resource Linked
|
||
Project: local/api-service
|
||
Resource: local/api-repo
|
||
Type: git-checkout
|
||
Read-Only: no
|
||
|
||
Access
|
||
Read: allowed
|
||
Write: allowed
|
||
Apply: requires approval
|
||
|
||
Indexing
|
||
Status: indexing...
|
||
Files Found: 347
|
||
Language: Python (primary)
|
||
Estimated Time: ~20 seconds
|
||
|
||
[OK] Resource linked to project
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project link-resource local/api-service local/api-repo",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource_linked": {
|
||
"project": "local/api-service",
|
||
"resource": "local/api-repo",
|
||
"type": "git-checkout",
|
||
"read_only": false
|
||
},
|
||
"access": {
|
||
"read": "allowed",
|
||
"write": "allowed",
|
||
"apply": "requires approval"
|
||
},
|
||
"indexing": {
|
||
"status": "indexing",
|
||
"files_found": 347,
|
||
"language": "Python (primary)",
|
||
"estimated_time_seconds": 20
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 92 },
|
||
"messages": [{ "level": "ok", "text": "Resource linked to project" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project link-resource local/api-service local/api-repo
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource_linked:
|
||
project: local/api-service
|
||
resource: local/api-repo
|
||
type: git-checkout
|
||
read_only: false
|
||
access:
|
||
read: allowed
|
||
write: allowed
|
||
apply: requires approval
|
||
indexing:
|
||
status: indexing
|
||
files_found: 347
|
||
language: Python (primary)
|
||
estimated_time_seconds: 20
|
||
timing:
|
||
duration_ms: 92
|
||
messages:
|
||
- level: ok
|
||
text: Resource linked to project
|
||
```
|
||
|
||
##### agents project unlink-resource
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project unlink-resource [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PROJECT></span> <span style="color: #66cc66;"><RESOURCE_NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Unlink a resource from a project. The resource itself remains registered in the Resource Registry and can still be linked to other projects. Active plans using this resource in this project context will be warned.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument).
|
||
- `<RESOURCE_NAME>`: Resource name (positional argument). Only user-added (named) resources can be unlinked.
|
||
- `--yes, -y`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project unlink-resource local/api-service local/api-repo
|
||
|
||
Unlink local/api-repo from local/api-service? [y/N]: y
|
||
|
||
╭─ Resource Unlinked ─────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Index Cleanup ──────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Text Index:</span> 347 removed │
|
||
│ <span style="color: yellow; font-weight: 600;">Vectors:</span> 892 removed │
|
||
│ <span style="color: yellow; font-weight: 600;">Graph Triples:</span> cleared │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 0.3s │
|
||
╰──────────────────────────╯
|
||
|
||
╭─ Project Summary ──────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Linked Resources:</span> 1 remaining │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Last Updated:</span> 2026-02-09 10:30 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource unlinked from project
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project unlink-resource local/api-service local/api-repo
|
||
|
||
Unlink local/api-repo from local/api-service? [y/N]: y
|
||
|
||
Resource Unlinked
|
||
Project: local/api-service
|
||
Resource: local/api-repo
|
||
Type: git-checkout
|
||
|
||
Index Cleanup
|
||
Text Index: 347 removed
|
||
Vectors: 892 removed
|
||
Graph Triples: cleared
|
||
Duration: 0.3s
|
||
|
||
Project Summary
|
||
Linked Resources: 1 remaining
|
||
Last Updated: 2026-02-09 10:30
|
||
Active Plans: 0
|
||
|
||
[OK] Resource unlinked from project
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project unlink-resource local/api-service local/api-repo",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource_unlinked": {
|
||
"project": "local/api-service",
|
||
"resource": "local/api-repo",
|
||
"type": "git-checkout"
|
||
},
|
||
"index_cleanup": {
|
||
"text_index": "347 removed",
|
||
"vectors": "892 removed",
|
||
"graph_triples": "cleared",
|
||
"duration_seconds": 0.3
|
||
},
|
||
"project_summary": {
|
||
"linked_resources": 1,
|
||
"last_updated": "2026-02-09T10:30:00Z",
|
||
"active_plans": 0
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 340 },
|
||
"messages": [{ "level": "ok", "text": "Resource unlinked from project" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project unlink-resource local/api-service local/api-repo
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource_unlinked:
|
||
project: local/api-service
|
||
resource: local/api-repo
|
||
type: git-checkout
|
||
index_cleanup:
|
||
text_index: 347 removed
|
||
vectors: 892 removed
|
||
graph_triples: cleared
|
||
duration_seconds: 0.3
|
||
project_summary:
|
||
linked_resources: 1
|
||
last_updated: "2026-02-09T10:30:00Z"
|
||
active_plans: 0
|
||
timing:
|
||
duration_ms: 340
|
||
messages:
|
||
- level: ok
|
||
text: Resource unlinked from project
|
||
```
|
||
|
||
##### agents project list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) NS] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List projects with optional filters.
|
||
|
||
**Arguments**
|
||
|
||
- `--namespace/-n NS`: Filter by namespace.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table project list
|
||
|
||
╭─ Projects ────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Resources</span> <span style="color: cyan; font-weight: 600;">Remote</span> <span style="color: cyan; font-weight: 600;">Active Plans</span> │
|
||
│ <span style="opacity: 0.7;">───────────────── ───────── ────── ────────────</span> │
|
||
│ local/api-service 2 No 1 │
|
||
│ local/docs 1 No 0 │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">With Resources:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Remote:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Resources:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 1,247 │
|
||
│ <span style="color: yellow; font-weight: 600;">Active Plans:</span> 1 │
|
||
╰────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 projects listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents --format table project list
|
||
|
||
Projects
|
||
Name Resources Remote Active Plans
|
||
----------------- --------- ------ ------------
|
||
local/api-service 2 No 1
|
||
local/docs 1 No 0
|
||
|
||
Summary
|
||
Total: 2
|
||
With Resources: 2
|
||
Remote: 0
|
||
Total Resources: 3
|
||
Indexed Files: 1,247
|
||
Active Plans: 1
|
||
|
||
[OK] 2 projects listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents --format table project list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"projects": [
|
||
{ "name": "local/api-service", "resources": 2, "remote": false, "active_plans": 1 },
|
||
{ "name": "local/docs", "resources": 1, "remote": false, "active_plans": 0 }
|
||
],
|
||
"summary": {
|
||
"total": 2,
|
||
"with_resources": 2,
|
||
"remote": 0,
|
||
"total_resources": 3,
|
||
"indexed_files": 1247,
|
||
"active_plans": 1
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 45 },
|
||
"messages": [{ "level": "ok", "text": "2 projects listed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents --format table project list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
projects:
|
||
- name: local/api-service
|
||
resources: 2
|
||
remote: false
|
||
active_plans: 1
|
||
- name: local/docs
|
||
resources: 1
|
||
remote: false
|
||
active_plans: 0
|
||
summary:
|
||
total: 2
|
||
with_resources: 2
|
||
remote: 0
|
||
total_resources: 3
|
||
indexed_files: 1247
|
||
active_plans: 1
|
||
timing:
|
||
duration_ms: 45
|
||
messages:
|
||
- level: ok
|
||
text: 2 projects listed
|
||
```
|
||
|
||
##### agents project show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project show <span style="color: #66cc66;"><PROJECT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show full project details.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Project name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project show local/api-service
|
||
|
||
╭─ Project Details ──────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Backend API │
|
||
│ <span style="color: yellow; font-weight: 600;">Resources:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Remote:</span> no │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:46 │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Linked Resources ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Resource</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Sandbox</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> │
|
||
│ <span style="opacity: 0.7;">──────────────── ────────────── ──────────────────── ─────────</span> │
|
||
│ local/api-repo git-checkout git_worktree no │
|
||
│ local/staging-db local/database transaction_rollback yes │
|
||
╰─────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Validations (3) ──────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">local/run-tests</span> Run unit tests with coverage <span style="color: #66cc66; font-weight: 600;">required</span> │
|
||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7…)</span> │
|
||
│ <span style="color: cyan; font-weight: 600;">local/lint-check</span> Lint check <span style="color: #66cc66; font-weight: 600;">required</span> │
|
||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: direct (always active) (attachment: 01HXM5…)</span> │
|
||
│ <span style="color: cyan; font-weight: 600;">local/check-bundle-size</span> Check bundle size (advisory) <span style="color: yellow; font-weight: 600;">informational</span> │
|
||
│ <span style="opacity: 0.7;">resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9…)</span> │
|
||
╰────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Context ───────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
|
||
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Indexing Status ──────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Text Index:</span> ready │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Vector Index:</span> ready │
|
||
│ <span style="color: yellow; font-weight: 600;">Graph Store:</span> disabled │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 347 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Last Indexed:</span> 12:48 │
|
||
╰────────────────────────────╯
|
||
|
||
╭─ Active Plans ──────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan ID</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Phase</span> │
|
||
│ <span style="opacity: 0.7;">──────── ─────────────────── ───────</span> │
|
||
│ 01HXM7A9 local/code-coverage execute │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project show local/api-service
|
||
|
||
Project Details
|
||
Name: local/api-service
|
||
Description: Backend API
|
||
Resources: 2
|
||
Remote: no
|
||
Created: 2026-02-08 12:46
|
||
|
||
Linked Resources
|
||
Resource Type Sandbox Read-Only
|
||
---------------- -------------- -------------------- ---------
|
||
local/api-repo git-checkout git_worktree no
|
||
local/staging-db local/database transaction_rollback yes
|
||
|
||
Validations (3)
|
||
local/run-tests Run unit tests with coverage required
|
||
resource: local/api-repo scope: project (attachment: 01HXM5A1B2C3D4E5F6G7...)
|
||
local/lint-check Lint check required
|
||
resource: local/api-repo scope: direct (always active) (attachment: 01HXM5...)
|
||
local/check-bundle-size Check bundle size (advisory) informational
|
||
resource: local/api-repo scope: project (attachment: 01HXM5D4E5F6G7H8J9...)
|
||
|
||
Context
|
||
Include: repo
|
||
Exclude: **/node_modules/**
|
||
Max File Size: 1 MB
|
||
|
||
Indexing Status
|
||
Text Index: ready
|
||
Vector Index: ready
|
||
Graph Store: disabled
|
||
Indexed Files: 347
|
||
Last Indexed: 12:48
|
||
|
||
Active Plans
|
||
Plan ID Action Phase
|
||
-------- ------------------- -------
|
||
01HXM7A9 local/code-coverage execute
|
||
|
||
[OK] Project loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project show local/api-service",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"project": {
|
||
"name": "local/api-service",
|
||
"description": "Backend API",
|
||
"resources": 2,
|
||
"remote": false,
|
||
"created": "2026-02-08T12:46:00Z"
|
||
},
|
||
"linked_resources": [
|
||
{ "name": "local/api-repo", "type": "git-checkout", "sandbox": "git_worktree", "read_only": false },
|
||
{ "name": "local/staging-db", "type": "local/database", "sandbox": "transaction_rollback", "read_only": true }
|
||
],
|
||
"validations": [
|
||
{
|
||
"name": "local/run-tests",
|
||
"description": "Run unit tests with coverage",
|
||
"mode": "required",
|
||
"resource": "local/api-repo",
|
||
"scope": "project",
|
||
"attachment_id": "01HXM5A1B2C3D4E5F6G7"
|
||
},
|
||
{
|
||
"name": "local/lint-check",
|
||
"description": "Lint check",
|
||
"mode": "required",
|
||
"resource": "local/api-repo",
|
||
"scope": "direct",
|
||
"attachment_id": "01HXM5"
|
||
},
|
||
{
|
||
"name": "local/check-bundle-size",
|
||
"description": "Check bundle size (advisory)",
|
||
"mode": "informational",
|
||
"resource": "local/api-repo",
|
||
"scope": "project",
|
||
"attachment_id": "01HXM5D4E5F6G7H8J9"
|
||
}
|
||
],
|
||
"context": {
|
||
"include": ["repo"],
|
||
"exclude": ["**/node_modules/**"],
|
||
"max_file_size_bytes": 1048576
|
||
},
|
||
"indexing_status": {
|
||
"text_index": "ready",
|
||
"vector_index": "ready",
|
||
"graph_store": "disabled",
|
||
"indexed_files": 347,
|
||
"last_indexed": "12:48"
|
||
},
|
||
"active_plans": [
|
||
{ "plan_id": "01HXM7A9", "action": "local/code-coverage", "phase": "execute" }
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 62 },
|
||
"messages": [{ "level": "ok", "text": "Project loaded" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project show local/api-service
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
project:
|
||
name: local/api-service
|
||
description: Backend API
|
||
resources: 2
|
||
remote: false
|
||
created: "2026-02-08T12:46:00Z"
|
||
linked_resources:
|
||
- name: local/api-repo
|
||
type: git-checkout
|
||
sandbox: git_worktree
|
||
read_only: false
|
||
- name: local/staging-db
|
||
type: local/database
|
||
sandbox: transaction_rollback
|
||
read_only: true
|
||
validations:
|
||
- name: local/run-tests
|
||
description: Run unit tests with coverage
|
||
mode: required
|
||
resource: local/api-repo
|
||
scope: project
|
||
attachment_id: 01HXM5A1B2C3D4E5F6G7
|
||
- name: local/lint-check
|
||
description: Lint check
|
||
mode: required
|
||
resource: local/api-repo
|
||
scope: direct
|
||
attachment_id: 01HXM5
|
||
- name: local/check-bundle-size
|
||
description: Check bundle size (advisory)
|
||
mode: informational
|
||
resource: local/api-repo
|
||
scope: project
|
||
attachment_id: 01HXM5D4E5F6G7H8J9
|
||
context:
|
||
include:
|
||
- repo
|
||
exclude:
|
||
- "**/node_modules/**"
|
||
max_file_size_bytes: 1048576
|
||
indexing_status:
|
||
text_index: ready
|
||
vector_index: ready
|
||
graph_store: disabled
|
||
indexed_files: 347
|
||
last_indexed: "12:48"
|
||
active_plans:
|
||
- plan_id: 01HXM7A9
|
||
action: local/code-coverage
|
||
phase: execute
|
||
timing:
|
||
duration_ms: 62
|
||
messages:
|
||
- level: ok
|
||
text: Project loaded
|
||
```
|
||
|
||
##### agents project validations
|
||
|
||
Note: Validations are managed as a top-level entity via `agents validation` commands (see the **agents validation** section below). A validation is always attached to a resource, but can optionally be scoped to a project via `agents validation attach --project <PROJECT> <RESOURCE> <VALIDATION>`. When scoped to a project, the validation only runs when that resource is accessed through the specified project. The `agents project show` command displays all validations relevant to the project — both directly-attached validations on linked resources and project-scoped validations.
|
||
|
||
See: [agents validation](#agents-validation) for full details on creating, managing, and attaching validations.
|
||
|
||
##### agents project delete
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project delete [<span style="color: cyan;">--force</span>|<span style="color: yellow;">-f</span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! warning "Irreversible Action"
|
||
|
||
Deleting a project ==cannot be undone==. All resource links, validation attachments, and context policies will be removed. The resources themselves remain in the Resource Registry. Use `--force` to also cancel active plans targeting this project.
|
||
|
||
**Purpose**
|
||
Delete a project and unlink all associated resources. The resources themselves remain in the Resource Registry.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Project name.
|
||
- `--force/-f`: Delete even if active plans exist.
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete local/docs
|
||
|
||
Delete project local/docs? This cannot be undone. [y/N]: y
|
||
|
||
╭─ Deletion Summary ──────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/docs │
|
||
│ <span style="color: yellow; font-weight: 600;">Resources:</span> 1 unlinked │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Data Dir:</span> /repos/docs/.cleveragents │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Index Cleanup ────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Text Index:</span> cleared │
|
||
│ <span style="color: yellow; font-weight: 600;">Vectors:</span> 240 removed │
|
||
│ <span style="color: yellow; font-weight: 600;">Graph Triples:</span> none │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Storage Freed:</span> 12 MB │
|
||
╰────────────────────────╯
|
||
|
||
╭─ Backups ────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Snapshot:</span> /backups/local-docs-2026-02-08.tgz │
|
||
│ <span style="color: yellow; font-weight: 600;">Retention:</span> 7 days │
|
||
╰──────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project deleted
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project delete local/docs
|
||
|
||
Delete project local/docs? This cannot be undone. [y/N]: y
|
||
|
||
Deletion Summary
|
||
Project: local/docs
|
||
Resources: 1 unlinked
|
||
Data Dir: /repos/docs/.cleveragents
|
||
|
||
Index Cleanup
|
||
Text Index: cleared
|
||
Vectors: 240 removed
|
||
Graph Triples: none
|
||
Storage Freed: 12 MB
|
||
|
||
Backups
|
||
Snapshot: /backups/local-docs-2026-02-08.tgz
|
||
Retention: 7 days
|
||
|
||
[OK] Project deleted
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project delete local/docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"deletion_summary": {
|
||
"project": "local/docs",
|
||
"resources_unlinked": 1,
|
||
"data_dir": "/repos/docs/.cleveragents"
|
||
},
|
||
"index_cleanup": {
|
||
"text_index": "cleared",
|
||
"vectors": "240 removed",
|
||
"graph_triples": "none",
|
||
"storage_freed_mb": 12
|
||
},
|
||
"backups": {
|
||
"snapshot": "/backups/local-docs-2026-02-08.tgz",
|
||
"retention_days": 7
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 530 },
|
||
"messages": [{ "level": "ok", "text": "Project deleted" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project delete local/docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
deletion_summary:
|
||
project: local/docs
|
||
resources_unlinked: 1
|
||
data_dir: /repos/docs/.cleveragents
|
||
index_cleanup:
|
||
text_index: cleared
|
||
vectors: 240 removed
|
||
graph_triples: none
|
||
storage_freed_mb: 12
|
||
backups:
|
||
snapshot: /backups/local-docs-2026-02-08.tgz
|
||
retention_days: 7
|
||
timing:
|
||
duration_ms: 530
|
||
messages:
|
||
- level: ok
|
||
text: Project deleted
|
||
```
|
||
|
||
Attempting to delete a project that has active plans (without `--force`):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete local/api-service
|
||
|
||
Delete project local/api-service? [y/N]: y
|
||
|
||
╭─ Delete Blocked ──────────────────────────────────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">Cannot delete:</span> project has active plans │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 2 │
|
||
│ <span style="opacity: 0.7;">01HXM7A9 — execute/processing (local/code-coverage)</span> │
|
||
│ <span style="opacity: 0.7;">01HXM4J1 — strategize/processing (local/refactor-api)</span> │
|
||
╰───────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Resolution ──────────────────────────────────────────────────────╮
|
||
│ - Cancel or complete active plans first, or │
|
||
│ - Use <span style="color: cyan;">--force</span> to cancel all active plans and delete the project │
|
||
╰───────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Delete blocked — 2 active plans
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project delete local/api-service
|
||
|
||
Delete project local/api-service? [y/N]: y
|
||
|
||
Delete Blocked
|
||
Cannot delete: project has active plans
|
||
Active Plans: 2
|
||
01HXM7A9 -- execute/processing (local/code-coverage)
|
||
01HXM4J1 -- strategize/processing (local/refactor-api)
|
||
|
||
Resolution
|
||
- Cancel or complete active plans first, or
|
||
- Use --force to cancel all active plans and delete the project
|
||
|
||
[ERROR] Delete blocked -- 2 active plans
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project delete local/api-service",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"delete_blocked": {
|
||
"reason": "project has active plans",
|
||
"active_plans": [
|
||
{ "plan_id": "01HXM7A9", "phase": "execute/processing", "action": "local/code-coverage" },
|
||
{ "plan_id": "01HXM4J1", "phase": "strategize/processing", "action": "local/refactor-api" }
|
||
]
|
||
},
|
||
"resolution": [
|
||
"Cancel or complete active plans first",
|
||
"Use --force to cancel all active plans and delete the project"
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 38 },
|
||
"messages": [{ "level": "error", "text": "Delete blocked — 2 active plans" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project delete local/api-service
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
delete_blocked:
|
||
reason: project has active plans
|
||
active_plans:
|
||
- plan_id: 01HXM7A9
|
||
phase: execute/processing
|
||
action: local/code-coverage
|
||
- plan_id: 01HXM4J1
|
||
phase: strategize/processing
|
||
action: local/refactor-api
|
||
resolution:
|
||
- Cancel or complete active plans first
|
||
- Use --force to cancel all active plans and delete the project
|
||
timing:
|
||
duration_ms: 38
|
||
messages:
|
||
- level: error
|
||
text: "Delete blocked \u2014 2 active plans"
|
||
```
|
||
|
||
Force-deleting a project with active plans:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project delete <span style="color: cyan;">--force</span> <span style="color: cyan;">--yes</span> local/api-service
|
||
|
||
╭─ Force Delete ─────────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Cancelling:</span> 2 active plans │
|
||
│ <span style="opacity: 0.7;">01HXM7A9 — cancelled (was execute/processing)</span> │
|
||
│ <span style="opacity: 0.7;">01HXM4J1 — cancelled (was strategize/processing)</span> │
|
||
╰────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Deleted ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resources Unlinked:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Validations Detached:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Plans Cancelled:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context Policies:</span> cleared │
|
||
╰──────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Project force-deleted
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project delete --force --yes local/api-service
|
||
|
||
Force Delete
|
||
Cancelling: 2 active plans
|
||
01HXM7A9 -- cancelled (was execute/processing)
|
||
01HXM4J1 -- cancelled (was strategize/processing)
|
||
|
||
Deleted
|
||
Project: local/api-service
|
||
Resources Unlinked: 2
|
||
Validations Detached: 3
|
||
Plans Cancelled: 2
|
||
Context Policies: cleared
|
||
|
||
[OK] Project force-deleted
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents project delete --force --yes local/api-service",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"force_delete": {
|
||
"cancelled_plans": [
|
||
{ "plan_id": "01HXM7A9", "previous_state": "execute/processing" },
|
||
{ "plan_id": "01HXM4J1", "previous_state": "strategize/processing" }
|
||
]
|
||
},
|
||
"deleted": {
|
||
"project": "local/api-service",
|
||
"resources_unlinked": 2,
|
||
"validations_detached": 3,
|
||
"plans_cancelled": 2,
|
||
"context_policies": "cleared"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 245 },
|
||
"messages": [{ "level": "ok", "text": "Project force-deleted" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents project delete --force --yes local/api-service
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
force_delete:
|
||
cancelled_plans:
|
||
- plan_id: 01HXM7A9
|
||
previous_state: execute/processing
|
||
- plan_id: 01HXM4J1
|
||
previous_state: strategize/processing
|
||
deleted:
|
||
project: local/api-service
|
||
resources_unlinked: 2
|
||
validations_detached: 3
|
||
plans_cancelled: 2
|
||
context_policies: cleared
|
||
timing:
|
||
duration_ms: 245
|
||
messages:
|
||
- level: ok
|
||
text: Project force-deleted
|
||
```
|
||
|
||
##### agents project context
|
||
|
||
**Purpose**
|
||
Manage ACMS context policies for the hot/warm/cold tiers, per-view context selection, strategy configuration, UKO depth/breadth parameters, and context budget tuning.
|
||
|
||
###### agents project context set
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project context set[<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--include-resource</span> <span style="color: #66cc66;"><INCLUDE_RESOURCE></span>]...
|
||
[<span style="color: cyan;">--exclude-resource</span> <span style="color: #66cc66;"><EXCLUDE_RESOURCE></span>]...
|
||
[<span style="color: cyan;">--include-path</span> <span style="color: #66cc66;"><INCLUDE_GLOB></span>]...
|
||
[<span style="color: cyan;">--exclude-path</span> <span style="color: #66cc66;"><EXCLUDE_GLOB></span>]...
|
||
[<span style="color: cyan;">--hot-max-tokens</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--warm-max-decisions</span> <span style="color: #66cc66;"><N_WARM_MAX></span>]
|
||
[<span style="color: cyan;">--cold-max-decisions</span> <span style="color: #66cc66;"><N_COLD_MAX></span>]
|
||
[<span style="color: cyan;">--query-limit</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--max-file-size</span> <span style="color: #66cc66;"><MAX_FILE_BYTES></span>]
|
||
[<span style="color: cyan;">--max-total-size</span> <span style="color: #66cc66;"><MAX_TOTAL_BYTES></span>]
|
||
[<span style="color: cyan;">--summarize</span>|<span style="color: cyan;">--no-summarize</span>]
|
||
[<span style="color: cyan;">--summary-max-tokens</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]...
|
||
[<span style="color: cyan;">--default-breadth</span> <span style="color: #66cc66;"><N></span>]
|
||
[<span style="color: cyan;">--default-depth</span> <span style="color: #66cc66;"><INT_OR_NAME></span>]
|
||
[<span style="color: cyan;">--depth-gradient</span> <span style="color: #66cc66;"><HOP:INT_OR_NAME></span>]...
|
||
[<span style="color: cyan;">--skeleton-ratio</span> <span style="color: #66cc66;"><FLOAT></span>]
|
||
[<span style="color: cyan;">--temporal-scope</span> (<span style="color: magenta;">current|recent|all</span>)]
|
||
[<span style="color: cyan;">--auto-refresh</span>|<span style="color: cyan;">--no-auto-refresh</span>]
|
||
[<span style="color: cyan;">--execution-environment</span> <span style="color: #66cc66;"><RESOURCE_NAME></span>]
|
||
[<span style="color: cyan;">--execution-env-priority</span> (<span style="color: magenta;">fallback|override</span>)]
|
||
[<span style="color: cyan;">--clear</span>] <span style="color: #66cc66;"><PROJECT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Set the context policy for a project and (optionally) a specific view.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument, at end of command).
|
||
- `--view strategize|execute|apply|default`: Which view this policy applies to.
|
||
- `--include-resource NAME`: Resource allowlist (repeatable).
|
||
- `--exclude-resource NAME`: Resource denylist (repeatable).
|
||
- `--include-path GLOB`: Path allowlist (repeatable).
|
||
- `--exclude-path GLOB`: Path denylist (repeatable).
|
||
- `--hot-max-tokens N`: Maximum token budget for hot context. This is a soft cap and may be null. The actor/LLM hard limit can be lower; the effective hot context is the lesser of the two.
|
||
- `--warm-max-decisions N`: Maximum number of decisions kept in warm context.
|
||
- `--cold-max-decisions N`: Maximum number of decisions kept in cold context.
|
||
- `--query-limit N`: Max number of retrieval results per query.
|
||
- `--max-file-size BYTES`: Max file size included in context.
|
||
- `--max-total-size BYTES`: Max total size across included files.
|
||
- `--summarize/--no-summarize`: Enable or disable summarization for large context segments.
|
||
- `--summary-max-tokens N`: Token limit for generated summaries.
|
||
- `--strategy STRATEGY`: ACMS context strategy to enable for this view (repeatable). Overrides the global `context.strategies.enabled` list. Built-in: `simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`, `arce`, `temporal-archaeology`, `plan-decision-context`.
|
||
- `--default-breadth N`: Default number of hops from focus nodes in the UKO graph. `0` = focus nodes only. Default: `2`.
|
||
- `--default-depth INT_OR_NAME`: Default detail depth for context fragments. Accepts a raw integer (e.g., `4`) or a named level from the active domain's DetailLevelMap (e.g., `SIGNATURES`, `MEMBER_SUMMARY`). Named levels are resolved to integers via the DetailLevelMap inheritance chain. Default: `3` (typically `MEMBER_SUMMARY` / `FULL_TOC` / `TYPED_COLUMNS` depending on domain).
|
||
- `--depth-gradient HOP:INT_OR_NAME`: Per-hop detail depth override (repeatable). Format: `0:9`, `1:4`, `2:0` or `0:FULL_SOURCE`, `1:SIGNATURES`, `2:MODULE_LISTING`. Hops not specified use `--default-depth`.
|
||
- `--skeleton-ratio FLOAT`: Fraction of context budget reserved for inherited plan skeleton. Range: 0.0–1.0. Default: `0.15`.
|
||
- `--temporal-scope current|recent|all`: Temporal scope for UKO node resolution. Default: `current`.
|
||
- `--auto-refresh/--no-auto-refresh`: Enable or disable automatic context re-assembly on budget changes.
|
||
- `--execution-environment RESOURCE_NAME`: Name of a `container-instance` or `devcontainer-instance` resource to use as the default execution environment for this project. When set, tool invocations during plan execution are routed to this container unless overridden at the plan level. See [ADR-043 §3.3](adr/ADR-043-devcontainer-integration.md).
|
||
- `--execution-env-priority fallback|override`: Priority semantics for the project-level execution environment. `fallback` (default): defers to auto-detected devcontainers when present; used only when no closer-scoped environment exists. `override`: always uses the specified environment, bypassing devcontainer auto-detection. See §Execution Environment Routing.
|
||
- `--clear`: Clear the policy for the selected view.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context set <span style="color: cyan;">--view</span> strategize \
|
||
<span style="color: cyan;">--include-resource</span> repo <span style="color: cyan;">--exclude-path</span> <span style="color: #66cc66;">"**/node_modules/**"</span> \
|
||
<span style="color: cyan;">--hot-max-tokens</span> 12000 <span style="color: cyan;">--warm-max-decisions</span> 50 <span style="color: cyan;">--cold-max-decisions</span> 200 \
|
||
<span style="color: cyan;">--summarize</span> <span style="color: cyan;">--summary-max-tokens</span> 800 local/api-service
|
||
|
||
╭─ Context Policy ────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
|
||
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Limits ─────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Hot Tokens:</span> 12000 (soft cap) │
|
||
│ <span style="color: magenta; font-weight: 600;">Warm Decisions:</span> 50 │
|
||
│ <span style="color: magenta; font-weight: 600;">Cold Decisions:</span> 200 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Query Limit:</span> 20 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max Total Size:</span> 50 MB │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Summarization ─╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Enabled:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max Tokens:</span> 800 │
|
||
╰─────────────────╯
|
||
|
||
╭─ Other Views ────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">execute:</span> (default) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">apply:</span> (default) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">default:</span> (unset) │
|
||
╰──────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context policy updated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project context set --view strategize \
|
||
--include-resource repo --exclude-path "**/node_modules/**" \
|
||
--hot-max-tokens 12000 --warm-max-decisions 50 --cold-max-decisions 200 \
|
||
--summarize --summary-max-tokens 800 local/api-service
|
||
|
||
Context Policy
|
||
Project: local/api-service
|
||
View: strategize
|
||
Include: repo
|
||
Exclude: **/node_modules/**
|
||
|
||
Limits
|
||
Hot Tokens: 12000 (soft cap)
|
||
Warm Decisions: 50
|
||
Cold Decisions: 200
|
||
Query Limit: 20
|
||
Max File Size: 1 MB
|
||
Max Total Size: 50 MB
|
||
|
||
Summarization
|
||
Enabled: yes
|
||
Max Tokens: 800
|
||
|
||
Other Views
|
||
execute: (default)
|
||
apply: (default)
|
||
default: (unset)
|
||
|
||
[OK] Context policy updated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "project context set",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_policy": {
|
||
"project": "local/api-service",
|
||
"view": "strategize",
|
||
"include_resources": ["repo"],
|
||
"exclude_paths": ["**/node_modules/**"]
|
||
},
|
||
"limits": {
|
||
"hot_max_tokens": 12000,
|
||
"warm_max_decisions": 50,
|
||
"cold_max_decisions": 200,
|
||
"query_limit": 20,
|
||
"max_file_size": "1 MB",
|
||
"max_total_size": "50 MB"
|
||
},
|
||
"summarization": {
|
||
"enabled": true,
|
||
"max_tokens": 800
|
||
},
|
||
"other_views": {
|
||
"execute": "(default)",
|
||
"apply": "(default)",
|
||
"default": "(unset)"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 42
|
||
},
|
||
"messages": ["Context policy updated"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: project context set
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_policy:
|
||
project: local/api-service
|
||
view: strategize
|
||
include_resources:
|
||
- repo
|
||
exclude_paths:
|
||
- "**/node_modules/**"
|
||
limits:
|
||
hot_max_tokens: 12000
|
||
warm_max_decisions: 50
|
||
cold_max_decisions: 200
|
||
query_limit: 20
|
||
max_file_size: 1 MB
|
||
max_total_size: 50 MB
|
||
summarization:
|
||
enabled: true
|
||
max_tokens: 800
|
||
other_views:
|
||
execute: (default)
|
||
apply: (default)
|
||
default: (unset)
|
||
timing:
|
||
duration_ms: 42
|
||
messages:
|
||
- Context policy updated
|
||
```
|
||
|
||
###### agents project context show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project context show [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
<span style="color: #66cc66;"><PROJECT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show the active context policy for a project.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument, at end of command).
|
||
- `--view strategize|execute|apply|default`: View to display.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context show <span style="color: cyan;">--view</span> strategize local/api-service
|
||
|
||
╭─ Context Policy ────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Include:</span> repo │
|
||
│ <span style="color: yellow; font-weight: 600;">Exclude:</span> **/node_modules/** │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Limits ─────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Hot Tokens:</span> 12000 (soft cap) │
|
||
│ <span style="color: magenta; font-weight: 600;">Warm Decisions:</span> 50 │
|
||
│ <span style="color: magenta; font-weight: 600;">Cold Decisions:</span> 200 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Query Limit:</span> 20 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max File Size:</span> 1 MB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max Total Size:</span> 50 MB │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Summarization ─╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Enabled:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max Tokens:</span> 800 │
|
||
╰─────────────────╯
|
||
|
||
╭─ Current Usage ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Hot Context:</span> 8,420 / 12,000 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Warm Entries:</span> 12 / 50 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cold Entries:</span> 47 / 200 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Indexed Resources:</span> 1 │
|
||
╰──────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context policy loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project context show --view strategize local/api-service
|
||
|
||
Context Policy
|
||
Project: local/api-service
|
||
View: strategize
|
||
Include: repo
|
||
Exclude: **/node_modules/**
|
||
|
||
Limits
|
||
Hot Tokens: 12000 (soft cap)
|
||
Warm Decisions: 50
|
||
Cold Decisions: 200
|
||
Query Limit: 20
|
||
Max File Size: 1 MB
|
||
Max Total Size: 50 MB
|
||
|
||
Summarization
|
||
Enabled: yes
|
||
Max Tokens: 800
|
||
|
||
Current Usage
|
||
Hot Context: 8,420 / 12,000
|
||
Warm Entries: 12 / 50
|
||
Cold Entries: 47 / 200
|
||
Indexed Resources: 1
|
||
|
||
[OK] Context policy loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "project context show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_policy": {
|
||
"project": "local/api-service",
|
||
"view": "strategize",
|
||
"include_resources": ["repo"],
|
||
"exclude_paths": ["**/node_modules/**"]
|
||
},
|
||
"limits": {
|
||
"hot_max_tokens": 12000,
|
||
"warm_max_decisions": 50,
|
||
"cold_max_decisions": 200,
|
||
"query_limit": 20,
|
||
"max_file_size": "1 MB",
|
||
"max_total_size": "50 MB"
|
||
},
|
||
"summarization": {
|
||
"enabled": true,
|
||
"max_tokens": 800
|
||
},
|
||
"current_usage": {
|
||
"hot_context_tokens": 8420,
|
||
"hot_context_limit": 12000,
|
||
"warm_entries": 12,
|
||
"warm_limit": 50,
|
||
"cold_entries": 47,
|
||
"cold_limit": 200,
|
||
"indexed_resources": 1
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 38
|
||
},
|
||
"messages": ["Context policy loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: project context show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_policy:
|
||
project: local/api-service
|
||
view: strategize
|
||
include_resources:
|
||
- repo
|
||
exclude_paths:
|
||
- "**/node_modules/**"
|
||
limits:
|
||
hot_max_tokens: 12000
|
||
warm_max_decisions: 50
|
||
cold_max_decisions: 200
|
||
query_limit: 20
|
||
max_file_size: 1 MB
|
||
max_total_size: 50 MB
|
||
summarization:
|
||
enabled: true
|
||
max_tokens: 800
|
||
current_usage:
|
||
hot_context_tokens: 8420
|
||
hot_context_limit: 12000
|
||
warm_entries: 12
|
||
warm_limit: 50
|
||
cold_entries: 47
|
||
cold_limit: 200
|
||
indexed_resources: 1
|
||
timing:
|
||
duration_ms: 38
|
||
messages:
|
||
- Context policy loaded
|
||
```
|
||
|
||
###### agents project context inspect
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project context inspect [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]
|
||
[<span style="color: cyan;">--focus</span> <span style="color: #66cc66;"><UKO_URI></span>]...
|
||
[<span style="color: cyan;">--breadth</span> <span style="color: #66cc66;"><N></span>] [<span style="color: cyan;">--depth</span> <span style="color: #66cc66;"><INT_OR_NAME></span>]
|
||
<span style="color: #66cc66;"><PROJECT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Inspect the current state of the ACMS context assembly for a project. Shows the UKO graph structure, active strategies, indexed resources, context budget usage, and the most recent fusion result. Useful for debugging context quality issues.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument, at end of command).
|
||
- `--view strategize|execute|apply|default`: View to inspect. Default: `default`.
|
||
- `--strategy STRATEGY`: Filter to show results from a specific strategy only.
|
||
- `--focus UKO_URI`: Show the UKO subgraph rooted at these focus nodes (repeatable). When omitted, shows a summary of the full indexed graph.
|
||
- `--breadth N`: Override the breadth (hop count) for the focus node expansion. Default: uses the view's `default_breadth`.
|
||
- `--depth INT_OR_NAME`: Override the detail depth for the display. Accepts a raw integer or a named level from the active DetailLevelMap. Default: uses the view's `default_depth`.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context inspect <span style="color: cyan;">--view</span> execute <span style="color: cyan;">--focus</span> uko-py:module/src.auth <span style="color: cyan;">--breadth</span> 2 local/api-service
|
||
|
||
╭─ ACMS Context Inspection ────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">View:</span> execute │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Focus:</span> uko-py:module/src.auth │
|
||
│ <span style="color: magenta; font-weight: 600;">Breadth:</span> 2 hops │ <span style="color: magenta; font-weight: 600;">Depth:</span> 3 (MEMBER_SUMMARY) │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">uko-py:module/src.auth</span> (depth 9/FULL_SOURCE, 1,240 tokens) │
|
||
│ ├─ contains → <span style="color: #5599ff;">uko-py:class/AuthHandler</span> (depth 3, 320 tokens) │
|
||
│ ├─ contains → <span style="color: #5599ff;">uko-py:class/TokenValidator</span> (depth 3, 280 tok) │
|
||
│ ├─ imports → <span style="color: #5599ff;">uko-py:module/src.db</span> (depth 0, 90 tokens) │
|
||
│ └─ imports → <span style="color: #5599ff;">uko-py:module/src.config</span> (depth 0, 60 tok) │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Active Strategies ──────────────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">breadth-depth-navigator</span> quality=0.85 budget=45% 4 fragments │
|
||
│ <span style="color: #66cc66; font-weight: 600;">semantic-embedding</span> quality=0.60 budget=35% 6 fragments │
|
||
│ <span style="color: #66cc66; font-weight: 600;">simple-keyword</span> quality=0.30 budget=20% 3 fragments │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Budget ─────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Model Window:</span> 128,000 tokens │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Response Reserve:</span> 4,096 tokens │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Definitions:</span> 2,400 tokens │
|
||
│ <span style="color: #5599ff; font-weight: 600;">System Prompt:</span> 1,200 tokens │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skeleton Reserve:</span> 18,046 (15%) │
|
||
│ <span style="color: magenta; font-weight: 600;">Available Budget:</span> 102,258 tokens │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Used:</span> 1,990 / 102,258 (1.9%) │
|
||
╰──────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context inspection complete
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project context inspect --view execute --focus uko-py:module/src.auth --breadth 2 local/api-service
|
||
|
||
ACMS Context Inspection
|
||
Project: local/api-service
|
||
View: execute
|
||
Focus: uko-py:module/src.auth
|
||
Breadth: 2 hops Depth: 3 (MEMBER_SUMMARY)
|
||
|
||
UKO Graph (2-hop neighborhood)
|
||
uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens)
|
||
contains -> uko-py:class/AuthHandler (depth 3, 320 tokens)
|
||
contains -> uko-py:class/TokenValidator (depth 3, 280 tok)
|
||
imports -> uko-py:module/src.db (depth 0, 90 tokens)
|
||
imports -> uko-py:module/src.config (depth 0, 60 tok)
|
||
|
||
Active Strategies
|
||
Strategy Quality Budget Fragments
|
||
------------------------- ------- ------ ---------
|
||
breadth-depth-navigator 0.85 45% 4
|
||
semantic-embedding 0.60 35% 6
|
||
simple-keyword 0.30 20% 3
|
||
|
||
Budget
|
||
Model Window: 128,000 tokens
|
||
Response Reserve: 4,096 tokens
|
||
Tool Definitions: 2,400 tokens
|
||
System Prompt: 1,200 tokens
|
||
Skeleton Reserve: 18,046 (15%)
|
||
Available Budget: 102,258 tokens
|
||
Used: 1,990 / 102,258 (1.9%)
|
||
|
||
[OK] Context inspection complete
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "project context inspect",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"inspection": {
|
||
"project": "local/api-service",
|
||
"view": "execute",
|
||
"focus": ["uko-py:module/src.auth"],
|
||
"breadth": 2,
|
||
"depth": 3,
|
||
"depth_name": "MEMBER_SUMMARY"
|
||
},
|
||
"uko_graph": {
|
||
"root": "uko-py:module/src.auth",
|
||
"root_depth": 9,
|
||
"root_depth_name": "FULL_SOURCE",
|
||
"root_tokens": 1240,
|
||
"edges": [
|
||
{ "relation": "contains", "target": "uko-py:class/AuthHandler", "depth": 3, "tokens": 320 },
|
||
{ "relation": "contains", "target": "uko-py:class/TokenValidator", "depth": 3, "tokens": 280 },
|
||
{ "relation": "imports", "target": "uko-py:module/src.db", "depth": 0, "tokens": 90 },
|
||
{ "relation": "imports", "target": "uko-py:module/src.config", "depth": 0, "tokens": 60 }
|
||
]
|
||
},
|
||
"active_strategies": [
|
||
{ "name": "breadth-depth-navigator", "quality": 0.85, "budget_pct": 0.45, "fragments": 4 },
|
||
{ "name": "semantic-embedding", "quality": 0.60, "budget_pct": 0.35, "fragments": 6 },
|
||
{ "name": "simple-keyword", "quality": 0.30, "budget_pct": 0.20, "fragments": 3 }
|
||
],
|
||
"budget": {
|
||
"model_window": 128000,
|
||
"response_reserve": 4096,
|
||
"tool_definitions": 2400,
|
||
"system_prompt": 1200,
|
||
"skeleton_reserve": 18046,
|
||
"skeleton_ratio": 0.15,
|
||
"available_budget": 102258,
|
||
"used": 1990,
|
||
"utilization": 0.019
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 185
|
||
},
|
||
"messages": ["Context inspection complete"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: project context inspect
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
inspection:
|
||
project: local/api-service
|
||
view: execute
|
||
focus:
|
||
- uko-py:module/src.auth
|
||
breadth: 2
|
||
depth: 3
|
||
depth_name: MEMBER_SUMMARY
|
||
uko_graph:
|
||
root: uko-py:module/src.auth
|
||
root_depth: 9
|
||
root_depth_name: FULL_SOURCE
|
||
root_tokens: 1240
|
||
edges:
|
||
- relation: contains
|
||
target: uko-py:class/AuthHandler
|
||
depth: 3
|
||
tokens: 320
|
||
- relation: contains
|
||
target: uko-py:class/TokenValidator
|
||
depth: 3
|
||
tokens: 280
|
||
- relation: imports
|
||
target: uko-py:module/src.db
|
||
depth: 0
|
||
tokens: 90
|
||
- relation: imports
|
||
target: uko-py:module/src.config
|
||
depth: 0
|
||
tokens: 60
|
||
active_strategies:
|
||
- name: breadth-depth-navigator
|
||
quality: 0.85
|
||
budget_pct: 0.45
|
||
fragments: 4
|
||
- name: semantic-embedding
|
||
quality: 0.60
|
||
budget_pct: 0.35
|
||
fragments: 6
|
||
- name: simple-keyword
|
||
quality: 0.30
|
||
budget_pct: 0.20
|
||
fragments: 3
|
||
budget:
|
||
model_window: 128000
|
||
response_reserve: 4096
|
||
tool_definitions: 2400
|
||
system_prompt: 1200
|
||
skeleton_reserve: 18046
|
||
skeleton_ratio: 0.15
|
||
available_budget: 102258
|
||
used: 1990
|
||
utilization: 0.019
|
||
timing:
|
||
duration_ms: 185
|
||
messages:
|
||
- Context inspection complete
|
||
```
|
||
|
||
###### agents project context simulate
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> project context simulate [<span style="color: cyan;">--view</span> (<span style="color: magenta;">strategize|execute|apply|default</span>)]
|
||
[<span style="color: cyan;">--budget</span> <span style="color: #66cc66;"><TOKENS></span>]
|
||
[<span style="color: cyan;">--focus</span> <span style="color: #66cc66;"><UKO_URI></span>]...
|
||
[<span style="color: cyan;">--strategy</span> <span style="color: #66cc66;"><STRATEGY></span>]...
|
||
<span style="color: #66cc66;"><PROJECT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Simulate a context assembly run without invoking an actor. Produces a dry-run report showing what the Context Assembly Pipeline would include in the context payload, which strategies contributed, how the budget was allocated, and what was excluded. Useful for tuning context view configurations before running plans.
|
||
|
||
**Arguments**
|
||
|
||
- `<PROJECT>`: Project name (positional argument, at end of command).
|
||
- `--view strategize|execute|apply|default`: View to simulate. Default: `default`.
|
||
- `--budget TOKENS`: Override the context budget in tokens. When omitted, uses the dynamic budget calculation.
|
||
- `--focus UKO_URI`: Focus nodes for the simulation (repeatable). When omitted, uses a default focus derived from recent plan activity.
|
||
- `--strategy STRATEGY`: Override which strategies to run (repeatable). When omitted, uses the view's configured strategies.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> project context simulate <span style="color: cyan;">--view</span> strategize <span style="color: cyan;">--budget</span> 16000 \
|
||
<span style="color: cyan;">--focus</span> uko-py:module/src.auth <span style="color: cyan;">--focus</span> uko-py:module/src.db \
|
||
local/api-service
|
||
|
||
╭─ ACMS Simulation ────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
|
||
│ <span style="color: magenta; font-weight: 600;">Budget:</span> 16,000 tokens (override) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Focus:</span> uko-py:module/src.auth, uko-py:module/src.db │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Strategy Results ───────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">breadth-depth-navigator</span> │
|
||
│ Confidence: 0.85 │ Budget: 7,200 tokens │ 12 fragments │
|
||
│ Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95) │
|
||
│ src/db/models.py (depth 3, 480t, score=0.88) │
|
||
│ │
|
||
│ <span style="color: cyan; font-weight: 600;">semantic-embedding</span> │
|
||
│ Confidence: 0.60 │ Budget: 5,600 tokens │ 8 fragments │
|
||
│ Top: src/auth/jwt.py (depth 3, 380t, score=0.82) │
|
||
│ src/middleware/auth_check.py (depth 3, 290t, score=0.79) │
|
||
│ │
|
||
│ <span style="color: cyan; font-weight: 600;">simple-keyword</span> │
|
||
│ Confidence: 0.30 │ Budget: 3,200 tokens │ 5 fragments │
|
||
│ Top: src/auth/utils.py (depth 6, 210t, score=0.71) │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Fusion Result ──────────────────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Included:</span> 18 fragments (14,820 tokens, 92.6% of budget) │
|
||
│ <span style="color: yellow; font-weight: 600;">Excluded:</span> 7 fragments (3,200 tokens, below budget cutoff) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Deduplicated:</span> 4 fragments merged │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skeleton:</span> 2,400 tokens (15% reserve) │
|
||
│ <span style="color: magenta; font-weight: 600;">Preamble:</span> 180 tokens │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Simulation complete (dry run — no context was assembled)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents project context simulate --view strategize --budget 16000 \
|
||
--focus uko-py:module/src.auth --focus uko-py:module/src.db \
|
||
local/api-service
|
||
|
||
ACMS Simulation
|
||
Project: local/api-service
|
||
View: strategize
|
||
Budget: 16,000 tokens (override)
|
||
Focus: uko-py:module/src.auth, uko-py:module/src.db
|
||
|
||
Strategy Results
|
||
breadth-depth-navigator
|
||
Confidence: 0.85 Budget: 7,200 tokens 12 fragments
|
||
Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95)
|
||
src/db/models.py (depth 3, 480t, score=0.88)
|
||
|
||
semantic-embedding
|
||
Confidence: 0.60 Budget: 5,600 tokens 8 fragments
|
||
Top: src/auth/jwt.py (depth 3, 380t, score=0.82)
|
||
src/middleware/auth_check.py (depth 3, 290t, score=0.79)
|
||
|
||
simple-keyword
|
||
Confidence: 0.30 Budget: 3,200 tokens 5 fragments
|
||
Top: src/auth/utils.py (depth 6, 210t, score=0.71)
|
||
|
||
Fusion Result
|
||
Included: 18 fragments (14,820 tokens, 92.6% of budget)
|
||
Excluded: 7 fragments (3,200 tokens, below budget cutoff)
|
||
Deduplicated: 4 fragments merged
|
||
Skeleton: 2,400 tokens (15% reserve)
|
||
Preamble: 180 tokens
|
||
|
||
[OK] Simulation complete (dry run -- no context was assembled)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "project context simulate",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"simulation": {
|
||
"project": "local/api-service",
|
||
"view": "strategize",
|
||
"budget": 16000,
|
||
"budget_source": "override",
|
||
"focus": ["uko-py:module/src.auth", "uko-py:module/src.db"]
|
||
},
|
||
"strategy_results": [
|
||
{
|
||
"name": "breadth-depth-navigator",
|
||
"confidence": 0.85,
|
||
"budget_tokens": 7200,
|
||
"fragments": 12,
|
||
"top": [
|
||
{ "path": "src/auth/__init__.py", "depth": 9, "tokens": 1240, "score": 0.95 },
|
||
{ "path": "src/db/models.py", "depth": 3, "tokens": 480, "score": 0.88 }
|
||
]
|
||
},
|
||
{
|
||
"name": "semantic-embedding",
|
||
"confidence": 0.60,
|
||
"budget_tokens": 5600,
|
||
"fragments": 8,
|
||
"top": [
|
||
{ "path": "src/auth/jwt.py", "depth": 3, "tokens": 380, "score": 0.82 },
|
||
{ "path": "src/middleware/auth_check.py", "depth": 3, "tokens": 290, "score": 0.79 }
|
||
]
|
||
},
|
||
{
|
||
"name": "simple-keyword",
|
||
"confidence": 0.30,
|
||
"budget_tokens": 3200,
|
||
"fragments": 5,
|
||
"top": [
|
||
{ "path": "src/auth/utils.py", "depth": 6, "tokens": 210, "score": 0.71 }
|
||
]
|
||
}
|
||
],
|
||
"fusion_result": {
|
||
"included_fragments": 18,
|
||
"included_tokens": 14820,
|
||
"budget_utilization": 0.926,
|
||
"excluded_fragments": 7,
|
||
"excluded_tokens": 3200,
|
||
"deduplicated_fragments": 4,
|
||
"skeleton_tokens": 2400,
|
||
"skeleton_ratio": 0.15,
|
||
"preamble_tokens": 180
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 310
|
||
},
|
||
"messages": ["Simulation complete (dry run -- no context was assembled)"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: project context simulate
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
simulation:
|
||
project: local/api-service
|
||
view: strategize
|
||
budget: 16000
|
||
budget_source: override
|
||
focus:
|
||
- uko-py:module/src.auth
|
||
- uko-py:module/src.db
|
||
strategy_results:
|
||
- name: breadth-depth-navigator
|
||
confidence: 0.85
|
||
budget_tokens: 7200
|
||
fragments: 12
|
||
top:
|
||
- path: src/auth/__init__.py
|
||
depth: 9
|
||
tokens: 1240
|
||
score: 0.95
|
||
- path: src/db/models.py
|
||
depth: 3
|
||
tokens: 480
|
||
score: 0.88
|
||
- name: semantic-embedding
|
||
confidence: 0.60
|
||
budget_tokens: 5600
|
||
fragments: 8
|
||
top:
|
||
- path: src/auth/jwt.py
|
||
depth: 3
|
||
tokens: 380
|
||
score: 0.82
|
||
- path: src/middleware/auth_check.py
|
||
depth: 3
|
||
tokens: 290
|
||
score: 0.79
|
||
- name: simple-keyword
|
||
confidence: 0.30
|
||
budget_tokens: 3200
|
||
fragments: 5
|
||
top:
|
||
- path: src/auth/utils.py
|
||
depth: 6
|
||
tokens: 210
|
||
score: 0.71
|
||
fusion_result:
|
||
included_fragments: 18
|
||
included_tokens: 14820
|
||
budget_utilization: 0.926
|
||
excluded_fragments: 7
|
||
excluded_tokens: 3200
|
||
deduplicated_fragments: 4
|
||
skeleton_tokens: 2400
|
||
skeleton_ratio: 0.15
|
||
preamble_tokens: 180
|
||
timing:
|
||
duration_ms: 310
|
||
messages:
|
||
- "Simulation complete (dry run -- no context was assembled)"
|
||
```
|
||
|
||
#### agents actor
|
||
|
||
**Purpose**
|
||
Manage actors and run actor configurations directly.
|
||
|
||
##### agents actor run
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor run [(<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><OUTPUT_FILE></span>]
|
||
[<span style="color: yellow;">-v</span>...] [<span style="color: cyan;">--unsafe</span>|<span style="color: yellow;">-u</span>] [<span style="color: cyan;">--context</span> <span style="color: #66cc66;"><CONTEXT_NAME></span>]
|
||
[<span style="color: cyan;">--context-dir</span> <span style="color: #66cc66;"><CONTEXT_PATH></span>] [<span style="color: cyan;">--load-context</span> <span style="color: #66cc66;"><LOAD_CONTEXT_NAME></span>]
|
||
[(<span style="color: magenta;"><span style="color: cyan;">--temperature</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TEMP></span>] [<span style="color: cyan;">--allow-rxpy-in-run-mode</span>]
|
||
[<span style="color: cyan;">--skill</span> <span style="color: #66cc66;"><SKILL></span>]... <span style="color: #66cc66;"><NAME></span> <span style="color: #66cc66;"><PROMPT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Run a named actor in isolation with simple, manual context.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: The name of the actor to run (required).
|
||
- `<PROMPT>`: Prompt text (positional argument).
|
||
- `--output/-o FILE`: Output file path.
|
||
- `--verbose/-v`: Increase log verbosity (repeatable). Same semantics as the global `-v` flag: no `-v` = normal output only, `-v` = ERROR, `-vv` = WARN, `-vvv` = INFO, `-vvvv` = DEBUG, `-vvvvv` = TRACE.
|
||
- `--unsafe/-u`: Allow unsafe configs.
|
||
- `--context NAME`: Named actor context to attach.
|
||
- `--context-dir PATH`: Context storage location.
|
||
- `--load-context FILE`: Load context from JSON.
|
||
- `--temperature/-t FLOAT`: Override temperature.
|
||
- `--skill NAME`: Skill to attach (repeatable).
|
||
- `--allow-rxpy-in-run-mode`: Allow RxPy routes in run mode.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--context</span> docs local/code_reader <span style="color: #66cc66;">"Summarize the README"</span>
|
||
|
||
╭─ Run Summary ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/code_reader │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: yellow; font-weight: 600;">Temperature:</span> 0.2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> anthropic │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Model:</span> claude-3.5 │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Inputs ─────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Prompt:</span> Summarize the README │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Context Files:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Context Size:</span> 12.4 KB │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Result Metrics ───────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Output:</span> stdout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input Tokens:</span> 1,524 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output Tokens:</span> 842 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 1.8s │
|
||
│ <span style="color: yellow; font-weight: 600;">Cost:</span> $0.0021 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 0 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Summary generated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor run --context docs local/code_reader "Summarize the README"
|
||
|
||
Run Summary
|
||
Actor: local/code_reader
|
||
Context: docs
|
||
Temperature: 0.2
|
||
Provider: anthropic
|
||
Model: claude-3.5
|
||
|
||
Inputs
|
||
Prompt: Summarize the README
|
||
Context Files: 3
|
||
Context Size: 12.4 KB
|
||
|
||
Result Metrics
|
||
Output: stdout
|
||
Input Tokens: 1,524
|
||
Output Tokens: 842
|
||
Duration: 1.8s
|
||
Cost: $0.0021
|
||
Tool Calls: 0
|
||
|
||
[OK] Summary generated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor run --context docs local/code_reader \"Summarize the README\"",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"run_summary": {
|
||
"actor": "local/code_reader",
|
||
"context": "docs",
|
||
"temperature": 0.2,
|
||
"provider": "anthropic",
|
||
"model": "claude-3.5"
|
||
},
|
||
"inputs": {
|
||
"prompt": "Summarize the README",
|
||
"context_files": 3,
|
||
"context_size": "12.4 KB"
|
||
},
|
||
"result_metrics": {
|
||
"output": "stdout",
|
||
"input_tokens": 1524,
|
||
"output_tokens": 842,
|
||
"duration_s": 1.8,
|
||
"cost": "$0.0021",
|
||
"tool_calls": 0
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 1800
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Summary generated" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor run --context docs local/code_reader "Summarize the README"
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
run_summary:
|
||
actor: local/code_reader
|
||
context: docs
|
||
temperature: 0.2
|
||
provider: anthropic
|
||
model: claude-3.5
|
||
inputs:
|
||
prompt: Summarize the README
|
||
context_files: 3
|
||
context_size: 12.4 KB
|
||
result_metrics:
|
||
output: stdout
|
||
input_tokens: 1524
|
||
output_tokens: 842
|
||
duration_s: 1.8
|
||
cost: "$0.0021"
|
||
tool_calls: 0
|
||
timing:
|
||
duration_ms: 1800
|
||
messages:
|
||
- level: ok
|
||
text: Summary generated
|
||
```
|
||
|
||
Running an actor with a custom temperature and skill attachment:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--temperature</span> 0.2 <span style="color: cyan;">--skill</span> local/code-analysis \
|
||
local/reviewer <span style="color: #66cc66;">"Review the auth module for security issues"</span>
|
||
|
||
╭─ Actor Run ─────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> agent │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Temperature:</span> 0.2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skill:</span> local/code-analysis │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Response ────────────────────────────────────────────────────────╮
|
||
│ I identified 3 potential security concerns in the auth module: │
|
||
│ │
|
||
│ 1. <span style="color: yellow; font-weight: 600;">Token expiry not validated</span> in `validate_session()` at │
|
||
│ src/auth/session.py:42. The JWT expiry claim is decoded but │
|
||
│ not checked against current time. │
|
||
│ │
|
||
│ 2. <span style="color: yellow; font-weight: 600;">Missing rate limiting</span> on the `/auth/refresh` endpoint. │
|
||
│ An attacker could brute-force refresh tokens. │
|
||
│ │
|
||
│ 3. <span style="color: #66cc66; font-weight: 600;">Low severity:</span> Password hashing uses bcrypt with cost=10. │
|
||
│ Consider cost=12 for production deployments. │
|
||
╰───────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Usage ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 2,840 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 4.2s │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cost:</span> $0.009 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 6 │
|
||
╰──────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor run completed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor run --temperature 0.2 --skill local/code-analysis \
|
||
local/reviewer "Review the auth module for security issues"
|
||
|
||
Actor Run
|
||
Actor: local/reviewer
|
||
Type: agent
|
||
Temperature: 0.2
|
||
Skill: local/code-analysis
|
||
|
||
Response
|
||
I identified 3 potential security concerns in the auth module:
|
||
|
||
1. Token expiry not validated in validate_session() at
|
||
src/auth/session.py:42. The JWT expiry claim is decoded but
|
||
not checked against current time.
|
||
|
||
2. Missing rate limiting on the /auth/refresh endpoint.
|
||
An attacker could brute-force refresh tokens.
|
||
|
||
3. Low severity: Password hashing uses bcrypt with cost=10.
|
||
Consider cost=12 for production deployments.
|
||
|
||
Usage
|
||
Tokens: 2,840
|
||
Duration: 4.2s
|
||
Cost: $0.009
|
||
Tool Calls: 6
|
||
|
||
[OK] Actor run completed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor run --temperature 0.2 --skill local/code-analysis local/reviewer \"Review the auth module for security issues\"",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_run": {
|
||
"actor": "local/reviewer",
|
||
"type": "agent",
|
||
"temperature": 0.2,
|
||
"skill": "local/code-analysis"
|
||
},
|
||
"response": {
|
||
"text": "I identified 3 potential security concerns in the auth module:\n\n1. Token expiry not validated in validate_session() at src/auth/session.py:42. The JWT expiry claim is decoded but not checked against current time.\n\n2. Missing rate limiting on the /auth/refresh endpoint. An attacker could brute-force refresh tokens.\n\n3. Low severity: Password hashing uses bcrypt with cost=10. Consider cost=12 for production deployments.",
|
||
"issues_found": 3
|
||
},
|
||
"usage": {
|
||
"tokens": 2840,
|
||
"duration_s": 4.2,
|
||
"cost": "$0.009",
|
||
"tool_calls": 6
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 4200
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Actor run completed" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: >-
|
||
agents actor run --temperature 0.2 --skill local/code-analysis
|
||
local/reviewer "Review the auth module for security issues"
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_run:
|
||
actor: local/reviewer
|
||
type: agent
|
||
temperature: 0.2
|
||
skill: local/code-analysis
|
||
response:
|
||
text: >-
|
||
I identified 3 potential security concerns in the auth module:
|
||
|
||
1. Token expiry not validated in validate_session() at
|
||
src/auth/session.py:42. The JWT expiry claim is decoded but
|
||
not checked against current time.
|
||
|
||
2. Missing rate limiting on the /auth/refresh endpoint.
|
||
An attacker could brute-force refresh tokens.
|
||
|
||
3. Low severity: Password hashing uses bcrypt with cost=10.
|
||
Consider cost=12 for production deployments.
|
||
issues_found: 3
|
||
usage:
|
||
tokens: 2840
|
||
duration_s: 4.2
|
||
cost: "$0.009"
|
||
tool_calls: 6
|
||
timing:
|
||
duration_ms: 4200
|
||
messages:
|
||
- level: ok
|
||
text: Actor run completed
|
||
```
|
||
|
||
Saving actor output to a file:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor run <span style="color: cyan;">--output</span> review.md local/reviewer <span style="color: #66cc66;">"Write a code review report"</span>
|
||
|
||
╭─ Actor Run ───────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Actor:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> review.md │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tokens:</span> 4,120 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 6.8s │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Output written to review.md (2.4 KB)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor run --output review.md local/reviewer "Write a code review report"
|
||
|
||
Actor Run
|
||
Actor: local/reviewer
|
||
Output: review.md
|
||
Tokens: 4,120
|
||
Duration: 6.8s
|
||
|
||
[OK] Output written to review.md (2.4 KB)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor run --output review.md local/reviewer \"Write a code review report\"",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_run": {
|
||
"actor": "local/reviewer",
|
||
"output": "review.md",
|
||
"tokens": 4120,
|
||
"duration_s": 6.8
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 6800
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Output written to review.md (2.4 KB)" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor run --output review.md local/reviewer "Write a code review report"
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_run:
|
||
actor: local/reviewer
|
||
output: review.md
|
||
tokens: 4120
|
||
duration_s: 6.8
|
||
timing:
|
||
duration_ms: 6800
|
||
messages:
|
||
- level: ok
|
||
text: Output written to review.md (2.4 KB)
|
||
```
|
||
|
||
##### agents actor add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Add a new actor configuration, or replace an existing one with `--update`. The actor is fully defined by the YAML configuration file specified with `--config`. If a local actor with the same name already exists, the command fails unless the `--update` flag is provided, which replaces the existing actor.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Actor config file (required). The file must fully define the actor, including the `name` field which determines the actor's registered name.
|
||
- `--update`: Replace an existing local actor with the same name. Without this flag, attempting to add an actor whose name is already registered will fail.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml
|
||
|
||
╭─ Actor Added ────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
|
||
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
|
||
│ <span style="color: yellow; font-weight: 600;">Default:</span> yes │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> graph │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Config ─────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> ./actors/reviewer.yaml │
|
||
│ <span style="color: magenta; font-weight: 600;">Hash:</span> 8b3f3d2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Options:</span> 4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Nodes:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Edges:</span> 4 │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Capabilities ───────╮
|
||
│ - code review │
|
||
│ - diff summarization │
|
||
│ - lint guidance │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Tools ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Safe</span> │
|
||
│ <span style="opacity: 0.7;">──────────── ───────── ────</span> │
|
||
│ read_file yes yes │
|
||
│ search_files yes yes │
|
||
│ git_diff yes yes │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor added
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor add --config ./actors/reviewer.yaml
|
||
|
||
Actor Added
|
||
Name: local/reviewer
|
||
Provider: openai
|
||
Model: gpt-4
|
||
Default: yes
|
||
Unsafe: no
|
||
Type: graph
|
||
|
||
Config
|
||
Path: ./actors/reviewer.yaml
|
||
Hash: 8b3f3d2
|
||
Options: 4
|
||
Nodes: 3
|
||
Edges: 4
|
||
|
||
Capabilities
|
||
- code review
|
||
- diff summarization
|
||
- lint guidance
|
||
|
||
Tools
|
||
Tool Read-Only Safe
|
||
------------ --------- ----
|
||
read_file yes yes
|
||
search_files yes yes
|
||
git_diff yes yes
|
||
|
||
[OK] Actor added
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor add --config ./actors/reviewer.yaml",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_added": {
|
||
"name": "local/reviewer",
|
||
"provider": "openai",
|
||
"model": "gpt-4",
|
||
"default": true,
|
||
"unsafe": false,
|
||
"type": "graph"
|
||
},
|
||
"config": {
|
||
"path": "./actors/reviewer.yaml",
|
||
"hash": "8b3f3d2",
|
||
"options": 4,
|
||
"nodes": 3,
|
||
"edges": 4
|
||
},
|
||
"capabilities": [
|
||
"code review",
|
||
"diff summarization",
|
||
"lint guidance"
|
||
],
|
||
"tools": [
|
||
{ "tool": "read_file", "read_only": true, "safe": true },
|
||
{ "tool": "search_files", "read_only": true, "safe": true },
|
||
{ "tool": "git_diff", "read_only": true, "safe": true }
|
||
]
|
||
},
|
||
"timing": {
|
||
"duration_ms": 95
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Actor added" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor add --config ./actors/reviewer.yaml
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_added:
|
||
name: local/reviewer
|
||
provider: openai
|
||
model: gpt-4
|
||
default: true
|
||
unsafe: false
|
||
type: graph
|
||
config:
|
||
path: ./actors/reviewer.yaml
|
||
hash: 8b3f3d2
|
||
options: 4
|
||
nodes: 3
|
||
edges: 4
|
||
capabilities:
|
||
- code review
|
||
- diff summarization
|
||
- lint guidance
|
||
tools:
|
||
- tool: read_file
|
||
read_only: true
|
||
safe: true
|
||
- tool: search_files
|
||
read_only: true
|
||
safe: true
|
||
- tool: git_diff
|
||
read_only: true
|
||
safe: true
|
||
timing:
|
||
duration_ms: 95
|
||
messages:
|
||
- level: ok
|
||
text: Actor added
|
||
```
|
||
|
||
Attempting to register an actor that already exists (without `--update`):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml
|
||
|
||
╭─ Error ─────────────────────────────────────────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">Actor already exists:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Registered:</span> 2026-02-07 14:22 │
|
||
│ <span style="opacity: 0.7;">Use <span style="color: cyan;">--update</span> to replace the existing actor definition.</span> │
|
||
╰─────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Actor already registered — use --update to replace
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor add --config ./actors/reviewer.yaml
|
||
|
||
Error
|
||
Actor already exists: local/reviewer
|
||
Registered: 2026-02-07 14:22
|
||
Use --update to replace the existing actor definition.
|
||
|
||
[ERROR] Actor already registered -- use --update to replace
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor add --config ./actors/reviewer.yaml",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"error": {
|
||
"message": "Actor already exists: local/reviewer",
|
||
"registered": "2026-02-07T14:22:00Z",
|
||
"hint": "Use --update to replace the existing actor definition."
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 42
|
||
},
|
||
"messages": [
|
||
{ "level": "error", "text": "Actor already registered -- use --update to replace" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor add --config ./actors/reviewer.yaml
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
error:
|
||
message: "Actor already exists: local/reviewer"
|
||
registered: "2026-02-07T14:22:00Z"
|
||
hint: Use --update to replace the existing actor definition.
|
||
timing:
|
||
duration_ms: 42
|
||
messages:
|
||
- level: error
|
||
text: Actor already registered -- use --update to replace
|
||
```
|
||
|
||
Updating an existing actor with `--update`:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor add <span style="color: cyan;">--config</span> ./actors/reviewer.yaml <span style="color: cyan;">--update</span>
|
||
|
||
╭─ Actor Updated ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> agent │
|
||
│ <span style="color: yellow; font-weight: 600;">Status:</span> updated │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Changes ────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> +1 (local/code-analysis) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Model:</span> unchanged │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Graph:</span> updated │
|
||
╰──────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor updated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor add --config ./actors/reviewer.yaml --update
|
||
|
||
Actor Updated
|
||
Name: local/reviewer
|
||
Type: agent
|
||
Status: updated
|
||
|
||
Changes
|
||
Skills: +1 (local/code-analysis)
|
||
Model: unchanged
|
||
Graph: updated
|
||
|
||
[OK] Actor updated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor add --config ./actors/reviewer.yaml --update",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_updated": {
|
||
"name": "local/reviewer",
|
||
"type": "agent",
|
||
"status": "updated"
|
||
},
|
||
"changes": {
|
||
"skills": "+1 (local/code-analysis)",
|
||
"model": "unchanged",
|
||
"graph": "updated"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 88
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Actor updated" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor add --config ./actors/reviewer.yaml --update
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_updated:
|
||
name: local/reviewer
|
||
type: agent
|
||
status: updated
|
||
changes:
|
||
skills: "+1 (local/code-analysis)"
|
||
model: unchanged
|
||
graph: updated
|
||
timing:
|
||
duration_ms: 88
|
||
messages:
|
||
- level: ok
|
||
text: Actor updated
|
||
```
|
||
|
||
##### agents actor remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor remove <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! warning "Destructive Operation"
|
||
Removes a custom actor registration. Active plans and actions referencing this actor will lose their actor binding. Check the **Impact** section in the output to verify no active plans or sessions are affected.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Actor name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor remove local/reviewer
|
||
|
||
╭─ Actor Removed ──────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
|
||
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Impact ───────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> 0 affected │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 affected │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actions Referencing:</span> 0 │
|
||
╰────────────────────────────────────────────╯
|
||
|
||
╭─ Cleanup ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> kept on disk │
|
||
│ <span style="color: yellow; font-weight: 600;">Contexts:</span> 1 orphaned │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor remove local/reviewer
|
||
|
||
Actor Removed
|
||
Name: local/reviewer
|
||
Provider: openai
|
||
Model: gpt-4
|
||
|
||
Impact
|
||
Sessions: 0 affected
|
||
Active Plans: 0 affected
|
||
Actions Referencing: 0
|
||
|
||
Cleanup
|
||
Config: kept on disk
|
||
Contexts: 1 orphaned
|
||
|
||
[OK] Actor removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor remove local/reviewer",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_removed": {
|
||
"name": "local/reviewer",
|
||
"provider": "openai",
|
||
"model": "gpt-4"
|
||
},
|
||
"impact": {
|
||
"sessions": 0,
|
||
"active_plans": 0,
|
||
"actions_referencing": 0
|
||
},
|
||
"cleanup": {
|
||
"config": "kept on disk",
|
||
"contexts": "1 orphaned"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 65
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Actor removed" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor remove local/reviewer
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_removed:
|
||
name: local/reviewer
|
||
provider: openai
|
||
model: gpt-4
|
||
impact:
|
||
sessions: 0
|
||
active_plans: 0
|
||
actions_referencing: 0
|
||
cleanup:
|
||
config: kept on disk
|
||
contexts: 1 orphaned
|
||
timing:
|
||
duration_ms: 65
|
||
messages:
|
||
- level: ok
|
||
text: Actor removed
|
||
```
|
||
|
||
##### agents actor list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor list</code></pre></div>
|
||
|
||
**Purpose**
|
||
List all actors.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor list
|
||
|
||
╭─ Actors ──────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Provider</span> <span style="color: cyan; font-weight: 600;">Model</span> <span style="color: cyan; font-weight: 600;">Default</span> <span style="color: cyan; font-weight: 600;">Built-in</span> <span style="color: cyan; font-weight: 600;">Unsafe</span> │
|
||
│ <span style="opacity: 0.7;">────────────── ───────── ────────── ─────── ──────── ──────</span> │
|
||
│ local/reviewer openai gpt-4 ✓ no │
|
||
│ openai/gpt-4 openai gpt-4 ✓ no │
|
||
│ anthropic/3.5 anthropic claude-3.5 ✓ no │
|
||
╰───────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Built-in:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Providers Used:</span> 2 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 actors listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor list
|
||
|
||
Actors
|
||
Name Provider Model Default Built-in Unsafe
|
||
-------------- --------- ---------- ------- -------- ------
|
||
local/reviewer openai gpt-4 yes no
|
||
openai/gpt-4 openai gpt-4 yes no
|
||
anthropic/3.5 anthropic claude-3.5 yes no
|
||
|
||
Summary
|
||
Total: 3
|
||
Built-in: 2
|
||
Custom: 1
|
||
Unsafe: 0
|
||
Providers Used: 2
|
||
|
||
[OK] 3 actors listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actors": [
|
||
{
|
||
"name": "local/reviewer",
|
||
"provider": "openai",
|
||
"model": "gpt-4",
|
||
"default": true,
|
||
"builtin": false,
|
||
"unsafe": false
|
||
},
|
||
{
|
||
"name": "openai/gpt-4",
|
||
"provider": "openai",
|
||
"model": "gpt-4",
|
||
"default": false,
|
||
"builtin": true,
|
||
"unsafe": false
|
||
},
|
||
{
|
||
"name": "anthropic/3.5",
|
||
"provider": "anthropic",
|
||
"model": "claude-3.5",
|
||
"default": false,
|
||
"builtin": true,
|
||
"unsafe": false
|
||
}
|
||
],
|
||
"summary": {
|
||
"total": 3,
|
||
"builtin": 2,
|
||
"custom": 1,
|
||
"unsafe": 0,
|
||
"providers_used": 2
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 55
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "3 actors listed" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actors:
|
||
- name: local/reviewer
|
||
provider: openai
|
||
model: gpt-4
|
||
default: true
|
||
builtin: false
|
||
unsafe: false
|
||
- name: openai/gpt-4
|
||
provider: openai
|
||
model: gpt-4
|
||
default: false
|
||
builtin: true
|
||
unsafe: false
|
||
- name: anthropic/3.5
|
||
provider: anthropic
|
||
model: claude-3.5
|
||
default: false
|
||
builtin: true
|
||
unsafe: false
|
||
summary:
|
||
total: 3
|
||
builtin: 2
|
||
custom: 1
|
||
unsafe: 0
|
||
providers_used: 2
|
||
timing:
|
||
duration_ms: 55
|
||
messages:
|
||
- level: ok
|
||
text: 3 actors listed
|
||
```
|
||
|
||
##### agents actor show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show details for a single actor.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Actor name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor show local/reviewer
|
||
|
||
╭─ Actor Details ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/reviewer │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Provider:</span> openai │
|
||
│ <span style="color: magenta; font-weight: 600;">Model:</span> gpt-4 │
|
||
│ <span style="color: yellow; font-weight: 600;">Default:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Built-in:</span> no │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> graph │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:35 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 12:40 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Config:</span> ./actors/reviewer.yaml │
|
||
│ <span style="color: magenta; font-weight: 600;">Config Hash:</span> 9c4e2a1 │
|
||
╰────────────────────────────────────╯
|
||
|
||
╭─ Options ──────────╮
|
||
│ - temperature: 0.2 │
|
||
│ - max_tokens: 2048 │
|
||
│ - top_p: 1.0 │
|
||
╰────────────────────╯
|
||
|
||
╭─ Graph Structure ─╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Nodes:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Edges:</span> 4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Entry:</span> analyze │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Exit:</span> report │
|
||
╰───────────────────╯
|
||
|
||
╭─ Tools ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Safe</span> │
|
||
│ <span style="opacity: 0.7;">──────────── ───────── ────</span> │
|
||
│ read_file yes yes │
|
||
│ search_files yes yes │
|
||
│ git_diff yes yes │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Access ────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">Unsafe:</span> no │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Filesystem:</span> allowed │
|
||
│ <span style="color: yellow; font-weight: 600;">Network:</span> restricted │
|
||
╰─────────────────────╯
|
||
|
||
╭─ Usage ─────────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Referenced by Actions:</span> 1 (local/code-coverage) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active in Sessions:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Runs:</span> 14 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Avg Cost/Run:</span> $0.0032 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Actor loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor show local/reviewer
|
||
|
||
Actor Details
|
||
Name: local/reviewer
|
||
Provider: openai
|
||
Model: gpt-4
|
||
Default: yes
|
||
Built-in: no
|
||
Unsafe: no
|
||
Type: graph
|
||
Created: 2026-02-08 12:35
|
||
Updated: 2026-02-08 12:40
|
||
Config: ./actors/reviewer.yaml
|
||
Config Hash: 9c4e2a1
|
||
|
||
Options
|
||
- temperature: 0.2
|
||
- max_tokens: 2048
|
||
- top_p: 1.0
|
||
|
||
Graph Structure
|
||
Nodes: 3
|
||
Edges: 4
|
||
Entry: analyze
|
||
Exit: report
|
||
|
||
Tools
|
||
Tool Read-Only Safe
|
||
------------ --------- ----
|
||
read_file yes yes
|
||
search_files yes yes
|
||
git_diff yes yes
|
||
|
||
Access
|
||
Unsafe: no
|
||
Filesystem: allowed
|
||
Network: restricted
|
||
|
||
Usage
|
||
Referenced by Actions: 1 (local/code-coverage)
|
||
Active in Sessions: 0
|
||
Total Runs: 14
|
||
Avg Cost/Run: $0.0032
|
||
|
||
[OK] Actor loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor show local/reviewer",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actor_details": {
|
||
"name": "local/reviewer",
|
||
"provider": "openai",
|
||
"model": "gpt-4",
|
||
"default": true,
|
||
"builtin": false,
|
||
"unsafe": false,
|
||
"type": "graph",
|
||
"created": "2026-02-08T12:35:00Z",
|
||
"updated": "2026-02-08T12:40:00Z",
|
||
"config": "./actors/reviewer.yaml",
|
||
"config_hash": "9c4e2a1"
|
||
},
|
||
"options": {
|
||
"temperature": 0.2,
|
||
"max_tokens": 2048,
|
||
"top_p": 1.0
|
||
},
|
||
"graph_structure": {
|
||
"nodes": 3,
|
||
"edges": 4,
|
||
"entry": "analyze",
|
||
"exit": "report"
|
||
},
|
||
"tools": [
|
||
{ "tool": "read_file", "read_only": true, "safe": true },
|
||
{ "tool": "search_files", "read_only": true, "safe": true },
|
||
{ "tool": "git_diff", "read_only": true, "safe": true }
|
||
],
|
||
"access": {
|
||
"unsafe": false,
|
||
"filesystem": "allowed",
|
||
"network": "restricted"
|
||
},
|
||
"usage": {
|
||
"referenced_by_actions": "1 (local/code-coverage)",
|
||
"active_in_sessions": 0,
|
||
"total_runs": 14,
|
||
"avg_cost_per_run": "$0.0032"
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 78
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Actor loaded" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor show local/reviewer
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actor_details:
|
||
name: local/reviewer
|
||
provider: openai
|
||
model: gpt-4
|
||
default: true
|
||
builtin: false
|
||
unsafe: false
|
||
type: graph
|
||
created: "2026-02-08T12:35:00Z"
|
||
updated: "2026-02-08T12:40:00Z"
|
||
config: ./actors/reviewer.yaml
|
||
config_hash: 9c4e2a1
|
||
options:
|
||
temperature: 0.2
|
||
max_tokens: 2048
|
||
top_p: 1.0
|
||
graph_structure:
|
||
nodes: 3
|
||
edges: 4
|
||
entry: analyze
|
||
exit: report
|
||
tools:
|
||
- tool: read_file
|
||
read_only: true
|
||
safe: true
|
||
- tool: search_files
|
||
read_only: true
|
||
safe: true
|
||
- tool: git_diff
|
||
read_only: true
|
||
safe: true
|
||
access:
|
||
unsafe: false
|
||
filesystem: allowed
|
||
network: restricted
|
||
usage:
|
||
referenced_by_actions: 1 (local/code-coverage)
|
||
active_in_sessions: 0
|
||
total_runs: 14
|
||
avg_cost_per_run: "$0.0032"
|
||
timing:
|
||
duration_ms: 78
|
||
messages:
|
||
- level: ok
|
||
text: Actor loaded
|
||
```
|
||
|
||
##### agents actor context
|
||
|
||
**Purpose**
|
||
Manage manual context for actor runs. These commands mirror the legacy context behavior but are scoped to an actor context name.
|
||
|
||
###### agents actor context remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] (<span style="color: magenta;"><span style="color: cyan;">--all</span>|<span style="color: yellow;">-a</span>|<span style="color: #66cc66;"><NAME></span></span>)</code></pre></div>
|
||
|
||
!!! warning "Context Data Loss"
|
||
Remove files or directories from an actor context. Use `--all` to clear all contexts at once. Context data is not recoverable after removal.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Context name (positional argument). Use --all/-a to target all contexts.
|
||
- `--all, -a`: Target all contexts instead of a named one.
|
||
- `--yes, -y`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context remove docs
|
||
|
||
╭─ Context Removed ───────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> removed │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Stats ───────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Remaining Size:</span> 48 KB │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 13:06 │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context updated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context remove docs
|
||
|
||
Context Removed
|
||
Context: docs
|
||
Status: removed
|
||
|
||
Stats
|
||
Remaining Size: 48 KB
|
||
Updated: 2026-02-08 13:06
|
||
|
||
[OK] Context updated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context remove docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_removed": {
|
||
"context": "docs",
|
||
"status": "removed"
|
||
},
|
||
"stats": {
|
||
"remaining_size_kb": 48,
|
||
"updated": "2026-02-08T13:06:00Z"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 65 },
|
||
"messages": [{ "level": "ok", "text": "Context updated" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context remove docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_removed:
|
||
context: docs
|
||
status: removed
|
||
stats:
|
||
remaining_size_kb: 48
|
||
updated: "2026-02-08T13:06:00Z"
|
||
timing:
|
||
duration_ms: 65
|
||
messages:
|
||
- level: ok
|
||
text: Context updated
|
||
```
|
||
|
||
###### agents actor context list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context list [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List files stored in an actor context.
|
||
|
||
**Arguments**
|
||
|
||
- `[REGEX]`: Optional regex filter for context names.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context list docs
|
||
|
||
╭─ Context Files ──────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Size</span> <span style="color: cyan; font-weight: 600;">Added</span> │
|
||
│ <span style="opacity: 0.7;">──────────────── ──── ─────── ──────────</span> │
|
||
│ README.md file 4.2 KB 02-08 12:10 │
|
||
│ docs/overview.md file 12.8 KB 02-08 12:10 │
|
||
│ docs/cli.md file 9.5 KB 02-08 12:10 │
|
||
╰──────────────────────────────────────────────╯
|
||
|
||
╭─ Stats ───────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total Files:</span> 3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Total Size:</span> 26.5 KB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimated Tokens:</span> ~6,600 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> Markdown │
|
||
╰───────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 files listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context list docs
|
||
|
||
Context Files
|
||
Name Type Size Added
|
||
---------------- ---- ------- ----------
|
||
README.md file 4.2 KB 02-08 12:10
|
||
docs/overview.md file 12.8 KB 02-08 12:10
|
||
docs/cli.md file 9.5 KB 02-08 12:10
|
||
|
||
Stats
|
||
Total Files: 3
|
||
Total Size: 26.5 KB
|
||
Estimated Tokens: ~6,600
|
||
Languages: Markdown
|
||
|
||
[OK] 3 files listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context list docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_files": [
|
||
{ "name": "README.md", "type": "file", "size_kb": 4.2, "added": "2026-02-08T12:10:00Z" },
|
||
{ "name": "docs/overview.md", "type": "file", "size_kb": 12.8, "added": "2026-02-08T12:10:00Z" },
|
||
{ "name": "docs/cli.md", "type": "file", "size_kb": 9.5, "added": "2026-02-08T12:10:00Z" }
|
||
],
|
||
"stats": {
|
||
"total_files": 3,
|
||
"total_size_kb": 26.5,
|
||
"estimated_tokens": 6600,
|
||
"languages": ["Markdown"]
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 35 },
|
||
"messages": [{ "level": "ok", "text": "3 files listed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context list docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_files:
|
||
- name: README.md
|
||
type: file
|
||
size_kb: 4.2
|
||
added: "2026-02-08T12:10:00Z"
|
||
- name: docs/overview.md
|
||
type: file
|
||
size_kb: 12.8
|
||
added: "2026-02-08T12:10:00Z"
|
||
- name: docs/cli.md
|
||
type: file
|
||
size_kb: 9.5
|
||
added: "2026-02-08T12:10:00Z"
|
||
stats:
|
||
total_files: 3
|
||
total_size_kb: 26.5
|
||
estimated_tokens: 6600
|
||
languages:
|
||
- Markdown
|
||
timing:
|
||
duration_ms: 35
|
||
messages:
|
||
- level: ok
|
||
text: 3 files listed
|
||
```
|
||
|
||
###### agents actor context show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show content of a file in an actor context.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Context name (positional argument).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context show docs
|
||
|
||
╭─ Context Summary ───────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Files:</span> 3 │
|
||
│ <span style="color: yellow; font-weight: 600;">Total Size:</span> 26.5 KB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimated Tokens:</span> ~6,600 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Created:</span> 2026-02-08 12:10 │
|
||
╰─────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context displayed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context show docs
|
||
|
||
Context Summary
|
||
Context: docs
|
||
Files: 3
|
||
Total Size: 26.5 KB
|
||
Estimated Tokens: ~6,600
|
||
Created: 2026-02-08 12:10
|
||
|
||
[OK] Context displayed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context show docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_summary": {
|
||
"context": "docs",
|
||
"files": 3,
|
||
"total_size_kb": 26.5,
|
||
"estimated_tokens": 6600,
|
||
"created": "2026-02-08T12:10:00Z"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 45 },
|
||
"messages": [{ "level": "ok", "text": "Context displayed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context show docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_summary:
|
||
context: docs
|
||
files: 3
|
||
total_size_kb: 26.5
|
||
estimated_tokens: 6600
|
||
created: "2026-02-08T12:10:00Z"
|
||
timing:
|
||
duration_ms: 45
|
||
messages:
|
||
- level: ok
|
||
text: Context displayed
|
||
```
|
||
|
||
###### agents actor context export
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context export (<span style="color: magenta;"><span style="color: cyan;">--output</span>|<span style="color: yellow;">-o</span></span>) <span style="color: #66cc66;"><FILE></span> <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Export a context as JSON.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Context name (positional argument).
|
||
- `--output/-o FILE`: Output file path (required).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context export <span style="color: cyan;">--output</span> /tmp/docs-context.json docs
|
||
|
||
╭─ Context Export ───────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Output:</span> /tmp/docs-context.json │
|
||
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Size:</span> 48 KB │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Integrity ──────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Checksum:</span> sha256:19b2...a7d0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Compressed:</span> no │
|
||
╰──────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Export completed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context export --output /tmp/docs-context.json docs
|
||
|
||
Context Export
|
||
Context: docs
|
||
Output: /tmp/docs-context.json
|
||
Items: 12
|
||
Size: 48 KB
|
||
|
||
Integrity
|
||
Checksum: sha256:19b2...a7d0
|
||
Compressed: no
|
||
|
||
[OK] Export completed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context export --output /tmp/docs-context.json docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_export": {
|
||
"context": "docs",
|
||
"output": "/tmp/docs-context.json",
|
||
"items": 12,
|
||
"size_kb": 48
|
||
},
|
||
"integrity": {
|
||
"checksum": "sha256:19b2...a7d0",
|
||
"compressed": false
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 180 },
|
||
"messages": [{ "level": "ok", "text": "Export completed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context export --output /tmp/docs-context.json docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_export:
|
||
context: docs
|
||
output: /tmp/docs-context.json
|
||
items: 12
|
||
size_kb: 48
|
||
integrity:
|
||
checksum: "sha256:19b2...a7d0"
|
||
compressed: false
|
||
timing:
|
||
duration_ms: 180
|
||
messages:
|
||
- level: ok
|
||
text: Export completed
|
||
```
|
||
|
||
###### agents actor context import
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context import [<span style="color: cyan;">--update</span>] (<span style="color: magenta;"><span style="color: cyan;">--input</span>|<span style="color: yellow;">-i</span></span>) <span style="color: #66cc66;"><FILE></span> [<span style="color: #66cc66;"><NAME></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Import a context from JSON.
|
||
|
||
**Arguments**
|
||
|
||
- `[NAME]`: Context name (optional, inferred from file if omitted).
|
||
- `--input/-i FILE`: Input JSON file (required).
|
||
- `--update`: Replace an existing context with the same name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context import <span style="color: cyan;">--input</span> /tmp/docs-context.json docs
|
||
|
||
╭─ Context Import ──────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input:</span> /tmp/docs-context.json │
|
||
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Merge ───────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> replace │
|
||
│ <span style="color: yellow; font-weight: 600;">Conflicts:</span> 0 │
|
||
╰───────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Import completed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context import --input /tmp/docs-context.json docs
|
||
|
||
Context Import
|
||
Context: docs
|
||
Input: /tmp/docs-context.json
|
||
Items: 12
|
||
|
||
Merge
|
||
Strategy: replace
|
||
Conflicts: 0
|
||
|
||
[OK] Import completed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context import --input /tmp/docs-context.json docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_import": {
|
||
"context": "docs",
|
||
"input": "/tmp/docs-context.json",
|
||
"items": 12
|
||
},
|
||
"merge": {
|
||
"strategy": "replace",
|
||
"conflicts": 0
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 210 },
|
||
"messages": [{ "level": "ok", "text": "Import completed" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context import --input /tmp/docs-context.json docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_import:
|
||
context: docs
|
||
input: /tmp/docs-context.json
|
||
items: 12
|
||
merge:
|
||
strategy: replace
|
||
conflicts: 0
|
||
timing:
|
||
duration_ms: 210
|
||
messages:
|
||
- level: ok
|
||
text: Import completed
|
||
```
|
||
|
||
###### agents actor context clear
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> actor context clear [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] (<span style="color: magenta;"><span style="color: cyan;">--all</span>|<span style="color: yellow;">-a</span>|<span style="color: #66cc66;"><NAME></span></span>)</code></pre></div>
|
||
|
||
**Purpose**
|
||
Clear all files from a context but keep the context itself.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Context name (positional argument). Use --all/-a to target all contexts.
|
||
- `--all, -a`: Target all contexts instead of a named one.
|
||
- `--yes, -y`: Skip confirmation.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> actor context clear docs
|
||
|
||
Clear context docs? [y/N]: y
|
||
|
||
╭─ Context Cleared ────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Context:</span> docs │
|
||
│ <span style="color: yellow; font-weight: 600;">Items:</span> 12 removed │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Storage:</span> 48 KB freed │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Retention ────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Context:</span> preserved │
|
||
│ <span style="color: yellow; font-weight: 600;">Files:</span> removed │
|
||
╰────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Context cleared
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents actor context clear docs
|
||
|
||
Clear context docs? [y/N]: y
|
||
|
||
Context Cleared
|
||
Context: docs
|
||
Items: 12 removed
|
||
Storage: 48 KB freed
|
||
|
||
Retention
|
||
Context: preserved
|
||
Files: removed
|
||
|
||
[OK] Context cleared
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "agents actor context clear docs",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"context_cleared": {
|
||
"context": "docs",
|
||
"items": "12 removed",
|
||
"storage": "48 KB freed"
|
||
},
|
||
"retention": {
|
||
"context": "preserved",
|
||
"files": "removed"
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 85 },
|
||
"messages": [{ "level": "ok", "text": "Context cleared" }]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: agents actor context clear docs
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
context_cleared:
|
||
context: docs
|
||
items: 12 removed
|
||
storage: 48 KB freed
|
||
retention:
|
||
context: preserved
|
||
files: removed
|
||
timing:
|
||
duration_ms: 85
|
||
messages:
|
||
- level: ok
|
||
text: Context cleared
|
||
```
|
||
|
||
#### agents skill
|
||
|
||
!!! info "Purpose"
|
||
|
||
Manage skills — reusable, namespaced collections of tools. Skills are defined in their own YAML configuration files and registered in the system through these commands. Once registered, skills can be referenced by actors.
|
||
|
||
##### agents skill add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new skill. The skill is fully defined by the YAML configuration file specified with `--config`. If a skill with the same name already exists, the command fails unless the `--update` flag is provided, which allows overwriting the existing registration with the new configuration.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Path to the skill YAML configuration file (required). The file must fully define the skill, including the `name` field which determines the skill's registered name.
|
||
- `--update`: Allow overwriting an existing skill registration. Without this flag, attempting to add a skill whose name is already registered will fail.
|
||
|
||
**Examples**
|
||
|
||
Registering a new skill:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit.yaml
|
||
|
||
╭─ Skill Registered ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./skills/devops-toolkit.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 13:10 │
|
||
╰───────────────────────────────────────────╯
|
||
|
||
╭─ Includes ────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/file-ops</span> (registered) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/git-ops</span> (registered) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/github</span> (registered) │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Tool Sources ────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Count</span> <span style="color: cyan; font-weight: 600;">Details</span> │
|
||
│ <span style="opacity: 0.7;">───────────── ───── ───────────────────</span> │
|
||
│ builtin 14 file, dir, git, shell │
|
||
│ mcp 6 github (4), linear (2) │
|
||
│ agent_skill 2 deploy, code-review │
|
||
│ custom 1 run_migrations │
|
||
│ <span style="opacity: 0.7;">───────────── ───── ───────────────────</span> │
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 23 │
|
||
╰───────────────────────────────────────────────╯
|
||
|
||
╭─ MCP Servers ────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">linear:</span> validated (2 tools) │
|
||
╰──────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill registered with 23 tools
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill add --config ./skills/devops-toolkit.yaml
|
||
|
||
Skill Registered
|
||
Name: local/devops-toolkit
|
||
Description: Full-stack development tools
|
||
Config: ./skills/devops-toolkit.yaml
|
||
Created: 2026-02-08 13:10
|
||
|
||
Includes
|
||
local/file-ops (registered)
|
||
local/git-ops (registered)
|
||
local/github (registered)
|
||
|
||
Tool Sources
|
||
Source Count Details
|
||
------------- ----- -------------------
|
||
builtin 14 file, dir, git, shell
|
||
mcp 6 github (4), linear (2)
|
||
agent_skill 2 deploy, code-review
|
||
custom 1 run_migrations
|
||
------------- ----- -------------------
|
||
Total: 23
|
||
|
||
MCP Servers
|
||
linear: validated (2 tools)
|
||
|
||
[OK] Skill registered with 23 tools
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill add --config ./skills/devops-toolkit.yaml",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"skill": {
|
||
"name": "local/devops-toolkit",
|
||
"description": "Full-stack development tools",
|
||
"config": "./skills/devops-toolkit.yaml",
|
||
"created": "2026-02-08T13:10:00Z"
|
||
},
|
||
"includes": [
|
||
{ "name": "local/file-ops", "status": "registered" },
|
||
{ "name": "local/git-ops", "status": "registered" },
|
||
{ "name": "local/github", "status": "registered" }
|
||
],
|
||
"tool_sources": [
|
||
{ "source": "builtin", "count": 14, "details": "file, dir, git, shell" },
|
||
{ "source": "mcp", "count": 6, "details": "github (4), linear (2)" },
|
||
{ "source": "agent_skill", "count": 2, "details": "deploy, code-review" },
|
||
{ "source": "custom", "count": 1, "details": "run_migrations" }
|
||
],
|
||
"total_tools": 23,
|
||
"mcp_servers": [
|
||
{ "name": "linear", "status": "validated", "tools": 2 }
|
||
]
|
||
},
|
||
"timing": {
|
||
"duration_ms": 150
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Skill registered with 23 tools" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill add --config ./skills/devops-toolkit.yaml
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
skill:
|
||
name: local/devops-toolkit
|
||
description: Full-stack development tools
|
||
config: ./skills/devops-toolkit.yaml
|
||
created: "2026-02-08T13:10:00Z"
|
||
includes:
|
||
- name: local/file-ops
|
||
status: registered
|
||
- name: local/git-ops
|
||
status: registered
|
||
- name: local/github
|
||
status: registered
|
||
tool_sources:
|
||
- source: builtin
|
||
count: 14
|
||
details: file, dir, git, shell
|
||
- source: mcp
|
||
count: 6
|
||
details: github (4), linear (2)
|
||
- source: agent_skill
|
||
count: 2
|
||
details: deploy, code-review
|
||
- source: custom
|
||
count: 1
|
||
details: run_migrations
|
||
total_tools: 23
|
||
mcp_servers:
|
||
- name: linear
|
||
status: validated
|
||
tools: 2
|
||
timing:
|
||
duration_ms: 150
|
||
messages:
|
||
- level: ok
|
||
text: Skill registered with 23 tools
|
||
```
|
||
|
||
Attempting to add a skill that already exists (without `--update`):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ Error:</span> Skill 'local/devops-toolkit' is already registered.
|
||
|
||
To overwrite the existing configuration, re-run with <span style="color: cyan;">--update</span>:
|
||
|
||
agents skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml <span style="color: cyan;">--update</span>
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill add --config ./skills/devops-toolkit-v2.yaml
|
||
|
||
Error: Skill 'local/devops-toolkit' is already registered.
|
||
|
||
To overwrite the existing configuration, re-run with --update:
|
||
|
||
agents skill add --config ./skills/devops-toolkit-v2.yaml --update
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill add --config ./skills/devops-toolkit-v2.yaml",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"skill_name": "local/devops-toolkit",
|
||
"reason": "already registered"
|
||
},
|
||
"timing": {
|
||
"duration_ms": 30
|
||
},
|
||
"messages": [
|
||
{ "level": "error", "text": "Skill 'local/devops-toolkit' is already registered." },
|
||
{ "level": "info", "text": "To overwrite the existing configuration, re-run with --update" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill add --config ./skills/devops-toolkit-v2.yaml
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
skill_name: local/devops-toolkit
|
||
reason: already registered
|
||
timing:
|
||
duration_ms: 30
|
||
messages:
|
||
- level: error
|
||
text: "Skill 'local/devops-toolkit' is already registered."
|
||
- level: info
|
||
text: To overwrite the existing configuration, re-run with --update
|
||
```
|
||
|
||
Updating an existing skill with `--update`:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill add <span style="color: cyan;">--config</span> ./skills/devops-toolkit-v2.yaml <span style="color: cyan;">--update</span>
|
||
|
||
╭─ Skill Updated ───────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 14:22 │
|
||
╰───────────────────────────────────────────╯
|
||
|
||
╭─ Changes ─────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Tools Added:</span> 2 │
|
||
│ <span style="color: yellow; font-weight: 600;">Tools Removed:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tools Modified:</span> 1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Includes Changed:</span> no │
|
||
│ <span style="color: #5599ff; font-weight: 600;">MCP Servers Changed:</span> no │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Affected Actors ─────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 2 actors reference this skill: │
|
||
│ - local/code-assistant │
|
||
│ - local/full-stack-assistant │
|
||
│ These actors will pick up changes on next use │
|
||
╰───────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill updated (23 → 25 tools)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill add --config ./skills/devops-toolkit-v2.yaml --update
|
||
|
||
Skill Updated
|
||
Name: local/devops-toolkit
|
||
Description: Full-stack development tools
|
||
Updated: 2026-02-08 14:22
|
||
|
||
Changes
|
||
Tools Added: 2
|
||
Tools Removed: 0
|
||
Tools Modified: 1
|
||
Includes Changed: no
|
||
MCP Servers Changed: no
|
||
|
||
Affected Actors
|
||
Warning: 2 actors reference this skill:
|
||
- local/code-assistant
|
||
- local/full-stack-assistant
|
||
These actors will pick up changes on next use
|
||
|
||
[OK] Skill updated (23 -> 25 tools)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill add --config ./skills/devops-toolkit-v2.yaml --update",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"skill": {
|
||
"name": "local/devops-toolkit",
|
||
"description": "Full-stack development tools",
|
||
"updated": "2026-02-08T14:22:00Z"
|
||
},
|
||
"changes": {
|
||
"tools_added": 2,
|
||
"tools_removed": 0,
|
||
"tools_modified": 1,
|
||
"includes_changed": false,
|
||
"mcp_servers_changed": false
|
||
},
|
||
"affected_actors": [
|
||
"local/code-assistant",
|
||
"local/full-stack-assistant"
|
||
],
|
||
"tool_count": {
|
||
"before": 23,
|
||
"after": 25
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 180
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Skill updated (23 -> 25 tools)" },
|
||
{ "level": "warn", "text": "2 actors reference this skill and will pick up changes on next use" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill add --config ./skills/devops-toolkit-v2.yaml --update
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
skill:
|
||
name: local/devops-toolkit
|
||
description: Full-stack development tools
|
||
updated: "2026-02-08T14:22:00Z"
|
||
changes:
|
||
tools_added: 2
|
||
tools_removed: 0
|
||
tools_modified: 1
|
||
includes_changed: false
|
||
mcp_servers_changed: false
|
||
affected_actors:
|
||
- local/code-assistant
|
||
- local/full-stack-assistant
|
||
tool_count:
|
||
before: 23
|
||
after: 25
|
||
timing:
|
||
duration_ms: 180
|
||
messages:
|
||
- level: ok
|
||
text: "Skill updated (23 -> 25 tools)"
|
||
- level: warn
|
||
text: 2 actors reference this skill and will pick up changes on next use
|
||
```
|
||
|
||
##### agents skill remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> skill remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! warning "Cascading Impact"
|
||
Removing a skill ==unregisters all tools== provided by that skill and closes any associated MCP server connections. Other skills that include this skill, and actors that reference it, will lose access to those tools.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Skill name to remove.
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill remove local/devops-toolkit
|
||
|
||
Remove skill local/devops-toolkit? [y/N]: y
|
||
|
||
╭─ Skill Removed ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
|
||
│ <span style="color: yellow; font-weight: 600;">Tools:</span> 23 removed from registry │
|
||
│ <span style="color: #5599ff; font-weight: 600;">MCP Servers:</span> 1 connection closed │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Dependency Check ─────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 1 skill includes this skill: │
|
||
│ - local/full-stack-dev (will lose devops tools) │
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> 2 actors reference this skill: │
|
||
│ - local/code-assistant │
|
||
│ - local/full-stack-assistant │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill remove local/devops-toolkit
|
||
|
||
Remove skill local/devops-toolkit? [y/N]: y
|
||
|
||
Skill Removed
|
||
Name: local/devops-toolkit
|
||
Tools: 23 removed from registry
|
||
MCP Servers: 1 connection closed
|
||
|
||
Dependency Check
|
||
Warning: 1 skill includes this skill:
|
||
- local/full-stack-dev (will lose devops tools)
|
||
Warning: 2 actors reference this skill:
|
||
- local/code-assistant
|
||
- local/full-stack-assistant
|
||
|
||
[OK] Skill removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill remove local/devops-toolkit",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"skill": {
|
||
"name": "local/devops-toolkit",
|
||
"tools_removed": 23,
|
||
"mcp_servers_closed": 1
|
||
},
|
||
"dependency_check": {
|
||
"including_skills": [
|
||
{ "name": "local/full-stack-dev", "impact": "will lose devops tools" }
|
||
],
|
||
"referencing_actors": [
|
||
"local/code-assistant",
|
||
"local/full-stack-assistant"
|
||
]
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 95
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Skill removed" },
|
||
{ "level": "warn", "text": "1 skill includes this skill" },
|
||
{ "level": "warn", "text": "2 actors reference this skill" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill remove local/devops-toolkit
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
skill:
|
||
name: local/devops-toolkit
|
||
tools_removed: 23
|
||
mcp_servers_closed: 1
|
||
dependency_check:
|
||
including_skills:
|
||
- name: local/full-stack-dev
|
||
impact: will lose devops tools
|
||
referencing_actors:
|
||
- local/code-assistant
|
||
- local/full-stack-assistant
|
||
timing:
|
||
duration_ms: 95
|
||
messages:
|
||
- level: ok
|
||
text: Skill removed
|
||
- level: warn
|
||
text: 1 skill includes this skill
|
||
- level: warn
|
||
text: 2 actors reference this skill
|
||
```
|
||
|
||
##### agents skill list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> skill list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--source</span> <span style="color: #66cc66;"><SOURCE></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List registered skills with optional filters.
|
||
|
||
**Arguments**
|
||
|
||
- `--namespace/-n NS`: Filter by namespace.
|
||
- `--source SOURCE`: Filter by tool source type (mcp, agent_skill, builtin, custom).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill list
|
||
|
||
╭─ Skills ────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Tools</span> <span style="color: cyan; font-weight: 600;">Includes</span> <span style="color: cyan; font-weight: 600;">Sources</span> │
|
||
│ <span style="opacity: 0.7;">────────────────────── ───── ──────── ──────────────────────</span> │
|
||
│ local/file-ops 9 0 builtin │
|
||
│ local/git-ops 4 0 builtin │
|
||
│ local/github 4 0 mcp │
|
||
│ local/devops-toolkit 23 3 builtin, mcp, custom │
|
||
│ local/full-stack-dev 25 4 builtin, mcp, custom │
|
||
╰─────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ─────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 5 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Local:</span> 5 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Server:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Tools:</span> 28 │
|
||
╰───────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 5 skills listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill list
|
||
|
||
Skills
|
||
Name Tools Includes Sources
|
||
---------------------- ----- -------- ----------------------
|
||
local/file-ops 9 0 builtin
|
||
local/git-ops 4 0 builtin
|
||
local/github 4 0 mcp
|
||
local/devops-toolkit 23 3 builtin, mcp, custom
|
||
local/full-stack-dev 25 4 builtin, mcp, custom
|
||
|
||
Summary
|
||
Total: 5
|
||
Local: 5
|
||
Server: 0
|
||
Total Tools: 28
|
||
|
||
[OK] 5 skills listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"skills": [
|
||
{ "name": "local/file-ops", "tools": 9, "includes": 0, "sources": ["builtin"] },
|
||
{ "name": "local/git-ops", "tools": 4, "includes": 0, "sources": ["builtin"] },
|
||
{ "name": "local/github", "tools": 4, "includes": 0, "sources": ["mcp"] },
|
||
{ "name": "local/devops-toolkit", "tools": 23, "includes": 3, "sources": ["builtin", "mcp", "custom"] },
|
||
{ "name": "local/full-stack-dev", "tools": 25, "includes": 4, "sources": ["builtin", "mcp", "custom"] }
|
||
],
|
||
"summary": {
|
||
"total": 5,
|
||
"local": 5,
|
||
"server": 0,
|
||
"total_tools": 28
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 45
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "5 skills listed" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
skills:
|
||
- name: local/file-ops
|
||
tools: 9
|
||
includes: 0
|
||
sources:
|
||
- builtin
|
||
- name: local/git-ops
|
||
tools: 4
|
||
includes: 0
|
||
sources:
|
||
- builtin
|
||
- name: local/github
|
||
tools: 4
|
||
includes: 0
|
||
sources:
|
||
- mcp
|
||
- name: local/devops-toolkit
|
||
tools: 23
|
||
includes: 3
|
||
sources:
|
||
- builtin
|
||
- mcp
|
||
- custom
|
||
- name: local/full-stack-dev
|
||
tools: 25
|
||
includes: 4
|
||
sources:
|
||
- builtin
|
||
- mcp
|
||
- custom
|
||
summary:
|
||
total: 5
|
||
local: 5
|
||
server: 0
|
||
total_tools: 28
|
||
timing:
|
||
duration_ms: 45
|
||
messages:
|
||
- level: ok
|
||
text: 5 skills listed
|
||
```
|
||
|
||
##### agents skill show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> skill show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show full details for a registered skill, including its includes, tool sources, and capability summary.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Skill name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill show local/devops-toolkit
|
||
|
||
╭─ Skill Details ──────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/devops-toolkit │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Full-stack development tools │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./skills/devops-toolkit.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 13:10 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Updated:</span> 2026-02-08 14:22 │
|
||
╰──────────────────────────────────────────────╯
|
||
|
||
╭─ Includes (3) ────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/file-ops</span> → 9 tools (builtin) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/git-ops</span> → 4 tools (builtin) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/github</span> → 4 tools (mcp) │
|
||
╰───────────────────────────────────────────╯
|
||
|
||
╭─ Direct Tools (6) ────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Writes</span> <span style="color: cyan; font-weight: 600;">Checkpoint</span> │
|
||
│ <span style="opacity: 0.7;">──────────────── ─────────── ────── ──────────</span> │
|
||
│ create_issue mcp:linear yes no │
|
||
│ list_issues mcp:linear no — │
|
||
│ deploy-to-staging agent_skill yes composite │
|
||
│ code-review agent_skill no — │
|
||
│ run_migrations custom yes transaction │
|
||
│ shell_execute builtin yes snapshot │
|
||
╰───────────────────────────────────────────────────────────╯
|
||
|
||
╭─ MCP Servers (1) ───────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">linear:</span> stdio, 2 tools, connected │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Capability Summary ──────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Tools:</span> 23 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 10 │
|
||
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 13 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> 10 │
|
||
│ <span style="color: yellow; font-weight: 600;">Has Side Effects:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Requires Approval:</span> 1 │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Referenced By ───────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> local/code-assistant │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> local/full-stack-dev │
|
||
╰───────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Skill loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill show local/devops-toolkit
|
||
|
||
Skill Details
|
||
Name: local/devops-toolkit
|
||
Description: Full-stack development tools
|
||
Config: ./skills/devops-toolkit.yaml
|
||
Created: 2026-02-08 13:10
|
||
Updated: 2026-02-08 14:22
|
||
|
||
Includes (3)
|
||
local/file-ops -> 9 tools (builtin)
|
||
local/git-ops -> 4 tools (builtin)
|
||
local/github -> 4 tools (mcp)
|
||
|
||
Direct Tools (6)
|
||
Name Source Writes Checkpoint
|
||
---------------- ----------- ------ ----------
|
||
create_issue mcp:linear yes no
|
||
list_issues mcp:linear no -
|
||
deploy-to-staging agent_skill yes composite
|
||
code-review agent_skill no -
|
||
run_migrations custom yes transaction
|
||
shell_execute builtin yes snapshot
|
||
|
||
MCP Servers (1)
|
||
linear: stdio, 2 tools, connected
|
||
|
||
Capability Summary
|
||
Total Tools: 23
|
||
Read-Only: 10
|
||
Writes: 13
|
||
Checkpointable: 10
|
||
Has Side Effects: 3
|
||
Requires Approval: 1
|
||
|
||
Referenced By
|
||
Actors: local/code-assistant
|
||
Skills: local/full-stack-dev
|
||
|
||
[OK] Skill loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill show local/devops-toolkit",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"skill": {
|
||
"name": "local/devops-toolkit",
|
||
"description": "Full-stack development tools",
|
||
"config": "./skills/devops-toolkit.yaml",
|
||
"created": "2026-02-08T13:10:00Z",
|
||
"updated": "2026-02-08T14:22:00Z"
|
||
},
|
||
"includes": [
|
||
{ "name": "local/file-ops", "tools": 9, "source": "builtin" },
|
||
{ "name": "local/git-ops", "tools": 4, "source": "builtin" },
|
||
{ "name": "local/github", "tools": 4, "source": "mcp" }
|
||
],
|
||
"direct_tools": [
|
||
{ "name": "create_issue", "source": "mcp:linear", "writes": true, "checkpoint": "no" },
|
||
{ "name": "list_issues", "source": "mcp:linear", "writes": false, "checkpoint": null },
|
||
{ "name": "deploy-to-staging", "source": "agent_skill", "writes": true, "checkpoint": "composite" },
|
||
{ "name": "code-review", "source": "agent_skill", "writes": false, "checkpoint": null },
|
||
{ "name": "run_migrations", "source": "custom", "writes": true, "checkpoint": "transaction" },
|
||
{ "name": "shell_execute", "source": "builtin", "writes": true, "checkpoint": "snapshot" }
|
||
],
|
||
"mcp_servers": [
|
||
{ "name": "linear", "transport": "stdio", "tools": 2, "status": "connected" }
|
||
],
|
||
"capability_summary": {
|
||
"total_tools": 23,
|
||
"read_only": 10,
|
||
"writes": 13,
|
||
"checkpointable": 10,
|
||
"has_side_effects": 3,
|
||
"requires_approval": 1
|
||
},
|
||
"referenced_by": {
|
||
"actors": ["local/code-assistant"],
|
||
"skills": ["local/full-stack-dev"]
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 110
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "Skill loaded" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill show local/devops-toolkit
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
skill:
|
||
name: local/devops-toolkit
|
||
description: Full-stack development tools
|
||
config: ./skills/devops-toolkit.yaml
|
||
created: "2026-02-08T13:10:00Z"
|
||
updated: "2026-02-08T14:22:00Z"
|
||
includes:
|
||
- name: local/file-ops
|
||
tools: 9
|
||
source: builtin
|
||
- name: local/git-ops
|
||
tools: 4
|
||
source: builtin
|
||
- name: local/github
|
||
tools: 4
|
||
source: mcp
|
||
direct_tools:
|
||
- name: create_issue
|
||
source: "mcp:linear"
|
||
writes: true
|
||
checkpoint: "no"
|
||
- name: list_issues
|
||
source: "mcp:linear"
|
||
writes: false
|
||
checkpoint: null
|
||
- name: deploy-to-staging
|
||
source: agent_skill
|
||
writes: true
|
||
checkpoint: composite
|
||
- name: code-review
|
||
source: agent_skill
|
||
writes: false
|
||
checkpoint: null
|
||
- name: run_migrations
|
||
source: custom
|
||
writes: true
|
||
checkpoint: transaction
|
||
- name: shell_execute
|
||
source: builtin
|
||
writes: true
|
||
checkpoint: snapshot
|
||
mcp_servers:
|
||
- name: linear
|
||
transport: stdio
|
||
tools: 2
|
||
status: connected
|
||
capability_summary:
|
||
total_tools: 23
|
||
read_only: 10
|
||
writes: 13
|
||
checkpointable: 10
|
||
has_side_effects: 3
|
||
requires_approval: 1
|
||
referenced_by:
|
||
actors:
|
||
- local/code-assistant
|
||
skills:
|
||
- local/full-stack-dev
|
||
timing:
|
||
duration_ms: 110
|
||
messages:
|
||
- level: ok
|
||
text: Skill loaded
|
||
```
|
||
|
||
##### agents skill tools
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> skill tools <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
List all tools provided by a skill, including those inherited from included skills (the flattened tool set).
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Skill name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> skill tools local/devops-toolkit
|
||
|
||
╭─ Tools for local/devops-toolkit ─────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">From Skill</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Writes</span> <span style="color: cyan; font-weight: 600;">Checkpoint</span> │
|
||
│ <span style="opacity: 0.7;">───────────────── ─────────── ────────────── ───────── ────── ──────────</span> │
|
||
│ read_file builtin local/file-ops ✓ — — │
|
||
│ write_file builtin local/file-ops — ✓ file │
|
||
│ edit_file builtin local/file-ops — ✓ file │
|
||
│ delete_file builtin local/file-ops — ✓ file │
|
||
│ move_file builtin local/file-ops — ✓ file │
|
||
│ copy_file builtin local/file-ops — ✓ file │
|
||
│ create_directory builtin local/file-ops — ✓ file │
|
||
│ list_directory builtin local/file-ops ✓ — — │
|
||
│ delete_directory builtin local/file-ops — ✓ file │
|
||
│ git_status builtin local/git-ops ✓ — — │
|
||
│ git_diff builtin local/git-ops ✓ — — │
|
||
│ git_log builtin local/git-ops ✓ — — │
|
||
│ git_blame builtin local/git-ops ✓ — — │
|
||
│ create_issue mcp:github local/github — ✓ no │
|
||
│ create_pr mcp:github local/github — ✓ no │
|
||
│ list_repos mcp:github local/github ✓ — — │
|
||
│ get_file_contents mcp:github local/github ✓ — — │
|
||
│ create_issue mcp:linear (direct) — ✓ no │
|
||
│ list_issues mcp:linear (direct) ✓ — — │
|
||
│ run_migrations custom (direct) — ✓ transaction │
|
||
│ deploy-to-staging agent_skill (direct) — ✓ composite │
|
||
│ code-review agent_skill (direct) ✓ — — │
|
||
│ shell_execute builtin (direct) — ✓ snapshot │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 23 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">From Includes:</span> 17 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Direct:</span> 6 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 10 │
|
||
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 13 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> 10 │
|
||
╰────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 23 tools listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents skill tools local/devops-toolkit
|
||
|
||
Tools for local/devops-toolkit
|
||
Tool Source From Skill Read-Only Writes Checkpoint
|
||
----------------- ----------- -------------- --------- ------ ----------
|
||
read_file builtin local/file-ops yes - -
|
||
write_file builtin local/file-ops - yes file
|
||
edit_file builtin local/file-ops - yes file
|
||
delete_file builtin local/file-ops - yes file
|
||
move_file builtin local/file-ops - yes file
|
||
copy_file builtin local/file-ops - yes file
|
||
create_directory builtin local/file-ops - yes file
|
||
list_directory builtin local/file-ops yes - -
|
||
delete_directory builtin local/file-ops - yes file
|
||
git_status builtin local/git-ops yes - -
|
||
git_diff builtin local/git-ops yes - -
|
||
git_log builtin local/git-ops yes - -
|
||
git_blame builtin local/git-ops yes - -
|
||
create_issue mcp:github local/github - yes no
|
||
create_pr mcp:github local/github - yes no
|
||
list_repos mcp:github local/github yes - -
|
||
get_file_contents mcp:github local/github yes - -
|
||
create_issue mcp:linear (direct) - yes no
|
||
list_issues mcp:linear (direct) yes - -
|
||
run_migrations custom (direct) - yes transaction
|
||
deploy-to-staging agent_skill (direct) - yes composite
|
||
code-review agent_skill (direct) yes - -
|
||
shell_execute builtin (direct) - yes snapshot
|
||
|
||
Summary
|
||
Total: 23
|
||
From Includes: 17
|
||
Direct: 6
|
||
Read-Only: 10
|
||
Writes: 13
|
||
Checkpointable: 10
|
||
|
||
[OK] 23 tools listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "skill tools local/devops-toolkit",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tools": [
|
||
{ "name": "read_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "write_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "edit_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "delete_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "move_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "copy_file", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "create_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "list_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "delete_directory", "source": "builtin", "from_skill": "local/file-ops", "read_only": false, "writes": true, "checkpoint": "file" },
|
||
{ "name": "git_status", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "git_diff", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "git_log", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "git_blame", "source": "builtin", "from_skill": "local/git-ops", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "create_issue", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" },
|
||
{ "name": "create_pr", "source": "mcp:github", "from_skill": "local/github", "read_only": false, "writes": true, "checkpoint": "no" },
|
||
{ "name": "list_repos", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "get_file_contents", "source": "mcp:github", "from_skill": "local/github", "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "create_issue", "source": "mcp:linear", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "no" },
|
||
{ "name": "list_issues", "source": "mcp:linear", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "run_migrations", "source": "custom", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "transaction" },
|
||
{ "name": "deploy-to-staging", "source": "agent_skill", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "composite" },
|
||
{ "name": "code-review", "source": "agent_skill", "from_skill": null, "read_only": true, "writes": false, "checkpoint": null },
|
||
{ "name": "shell_execute", "source": "builtin", "from_skill": null, "read_only": false, "writes": true, "checkpoint": "snapshot" }
|
||
],
|
||
"summary": {
|
||
"total": 23,
|
||
"from_includes": 17,
|
||
"direct": 6,
|
||
"read_only": 10,
|
||
"writes": 13,
|
||
"checkpointable": 10
|
||
}
|
||
},
|
||
"timing": {
|
||
"duration_ms": 85
|
||
},
|
||
"messages": [
|
||
{ "level": "ok", "text": "23 tools listed" }
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: skill tools local/devops-toolkit
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tools:
|
||
- name: read_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: write_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: edit_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: delete_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: move_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: copy_file
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: create_directory
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: list_directory
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: delete_directory
|
||
source: builtin
|
||
from_skill: local/file-ops
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: file
|
||
- name: git_status
|
||
source: builtin
|
||
from_skill: local/git-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: git_diff
|
||
source: builtin
|
||
from_skill: local/git-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: git_log
|
||
source: builtin
|
||
from_skill: local/git-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: git_blame
|
||
source: builtin
|
||
from_skill: local/git-ops
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: create_issue
|
||
source: "mcp:github"
|
||
from_skill: local/github
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: "no"
|
||
- name: create_pr
|
||
source: "mcp:github"
|
||
from_skill: local/github
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: "no"
|
||
- name: list_repos
|
||
source: "mcp:github"
|
||
from_skill: local/github
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: get_file_contents
|
||
source: "mcp:github"
|
||
from_skill: local/github
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: create_issue
|
||
source: "mcp:linear"
|
||
from_skill: null
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: "no"
|
||
- name: list_issues
|
||
source: "mcp:linear"
|
||
from_skill: null
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: run_migrations
|
||
source: custom
|
||
from_skill: null
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: transaction
|
||
- name: deploy-to-staging
|
||
source: agent_skill
|
||
from_skill: null
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: composite
|
||
- name: code-review
|
||
source: agent_skill
|
||
from_skill: null
|
||
read_only: true
|
||
writes: false
|
||
checkpoint: null
|
||
- name: shell_execute
|
||
source: builtin
|
||
from_skill: null
|
||
read_only: false
|
||
writes: true
|
||
checkpoint: snapshot
|
||
summary:
|
||
total: 23
|
||
from_includes: 17
|
||
direct: 6
|
||
read_only: 10
|
||
writes: 13
|
||
checkpointable: 10
|
||
timing:
|
||
duration_ms: 85
|
||
messages:
|
||
- level: ok
|
||
text: 23 tools listed
|
||
```
|
||
|
||
#### agents tool
|
||
|
||
!!! info "Purpose"
|
||
Manage ==tools== — namespaced, independently registered, callable operations. Tools are defined in their own YAML configuration files and registered in the system through these commands. Once registered, tools can be referenced by name in skills (as part of a tool collection) and in actor graphs (as tool nodes).
|
||
|
||
??? tip "Tool Lifecycle Overview"
|
||
| Stage | Command | Description |
|
||
| :---- | :------ | :---------- |
|
||
| **Register** | `agents tool add` | Register from YAML config |
|
||
| **Inspect** | `agents tool show` | View tool details and capabilities |
|
||
| **List** | `agents tool list` | Browse registered tools |
|
||
| **Update** | `agents tool add --update` | Re-register with updated config |
|
||
| **Remove** | `agents tool remove` | Unregister a tool |
|
||
|
||
##### agents tool add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new tool. The tool is fully defined by the YAML configuration file specified with `--config`. If a tool with the same name already exists, the command fails unless the `--update` flag is provided, which allows overwriting the existing registration with the new configuration.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Path to the tool YAML configuration file (required). The file must fully define the tool, including the `name` field which determines the tool's registered name.
|
||
- `--update`: Allow overwriting an existing tool registration. Without this flag, attempting to add a tool whose name is already registered will fail.
|
||
|
||
**Examples**
|
||
|
||
Registering a new tool:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/run-migrations.yaml
|
||
|
||
╭─ Tool Registered ────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run database migrations │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./tools/run-migrations.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:15 │
|
||
╰──────────────────────────────────────────────╯
|
||
|
||
╭─ Capability ─────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Writes:</span> true │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Write Scope:</span> database:migrations │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> true │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint Scope:</span> transaction │
|
||
│ <span style="color: yellow; font-weight: 600;">Side Effects:</span> schema_mutation │
|
||
╰──────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool add --config ./tools/run-migrations.yaml
|
||
|
||
Tool Registered
|
||
Name: local/run-migrations
|
||
Description: Run database migrations
|
||
Source: custom
|
||
Config: ./tools/run-migrations.yaml
|
||
Created: 2026-02-09 10:15
|
||
|
||
Capability
|
||
Writes: true
|
||
Write Scope: database:migrations
|
||
Checkpointable: true
|
||
Checkpoint Scope: transaction
|
||
Side Effects: schema_mutation
|
||
|
||
[OK] Tool registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tool_registered": {
|
||
"name": "local/run-migrations",
|
||
"description": "Run database migrations",
|
||
"source": "custom",
|
||
"config": "./tools/run-migrations.yaml",
|
||
"created": "2026-02-09T10:15:00Z"
|
||
},
|
||
"capability": {
|
||
"writes": true,
|
||
"write_scope": "database:migrations",
|
||
"checkpointable": true,
|
||
"checkpoint_scope": "transaction",
|
||
"side_effects": ["schema_mutation"]
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 58 },
|
||
"messages": ["Tool registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tool_registered:
|
||
name: local/run-migrations
|
||
description: Run database migrations
|
||
source: custom
|
||
config: ./tools/run-migrations.yaml
|
||
created: "2026-02-09T10:15:00Z"
|
||
capability:
|
||
writes: true
|
||
write_scope: "database:migrations"
|
||
checkpointable: true
|
||
checkpoint_scope: transaction
|
||
side_effects:
|
||
- schema_mutation
|
||
timing:
|
||
duration_ms: 58
|
||
messages:
|
||
- Tool registered
|
||
```
|
||
|
||
Attempting to add a tool that already exists (without `--update`):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/run-migrations-v2.yaml
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ Error:</span> Tool 'local/run-migrations' is already registered.
|
||
|
||
To overwrite the existing configuration, re-run with <span style="color: cyan;">--update</span>:
|
||
|
||
agents tool add <span style="color: cyan;">--config</span> ./tools/run-migrations-v2.yaml <span style="color: cyan;">--update</span>
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool add --config ./tools/run-migrations-v2.yaml
|
||
|
||
[ERROR] Tool 'local/run-migrations' is already registered.
|
||
|
||
To overwrite the existing configuration, re-run with --update:
|
||
|
||
agents tool add --config ./tools/run-migrations-v2.yaml --update
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool add",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"error": "Tool 'local/run-migrations' is already registered.",
|
||
"hint": "To overwrite the existing configuration, re-run with --update",
|
||
"suggested_command": "agents tool add --config ./tools/run-migrations-v2.yaml --update"
|
||
},
|
||
"timing": { "duration_ms": 12 },
|
||
"messages": ["Tool 'local/run-migrations' is already registered."]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool add
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
error: "Tool 'local/run-migrations' is already registered."
|
||
hint: "To overwrite the existing configuration, re-run with --update"
|
||
suggested_command: "agents tool add --config ./tools/run-migrations-v2.yaml --update"
|
||
timing:
|
||
duration_ms: 12
|
||
messages:
|
||
- "Tool 'local/run-migrations' is already registered."
|
||
```
|
||
|
||
Updating an existing tool with `--update`:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool add <span style="color: cyan;">--config</span> ./tools/db-migrate.yaml <span style="color: cyan;">--update</span>
|
||
|
||
╭─ Tool Updated ─────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/db-migrate │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom (Python) │
|
||
│ <span style="color: yellow; font-weight: 600;">Status:</span> updated (was version 1 → now 2) │
|
||
╰────────────────────────────────────────────╯
|
||
|
||
╭─ Changes ─────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Input Schema:</span> modified (added batch_size) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Capabilities:</span> unchanged (writes, checkpoint) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> updated │
|
||
╰───────────────────────────────────────────────╯
|
||
|
||
╭─ References ──────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> 1 (local/db-tools) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actors:</span> 0 │
|
||
│ <span style="opacity: 0.7;">Referencing skills will use</span> │
|
||
│ <span style="opacity: 0.7;">the updated definition.</span> │
|
||
╰───────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool updated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool add --config ./tools/db-migrate.yaml --update
|
||
|
||
Tool Updated
|
||
Name: local/db-migrate
|
||
Source: custom (Python)
|
||
Status: updated (was version 1 -> now 2)
|
||
|
||
Changes
|
||
Input Schema: modified (added batch_size)
|
||
Capabilities: unchanged (writes, checkpoint)
|
||
Description: updated
|
||
|
||
References
|
||
Skills: 1 (local/db-tools)
|
||
Actors: 0
|
||
Referencing skills will use the updated definition.
|
||
|
||
[OK] Tool updated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tool_updated": {
|
||
"name": "local/db-migrate",
|
||
"source": "custom",
|
||
"source_language": "Python",
|
||
"status": "updated",
|
||
"previous_version": 1,
|
||
"current_version": 2
|
||
},
|
||
"changes": {
|
||
"input_schema": "modified (added batch_size)",
|
||
"capabilities": "unchanged (writes, checkpoint)",
|
||
"description": "updated"
|
||
},
|
||
"references": {
|
||
"skills": ["local/db-tools"],
|
||
"actors": []
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 45 },
|
||
"messages": ["Tool updated"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tool_updated:
|
||
name: local/db-migrate
|
||
source: custom
|
||
source_language: Python
|
||
status: updated
|
||
previous_version: 1
|
||
current_version: 2
|
||
changes:
|
||
input_schema: "modified (added batch_size)"
|
||
capabilities: "unchanged (writes, checkpoint)"
|
||
description: updated
|
||
references:
|
||
skills:
|
||
- local/db-tools
|
||
actors: []
|
||
timing:
|
||
duration_ms: 45
|
||
messages:
|
||
- Tool updated
|
||
```
|
||
|
||
##### agents tool remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> tool remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! danger "Destructive Operation"
|
||
Remove a registered tool. Because Validations are a subtype of Tool and share the same registry, this command ==also removes validations==. When removing a Validation, all attachments are automatically detached before the entry is removed from the registry.
|
||
|
||
References from skills and actor graphs will **break** until resolved.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Tool or validation name to remove.
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool remove local/run-migrations
|
||
|
||
Remove tool local/run-migrations? [y/N]: y
|
||
|
||
╭─ Tool Removed ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ References ──────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This tool is referenced by: │
|
||
│ - Skill: local/devops-toolkit │
|
||
│ - Actor graph node: code_executor.run_db_migrate │
|
||
│ These references will break until resolved. │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool remove local/run-migrations
|
||
|
||
Remove tool local/run-migrations? [y/N]: y
|
||
|
||
Tool Removed
|
||
Name: local/run-migrations
|
||
Source: custom
|
||
|
||
References
|
||
Warning: This tool is referenced by:
|
||
- Skill: local/devops-toolkit
|
||
- Actor graph node: code_executor.run_db_migrate
|
||
These references will break until resolved.
|
||
|
||
[OK] Tool removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tool_removed": {
|
||
"name": "local/run-migrations",
|
||
"source": "custom"
|
||
},
|
||
"broken_references": [
|
||
{ "type": "skill", "name": "local/devops-toolkit" },
|
||
{ "type": "actor_graph_node", "name": "code_executor.run_db_migrate" }
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 34 },
|
||
"messages": [
|
||
"Tool removed",
|
||
"Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved."
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tool_removed:
|
||
name: local/run-migrations
|
||
source: custom
|
||
broken_references:
|
||
- type: skill
|
||
name: local/devops-toolkit
|
||
- type: actor_graph_node
|
||
name: code_executor.run_db_migrate
|
||
timing:
|
||
duration_ms: 34
|
||
messages:
|
||
- Tool removed
|
||
- "Warning: This tool is referenced by 1 skill and 1 actor graph node. These references will break until resolved."
|
||
```
|
||
|
||
When removing a validation, attachments are cleaned up automatically:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool remove local/check-bundle-size
|
||
|
||
Remove validation local/check-bundle-size? [y/N]: y
|
||
|
||
╭─ Validation Removed ─────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/check-bundle-size │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Check bundle size (advisory) │
|
||
╰──────────────────────────────────────────────────╯
|
||
|
||
╭─ Detached From ────────────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This validation had 2 attachments: │
|
||
│ - local/api-repo (scope: project local/api-service) │
|
||
│ - local/api-repo (direct) │
|
||
│ These attachments have been removed. │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation removed─
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool remove local/check-bundle-size
|
||
|
||
Remove validation local/check-bundle-size? [y/N]: y
|
||
|
||
Validation Removed
|
||
Name: local/check-bundle-size
|
||
Description: Check bundle size (advisory)
|
||
|
||
Detached From
|
||
Warning: This validation had 2 attachments:
|
||
- local/api-repo (scope: project local/api-service)
|
||
- local/api-repo (direct)
|
||
These attachments have been removed.
|
||
|
||
[OK] Validation removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_removed": {
|
||
"name": "local/check-bundle-size",
|
||
"description": "Check bundle size (advisory)"
|
||
},
|
||
"detached_attachments": [
|
||
{ "resource": "local/api-repo", "scope": "project", "project": "local/api-service" },
|
||
{ "resource": "local/api-repo", "scope": "direct" }
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 41 },
|
||
"messages": [
|
||
"Validation removed",
|
||
"Warning: This validation had 2 attachments which have been removed."
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_removed:
|
||
name: local/check-bundle-size
|
||
description: "Check bundle size (advisory)"
|
||
detached_attachments:
|
||
- resource: local/api-repo
|
||
scope: project
|
||
project: local/api-service
|
||
- resource: local/api-repo
|
||
scope: direct
|
||
timing:
|
||
duration_ms: 41
|
||
messages:
|
||
- Validation removed
|
||
- "Warning: This validation had 2 attachments which have been removed."
|
||
```
|
||
|
||
##### agents tool list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> tool list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--source</span> <span style="color: #66cc66;"><SOURCE></span>] [<span style="color: cyan;">--type</span> (<span style="color: magenta;">tool|validation</span>)] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List registered tools with optional filters. Because Validations are a subtype of Tool and share the same registry, this command lists both plain tools and validations. Use `--type validation` to show only validations, or `--type tool` to show only plain tools. When `--type` is omitted, both are listed with a `Type` column distinguishing them.
|
||
|
||
**Arguments**
|
||
|
||
- `--namespace/-n NS`: Filter by namespace.
|
||
- `--source SOURCE`: Filter by tool source type (mcp, agent_skill, builtin, custom).
|
||
- `--type TYPE`: Filter by entry type: `tool` (plain tools only) or `validation` (validations only). When omitted, both are listed.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool list <span style="color: cyan;">--namespace</span> local
|
||
|
||
╭─ Tools ─────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Read-Only</span> <span style="color: cyan; font-weight: 600;">Writes</span> │
|
||
│ <span style="opacity: 0.7;">───────────────────────── ────────── ─────── ───────── ──────</span> │
|
||
│ local/run-migrations tool custom — ✓ │
|
||
│ local/validate-api-compat tool custom — ✓ │
|
||
│ local/create-subplan tool custom — ✓ │
|
||
│ local/deploy-staging tool agent — ✓ │
|
||
│ local/run-tests validation custom ✓ — │
|
||
│ local/lint-check validation custom ✓ — │
|
||
│ local/check-bundle-size validation custom ✓ — │
|
||
│ local/type-check validation custom ✓ — │
|
||
╰─────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tools:</span> 4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Validations:</span> 4 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Read-Only:</span> 4 │
|
||
│ <span style="color: yellow; font-weight: 600;">Writes:</span> 4 │
|
||
╰──────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 8 tools listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool list --namespace local
|
||
|
||
Tools
|
||
Name Type Source Read-Only Writes
|
||
------------------------- ---------- ------- --------- ------
|
||
local/run-migrations tool custom - yes
|
||
local/validate-api-compat tool custom - yes
|
||
local/create-subplan tool custom - yes
|
||
local/deploy-staging tool agent - yes
|
||
local/run-tests validation custom yes -
|
||
local/lint-check validation custom yes -
|
||
local/check-bundle-size validation custom yes -
|
||
local/type-check validation custom yes -
|
||
|
||
Summary
|
||
Total: 8
|
||
Tools: 4
|
||
Validations: 4
|
||
Read-Only: 4
|
||
Writes: 4
|
||
|
||
[OK] 8 tools listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tools": [
|
||
{ "name": "local/run-migrations", "type": "tool", "source": "custom", "read_only": false, "writes": true },
|
||
{ "name": "local/validate-api-compat", "type": "tool", "source": "custom", "read_only": false, "writes": true },
|
||
{ "name": "local/create-subplan", "type": "tool", "source": "custom", "read_only": false, "writes": true },
|
||
{ "name": "local/deploy-staging", "type": "tool", "source": "agent", "read_only": false, "writes": true },
|
||
{ "name": "local/run-tests", "type": "validation", "source": "custom", "read_only": true, "writes": false },
|
||
{ "name": "local/lint-check", "type": "validation", "source": "custom", "read_only": true, "writes": false },
|
||
{ "name": "local/check-bundle-size", "type": "validation", "source": "custom", "read_only": true, "writes": false },
|
||
{ "name": "local/type-check", "type": "validation", "source": "custom", "read_only": true, "writes": false }
|
||
],
|
||
"summary": {
|
||
"total": 8,
|
||
"tools": 4,
|
||
"validations": 4,
|
||
"read_only": 4,
|
||
"writes": 4
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 22 },
|
||
"messages": ["8 tools listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tools:
|
||
- name: local/run-migrations
|
||
type: tool
|
||
source: custom
|
||
read_only: false
|
||
writes: true
|
||
- name: local/validate-api-compat
|
||
type: tool
|
||
source: custom
|
||
read_only: false
|
||
writes: true
|
||
- name: local/create-subplan
|
||
type: tool
|
||
source: custom
|
||
read_only: false
|
||
writes: true
|
||
- name: local/deploy-staging
|
||
type: tool
|
||
source: agent
|
||
read_only: false
|
||
writes: true
|
||
- name: local/run-tests
|
||
type: validation
|
||
source: custom
|
||
read_only: true
|
||
writes: false
|
||
- name: local/lint-check
|
||
type: validation
|
||
source: custom
|
||
read_only: true
|
||
writes: false
|
||
- name: local/check-bundle-size
|
||
type: validation
|
||
source: custom
|
||
read_only: true
|
||
writes: false
|
||
- name: local/type-check
|
||
type: validation
|
||
source: custom
|
||
read_only: true
|
||
writes: false
|
||
summary:
|
||
total: 8
|
||
tools: 4
|
||
validations: 4
|
||
read_only: 4
|
||
writes: 4
|
||
timing:
|
||
duration_ms: 22
|
||
messages:
|
||
- 8 tools listed
|
||
```
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool list <span style="color: cyan;">--type</span> validation <span style="color: cyan;">--namespace</span> local
|
||
|
||
╭─ Validations ─────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Mode</span> <span style="color: cyan; font-weight: 600;">Attachments</span> │
|
||
│ <span style="opacity: 0.7;">───────────────────────── ─────── ──────────── ────────────────────────</span> │
|
||
│ local/run-tests custom required 2 (1 direct, 1 project) │
|
||
│ local/lint-check custom required 1 (1 direct) │
|
||
│ local/check-bundle-size custom informational 1 (1 project) │
|
||
│ local/type-check custom required 2 (2 project) │
|
||
╰───────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 4 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Required:</span> 3 │
|
||
│ <span style="color: yellow; font-weight: 600;">Informational:</span> 1 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 4 validations listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool list --type validation --namespace local
|
||
|
||
Validations
|
||
Name Source Mode Attachments
|
||
------------------------- ------- ------------ ------------------------
|
||
local/run-tests custom required 2 (1 direct, 1 project)
|
||
local/lint-check custom required 1 (1 direct)
|
||
local/check-bundle-size custom informational 1 (1 project)
|
||
local/type-check custom required 2 (2 project)
|
||
|
||
Summary
|
||
Total: 4
|
||
Required: 3
|
||
Informational: 1
|
||
|
||
[OK] 4 validations listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validations": [
|
||
{ "name": "local/run-tests", "source": "custom", "mode": "required", "attachments": { "total": 2, "direct": 1, "project": 1 } },
|
||
{ "name": "local/lint-check", "source": "custom", "mode": "required", "attachments": { "total": 1, "direct": 1 } },
|
||
{ "name": "local/check-bundle-size", "source": "custom", "mode": "informational", "attachments": { "total": 1, "project": 1 } },
|
||
{ "name": "local/type-check", "source": "custom", "mode": "required", "attachments": { "total": 2, "project": 2 } }
|
||
],
|
||
"summary": {
|
||
"total": 4,
|
||
"required": 3,
|
||
"informational": 1
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 18 },
|
||
"messages": ["4 validations listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validations:
|
||
- name: local/run-tests
|
||
source: custom
|
||
mode: required
|
||
attachments:
|
||
total: 2
|
||
direct: 1
|
||
project: 1
|
||
- name: local/lint-check
|
||
source: custom
|
||
mode: required
|
||
attachments:
|
||
total: 1
|
||
direct: 1
|
||
- name: local/check-bundle-size
|
||
source: custom
|
||
mode: informational
|
||
attachments:
|
||
total: 1
|
||
project: 1
|
||
- name: local/type-check
|
||
source: custom
|
||
mode: required
|
||
attachments:
|
||
total: 2
|
||
project: 2
|
||
summary:
|
||
total: 4
|
||
required: 3
|
||
informational: 1
|
||
timing:
|
||
duration_ms: 18
|
||
messages:
|
||
- 4 validations listed
|
||
```
|
||
|
||
##### agents tool show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> tool show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show full details for a registered tool, including its schema, capability metadata, and where it is referenced. Because Validations are a subtype of Tool and share the same registry, this command also shows validation details. When showing a Validation, additional validation-specific fields are displayed: `Mode` (required/informational) and `Attached To` (listing each resource attachment with its scope — direct, project-scoped, or plan-scoped).
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Tool or validation name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool show local/run-migrations
|
||
|
||
╭─ Tool Details ───────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-migrations │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run database migrations │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./tools/run-migrations.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
|
||
╰──────────────────────────────────────────────╯
|
||
|
||
╭─ Input Schema ─────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">direction</span>: string (required) enum: [up, down] │
|
||
│ <span style="color: #5599ff; font-weight: 600;">count</span>: integer (default: 1) │
|
||
╰────────────────────────────────────────────────╯
|
||
|
||
╭─ Capability ──────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> false │
|
||
│ <span style="color: yellow; font-weight: 600;">Writes:</span> true │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Write Scope:</span> database:migrations │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> true │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint Scope:</span> transaction │
|
||
│ <span style="color: yellow; font-weight: 600;">Side Effects:</span> schema_mutation │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Idempotent:</span> false │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Referenced By ───────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Skills:</span> │
|
||
│ - local/devops-toolkit │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Actor Graph Nodes:</span> │
|
||
│ - code_executor.run_db_migrate │
|
||
╰───────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Tool details loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool show local/run-migrations
|
||
|
||
Tool Details
|
||
Name: local/run-migrations
|
||
Description: Run database migrations
|
||
Source: custom
|
||
Config: ./tools/run-migrations.yaml
|
||
Registered: 2026-02-09 10:15
|
||
|
||
Input Schema
|
||
direction: string (required) enum: [up, down]
|
||
count: integer (default: 1)
|
||
|
||
Capability
|
||
Read-Only: false
|
||
Writes: true
|
||
Write Scope: database:migrations
|
||
Checkpointable: true
|
||
Checkpoint Scope: transaction
|
||
Side Effects: schema_mutation
|
||
Idempotent: false
|
||
|
||
Referenced By
|
||
Skills:
|
||
- local/devops-toolkit
|
||
Actor Graph Nodes:
|
||
- code_executor.run_db_migrate
|
||
|
||
[OK] Tool details loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"tool_details": {
|
||
"name": "local/run-migrations",
|
||
"description": "Run database migrations",
|
||
"source": "custom",
|
||
"config": "./tools/run-migrations.yaml",
|
||
"registered": "2026-02-09T10:15:00Z"
|
||
},
|
||
"input_schema": {
|
||
"direction": { "type": "string", "required": true, "enum": ["up", "down"] },
|
||
"count": { "type": "integer", "default": 1 }
|
||
},
|
||
"capability": {
|
||
"read_only": false,
|
||
"writes": true,
|
||
"write_scope": "database:migrations",
|
||
"checkpointable": true,
|
||
"checkpoint_scope": "transaction",
|
||
"side_effects": ["schema_mutation"],
|
||
"idempotent": false
|
||
},
|
||
"referenced_by": {
|
||
"skills": ["local/devops-toolkit"],
|
||
"actor_graph_nodes": ["code_executor.run_db_migrate"]
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 15 },
|
||
"messages": ["Tool details loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
tool_details:
|
||
name: local/run-migrations
|
||
description: Run database migrations
|
||
source: custom
|
||
config: ./tools/run-migrations.yaml
|
||
registered: "2026-02-09T10:15:00Z"
|
||
input_schema:
|
||
direction:
|
||
type: string
|
||
required: true
|
||
enum:
|
||
- up
|
||
- down
|
||
count:
|
||
type: integer
|
||
default: 1
|
||
capability:
|
||
read_only: false
|
||
writes: true
|
||
write_scope: "database:migrations"
|
||
checkpointable: true
|
||
checkpoint_scope: transaction
|
||
side_effects:
|
||
- schema_mutation
|
||
idempotent: false
|
||
referenced_by:
|
||
skills:
|
||
- local/devops-toolkit
|
||
actor_graph_nodes:
|
||
- code_executor.run_db_migrate
|
||
timing:
|
||
duration_ms: 15
|
||
messages:
|
||
- Tool details loaded
|
||
```
|
||
|
||
When showing a Validation, the output includes validation-specific sections:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> tool show local/run-tests
|
||
|
||
╭─ Validation Details ──────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> validation │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run unit tests with coverage │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./validations/run-tests.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
╭─ Input Schema ─────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">coverage_threshold</span>: integer (default: 80) │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Output Schema (Validation Return Format) ─────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">passed</span>: boolean (required) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">message</span>: string (optional) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">data</span>: object (optional, arbitrary structure) │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Capability ──────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> true (enforced) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> false (enforced) │
|
||
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 600s │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Attached To ─────────────────────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/api-repo</span> (direct, always active) │
|
||
│ <span style="opacity: 0.7;">(attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)</span> │
|
||
│ <span style="color: #5599ff; font-weight: 600;">local/api-repo</span> (scope: project local/api-service) │
|
||
│ <span style="opacity: 0.7;">(attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)</span> │
|
||
╰───────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation details loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents tool show local/run-tests
|
||
|
||
Validation Details
|
||
Name: local/run-tests
|
||
Type: validation
|
||
Description: Run unit tests with coverage
|
||
Source: custom
|
||
Mode: required
|
||
Config: ./validations/run-tests.yaml
|
||
Registered: 2026-02-09 10:15
|
||
|
||
Input Schema
|
||
coverage_threshold: integer (default: 80)
|
||
|
||
Output Schema (Validation Return Format)
|
||
passed: boolean (required)
|
||
message: string (optional)
|
||
data: object (optional, arbitrary structure)
|
||
|
||
Capability
|
||
Read-Only: true (enforced)
|
||
Checkpointable: false (enforced)
|
||
Timeout: 600s
|
||
|
||
Attached To
|
||
local/api-repo (direct, always active)
|
||
(attachment: 01HXM5B2C3D4E5F6G7H8J9K0L1)
|
||
local/api-repo (scope: project local/api-service)
|
||
(attachment: 01HXM5A1B2C3D4E5F6G7H8J9K0)
|
||
|
||
[OK] Validation details loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "tool show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_details": {
|
||
"name": "local/run-tests",
|
||
"type": "validation",
|
||
"description": "Run unit tests with coverage",
|
||
"source": "custom",
|
||
"mode": "required",
|
||
"config": "./validations/run-tests.yaml",
|
||
"registered": "2026-02-09T10:15:00Z"
|
||
},
|
||
"input_schema": {
|
||
"coverage_threshold": { "type": "integer", "default": 80 }
|
||
},
|
||
"output_schema": {
|
||
"passed": { "type": "boolean", "required": true },
|
||
"message": { "type": "string", "required": false },
|
||
"data": { "type": "object", "required": false, "description": "arbitrary structure" }
|
||
},
|
||
"capability": {
|
||
"read_only": true,
|
||
"read_only_enforced": true,
|
||
"checkpointable": false,
|
||
"checkpointable_enforced": true,
|
||
"timeout_seconds": 600
|
||
},
|
||
"attached_to": [
|
||
{ "resource": "local/api-repo", "scope": "direct", "attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1" },
|
||
{ "resource": "local/api-repo", "scope": "project", "project": "local/api-service", "attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0" }
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 19 },
|
||
"messages": ["Validation details loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: tool show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_details:
|
||
name: local/run-tests
|
||
type: validation
|
||
description: Run unit tests with coverage
|
||
source: custom
|
||
mode: required
|
||
config: ./validations/run-tests.yaml
|
||
registered: "2026-02-09T10:15:00Z"
|
||
input_schema:
|
||
coverage_threshold:
|
||
type: integer
|
||
default: 80
|
||
output_schema:
|
||
passed:
|
||
type: boolean
|
||
required: true
|
||
message:
|
||
type: string
|
||
required: false
|
||
data:
|
||
type: object
|
||
required: false
|
||
description: arbitrary structure
|
||
capability:
|
||
read_only: true
|
||
read_only_enforced: true
|
||
checkpointable: false
|
||
checkpointable_enforced: true
|
||
timeout_seconds: 600
|
||
attached_to:
|
||
- resource: local/api-repo
|
||
scope: direct
|
||
attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1
|
||
- resource: local/api-repo
|
||
scope: project
|
||
project: local/api-service
|
||
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
timing:
|
||
duration_ms: 19
|
||
messages:
|
||
- Validation details loaded
|
||
```
|
||
|
||
#### agents lsp
|
||
|
||
!!! info "Purpose"
|
||
Manage the **LSP Registry** — the global registry of Language Server Protocol servers that provide language intelligence (diagnostics, type information, completions, references, definitions, symbols, formatting, code actions, renaming) to actors. LSP servers are Infrastructure-layer components attached to actors via the `lsp:` configuration field; they have nothing to do with IDE integration. Each registered LSP server has a namespaced name (`[[server:]namespace/]name`), a launch command, supported languages, initialization options, and capability declarations. The `agents lsp` commands mirror the structure of `agents tool` commands.
|
||
|
||
##### agents lsp add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> lsp add [<span style="color: cyan;">--update</span>|<span style="color: yellow;">-u</span>] (<span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span>) <span style="color: #66cc66;"><FILE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Register an LSP server from a YAML configuration file. The config file defines the server's namespaced name, launch command, supported languages, initialization options, and capability declarations. If the server already exists and `--update` is not provided, the command fails with an error and a hint to use `--update`.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Path to LSP server YAML configuration file (required).
|
||
- `--update/-u`: Overwrite if the server already exists in the registry.
|
||
|
||
**Examples**
|
||
|
||
Registering a new LSP server:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp add <span style="color: cyan;">--config</span> lsp/pyright.yaml
|
||
|
||
╭─ LSP Server Registered ──────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Command:</span> pyright-langserver --stdio │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Capabilities:</span> diagnostics, hover, completions, │
|
||
│ references, definitions, symbols, │
|
||
│ rename, code_actions │
|
||
╰──────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> LSP server registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp add --config lsp/pyright.yaml
|
||
|
||
LSP Server Registered
|
||
Name: local/pyright
|
||
Languages: python
|
||
Command: pyright-langserver --stdio
|
||
Capabilities: diagnostics, hover, completions, references, definitions, symbols, rename, code_actions
|
||
|
||
[OK] LSP server registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"lsp_server": {
|
||
"name": "local/pyright",
|
||
"languages": ["python"],
|
||
"command": "pyright-langserver --stdio",
|
||
"capabilities": [
|
||
"diagnostics", "hover", "completions", "references",
|
||
"definitions", "symbols", "rename", "code_actions"
|
||
]
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 12 },
|
||
"messages": ["LSP server registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
lsp_server:
|
||
name: local/pyright
|
||
languages:
|
||
- python
|
||
command: pyright-langserver --stdio
|
||
capabilities:
|
||
- diagnostics
|
||
- hover
|
||
- completions
|
||
- references
|
||
- definitions
|
||
- symbols
|
||
- rename
|
||
- code_actions
|
||
timing:
|
||
duration_ms: 12
|
||
messages:
|
||
- LSP server registered
|
||
```
|
||
|
||
Attempting to add a server that already exists (without `--update`):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp add <span style="color: cyan;">--config</span> lsp/pyright.yaml
|
||
|
||
<span style="color: red; font-weight: 600;">✗ ERROR</span> LSP server 'local/pyright' already exists
|
||
|
||
<span style="color: yellow;">Hint:</span> Use <span style="color: cyan;">--update</span> to overwrite: agents lsp add --update --config lsp/pyright.yaml
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp add --config lsp/pyright.yaml
|
||
|
||
[ERROR] LSP server 'local/pyright' already exists
|
||
Hint: Use --update to overwrite: agents lsp add --update --config lsp/pyright.yaml
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp add",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"error": "LSP server 'local/pyright' already exists"
|
||
},
|
||
"hint": "Use --update to overwrite",
|
||
"suggested_command": "agents lsp add --update --config lsp/pyright.yaml",
|
||
"timing": { "duration_ms": 5 },
|
||
"messages": ["LSP server 'local/pyright' already exists"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp add
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
error: "LSP server 'local/pyright' already exists"
|
||
hint: Use --update to overwrite
|
||
suggested_command: agents lsp add --update --config lsp/pyright.yaml
|
||
timing:
|
||
duration_ms: 5
|
||
messages:
|
||
- "LSP server 'local/pyright' already exists"
|
||
```
|
||
|
||
##### agents lsp remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> lsp remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! danger "Destructive Operation"
|
||
Remove a registered LSP server from the LSP Registry. Running LSP server processes bound to the removed entry are terminated. Actor configurations referencing this server by name will fail at activation until resolved.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Namespaced LSP server name to remove.
|
||
- `--yes/-y`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp remove local/pyright
|
||
|
||
Remove LSP server local/pyright? [y/N]: y
|
||
|
||
╭─ LSP Server Removed ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
|
||
╰──────────────────────────────────────────╯
|
||
|
||
╭─ References ──────────────────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Warning:</span> This LSP server is referenced by: │
|
||
│ - Actor: local/code-reviewer (lsp: [local/pyright]) │
|
||
│ - Actor: local/refactor-agent (lsp: [local/pyright]) │
|
||
│ These actor LSP bindings will fail until resolved. │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> LSP server removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp remove local/pyright
|
||
|
||
Remove LSP server local/pyright? [y/N]: y
|
||
|
||
LSP Server Removed
|
||
Name: local/pyright
|
||
Languages: python
|
||
|
||
References
|
||
Warning: This LSP server is referenced by:
|
||
- Actor: local/code-reviewer (lsp: [local/pyright])
|
||
- Actor: local/refactor-agent (lsp: [local/pyright])
|
||
These actor LSP bindings will fail until resolved.
|
||
|
||
[OK] LSP server removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"lsp_server_removed": {
|
||
"name": "local/pyright",
|
||
"languages": ["python"]
|
||
},
|
||
"broken_references": [
|
||
{ "type": "actor", "name": "local/code-reviewer" },
|
||
{ "type": "actor", "name": "local/refactor-agent" }
|
||
]
|
||
},
|
||
"timing": { "duration_ms": 28 },
|
||
"messages": [
|
||
"LSP server removed",
|
||
"Warning: This LSP server is referenced by 2 actors. These actor LSP bindings will fail until resolved."
|
||
]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
lsp_server_removed:
|
||
name: local/pyright
|
||
languages:
|
||
- python
|
||
broken_references:
|
||
- type: actor
|
||
name: local/code-reviewer
|
||
- type: actor
|
||
name: local/refactor-agent
|
||
timing:
|
||
duration_ms: 28
|
||
messages:
|
||
- LSP server removed
|
||
- "Warning: This LSP server is referenced by 2 actors. These actor LSP bindings will fail until resolved."
|
||
```
|
||
|
||
##### agents lsp list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> lsp list [(<span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span>) <span style="color: #66cc66;"><NS></span>] [<span style="color: cyan;">--language</span> <span style="color: #66cc66;"><LANG></span>] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List registered LSP servers with optional filters. Shows each server's name, supported languages, command, and the number of actors currently bound to it.
|
||
|
||
**Arguments**
|
||
|
||
- `--namespace/-n NS`: Filter by namespace.
|
||
- `--language LANG`: Filter by supported language (e.g., `python`, `typescript`).
|
||
- `<REGEX>`: Optional name filter pattern.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp list
|
||
|
||
╭─ LSP Registry (3 servers) ───────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> │ <span style="color: cyan; font-weight: 600;">Languages</span> │ <span style="color: cyan; font-weight: 600;">Command</span> │ <span style="color: cyan; font-weight: 600;">Bound</span> │
|
||
│─────────────────────────│──────────────────────│─────────────────────────────│───────│
|
||
│ local/pyright │ python │ pyright-langserver --stdio │ 3 │
|
||
│ local/ts-server │ typescript, jsx, tsx │ typescript-language-server │ 2 │
|
||
│ local/gopls │ go │ gopls serve │ 1 │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────╯
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp list
|
||
|
||
LSP Registry (3 servers)
|
||
Name Languages Command Bound
|
||
local/pyright python pyright-langserver --stdio 3
|
||
local/ts-server typescript, jsx, tsx typescript-language-server 2
|
||
local/gopls go gopls serve 1
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"lsp_servers": [
|
||
{
|
||
"name": "local/pyright",
|
||
"languages": ["python"],
|
||
"command": "pyright-langserver --stdio",
|
||
"bound_actors": 3
|
||
},
|
||
{
|
||
"name": "local/ts-server",
|
||
"languages": ["typescript", "jsx", "tsx"],
|
||
"command": "typescript-language-server",
|
||
"bound_actors": 2
|
||
},
|
||
{
|
||
"name": "local/gopls",
|
||
"languages": ["go"],
|
||
"command": "gopls serve",
|
||
"bound_actors": 1
|
||
}
|
||
],
|
||
"total": 3
|
||
},
|
||
"timing": { "duration_ms": 8 },
|
||
"messages": ["3 LSP servers listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
lsp_servers:
|
||
- name: local/pyright
|
||
languages:
|
||
- python
|
||
command: pyright-langserver --stdio
|
||
bound_actors: 3
|
||
- name: local/ts-server
|
||
languages:
|
||
- typescript
|
||
- jsx
|
||
- tsx
|
||
command: typescript-language-server
|
||
bound_actors: 2
|
||
- name: local/gopls
|
||
languages:
|
||
- go
|
||
command: gopls serve
|
||
bound_actors: 1
|
||
total: 3
|
||
timing:
|
||
duration_ms: 8
|
||
messages:
|
||
- 3 LSP servers listed
|
||
```
|
||
|
||
Filtering by language:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp list <span style="color: cyan;">--language</span> python
|
||
|
||
╭─ LSP Registry (1 server, filtered: language=python) ─────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> │ <span style="color: cyan; font-weight: 600;">Languages</span> │ <span style="color: cyan; font-weight: 600;">Command</span> │ <span style="color: cyan; font-weight: 600;">Bound</span> │
|
||
│─────────────────────────│────────────│───────────────────────────────────│───────│
|
||
│ local/pyright │ python │ pyright-langserver --stdio │ 3 │
|
||
╰──────────────────────────────────────────────────────────────────────────────────╯
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp list --language python
|
||
|
||
LSP Registry (1 server, filtered: language=python)
|
||
Name Languages Command Bound
|
||
local/pyright python pyright-langserver --stdio 3
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"lsp_servers": [
|
||
{
|
||
"name": "local/pyright",
|
||
"languages": ["python"],
|
||
"command": "pyright-langserver --stdio",
|
||
"bound_actors": 3
|
||
}
|
||
],
|
||
"total": 1,
|
||
"filter": { "language": "python" }
|
||
},
|
||
"timing": { "duration_ms": 6 },
|
||
"messages": ["1 LSP server listed (filtered: language=python)"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
lsp_servers:
|
||
- name: local/pyright
|
||
languages:
|
||
- python
|
||
command: pyright-langserver --stdio
|
||
bound_actors: 3
|
||
total: 1
|
||
filter:
|
||
language: python
|
||
timing:
|
||
duration_ms: 6
|
||
messages:
|
||
- "1 LSP server listed (filtered: language=python)"
|
||
```
|
||
|
||
##### agents lsp show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> lsp show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show full details for a registered LSP server, including its configuration, supported languages, capabilities, initialization options, and which actors are bound to it.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Namespaced LSP server name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp show local/pyright
|
||
|
||
╭─ LSP Server Details ──────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/pyright │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Languages:</span> python │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Command:</span> pyright-langserver --stdio │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Root path:</span> {{ project.root }} │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Init options:</span> │
|
||
│ python.analysis.typeCheckingMode: standard │
|
||
│ python.analysis.autoSearchPaths: true │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Capabilities ────────────────────────────────────────────────╮
|
||
│ diagnostics, hover, completions, references, definitions, │
|
||
│ symbols, rename, code_actions │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Bound Actors ────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">local/code-reviewer</span> (explicit binding) │
|
||
│ <span style="color: cyan; font-weight: 600;">local/refactor-agent</span> (language-based: python) │
|
||
│ <span style="color: cyan; font-weight: 600;">local/polyglot-planner</span> (auto-discovery) │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp show local/pyright
|
||
|
||
LSP Server Details
|
||
Name: local/pyright
|
||
Languages: python
|
||
Command: pyright-langserver --stdio
|
||
Root path: {{ project.root }}
|
||
Init options:
|
||
python.analysis.typeCheckingMode: standard
|
||
python.analysis.autoSearchPaths: true
|
||
|
||
Capabilities
|
||
diagnostics, hover, completions, references, definitions, symbols, rename, code_actions
|
||
|
||
Bound Actors
|
||
local/code-reviewer (explicit binding)
|
||
local/refactor-agent (language-based: python)
|
||
local/polyglot-planner (auto-discovery)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "lsp show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"lsp_server": {
|
||
"name": "local/pyright",
|
||
"languages": ["python"],
|
||
"command": "pyright-langserver --stdio",
|
||
"root_path": "{{ project.root }}",
|
||
"init_options": {
|
||
"python.analysis.typeCheckingMode": "standard",
|
||
"python.analysis.autoSearchPaths": true
|
||
},
|
||
"capabilities": [
|
||
"diagnostics", "hover", "completions", "references",
|
||
"definitions", "symbols", "rename", "code_actions"
|
||
],
|
||
"bound_actors": [
|
||
{ "name": "local/code-reviewer", "binding_mode": "explicit" },
|
||
{ "name": "local/refactor-agent", "binding_mode": "language_based", "language": "python" },
|
||
{ "name": "local/polyglot-planner", "binding_mode": "auto_discovery" }
|
||
]
|
||
}
|
||
},
|
||
"timing": { "duration_ms": 14 },
|
||
"messages": ["LSP server details loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: lsp show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
lsp_server:
|
||
name: local/pyright
|
||
languages:
|
||
- python
|
||
command: pyright-langserver --stdio
|
||
root_path: "{{ project.root }}"
|
||
init_options:
|
||
python.analysis.typeCheckingMode: standard
|
||
python.analysis.autoSearchPaths: true
|
||
capabilities:
|
||
- diagnostics
|
||
- hover
|
||
- completions
|
||
- references
|
||
- definitions
|
||
- symbols
|
||
- rename
|
||
- code_actions
|
||
bound_actors:
|
||
- name: local/code-reviewer
|
||
binding_mode: explicit
|
||
- name: local/refactor-agent
|
||
binding_mode: language_based
|
||
language: python
|
||
- name: local/polyglot-planner
|
||
binding_mode: auto_discovery
|
||
timing:
|
||
duration_ms: 14
|
||
messages:
|
||
- LSP server details loaded
|
||
```
|
||
|
||
##### agents lsp serve
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> lsp serve [<span style="color: cyan;">--log-level</span> <span style="color: #66cc66;"><LEVEL></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Launch the stub LSP server over stdin/stdout using the JSON-RPC base protocol with Content-Length header framing. The server supports the `initialize`, `shutdown`, and `exit` lifecycle methods. Requests received **before** `initialize` are rejected with `ServerNotInitialized` (-32002) per the LSP specification. After initialization, unsupported LSP methods return a `MethodNotFound` (-32601) error. After `shutdown` is received, only `exit` is accepted; other requests are rejected with `InvalidRequest` (-32600). Sending `initialize` a second time is also rejected with `InvalidRequest`.
|
||
|
||
This command is intended for development and testing of LSP transport integration. In a future milestone the stub handlers will be replaced by real LSP server proxying through the A2A facade.
|
||
|
||
**Arguments**
|
||
|
||
- `--log-level LEVEL`: Logging level for the server process. Valid values: `debug`, `info` (default), `warning`, `error`. Invalid values cause immediate exit with a descriptive error message.
|
||
|
||
**Transport Limits**
|
||
|
||
| Limit | Value | Description |
|
||
|-------|-------|-------------|
|
||
| Max Content-Length | 10 MB | Messages exceeding this are rejected with a warning log (DoS guard) |
|
||
| Max header lines | 32 | Headers with more lines are rejected with a warning log (DoS guard) |
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> lsp serve
|
||
|
||
<span style="color: cyan; font-weight: 600;">CleverAgents LSP Server</span> (stub) starting — PID 7412
|
||
Log level: info
|
||
Transport: stdin/stdout (JSON-RPC, Content-Length framing)
|
||
Supported methods: initialize, shutdown, exit
|
||
All other methods → MethodNotFound (-32601)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents lsp serve
|
||
|
||
CleverAgents LSP Server (stub) starting — PID 7412
|
||
Log level: info
|
||
Transport: stdin/stdout (JSON-RPC, Content-Length framing)
|
||
Supported methods: initialize, shutdown, exit
|
||
All other methods → MethodNotFound (-32601)
|
||
```
|
||
|
||
#### agents validation
|
||
|
||
!!! info "Purpose"
|
||
Register and attach ==validations== — a specialized subtype of Tool that extends the Tool class with pass/fail semantics and attachment scoping. A Validation inherits all base Tool properties (name, source, input_schema, capability, resource bindings, lifecycle hooks, etc.) and adds: a `mode` field (`required` or `informational`), and a structured JSON return format with a mandatory `passed` boolean, an optional `message` string, and an optional `data` object for arbitrary informational output. Since Validation extends Tool, it shares the same backing sources (custom, MCP, agent_skill, builtin) plus the additional `wrapped` source type for Validations that wrap an existing Tool via the `wraps` field. It uses the same YAML configuration format (with an additional `validation` block and optional `wraps`/`transform` fields), and the same registries and resolution mechanisms. Validations are always read-only (`writes` is always `false`, `checkpointable` is always `false`).
|
||
|
||
Because Validations are a subtype of Tool and share the same Tool Registry and naming namespace, only validation-specific operations have dedicated subcommands here: `add` (registration with validation-specific fields like `mode`), `attach`, and `detach`. General tool operations — listing, inspection, and removal — are handled through the `agents tool` commands:
|
||
|
||
- **List validations**: `agents tool list --type validation`
|
||
- **Show validation details**: `agents tool show <NAME>` (displays validation-specific fields when the entry is a Validation)
|
||
- **Remove a validation**: `agents tool remove <NAME>` (automatically removes all attachments)
|
||
|
||
A validation is always attached to a resource. The optional `--project` or `--plan` flag controls the scope of the attachment:
|
||
- **Direct attachment** (no scope flag): The validation is always active for that resource, regardless of which plan or project accesses it. Use `agents validation attach <RESOURCE> <VALIDATION> [args...]`.
|
||
- **Project-scoped attachment** (`--project`): The validation only runs for that resource when it is being interacted with through the specified project. Use `agents validation attach --project <PROJECT> <RESOURCE> <VALIDATION> [args...]`.
|
||
- **Plan-scoped attachment** (`--plan`): The validation only runs for that resource when it is being interacted with through the specified plan. Use `agents validation attach --plan <PLAN_ID> <RESOURCE> <VALIDATION> [args...]`.
|
||
|
||
The same validation can be attached to the same resource multiple times — directly, through different projects, and through different plans — and since validations accept arguments, attaching the same validation to the same resource multiple times with different arguments is a common and useful configuration pattern (e.g., running the same test suite with different coverage thresholds for different projects).
|
||
|
||
Each `attach` invocation returns a system-assigned **attachment ULID** uniquely identifying that attachment. Use this ULID with `agents validation detach <ATTACHMENT_ID>` to remove a specific attachment.
|
||
|
||
When multiple attachment scopes apply, the union of all applicable validations is used. A resource with a directly-attached validation will always have that validation run, plus any additional validations attached through the active project or plan.
|
||
|
||
##### agents validation add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--required</span> | <span style="color: cyan;">--informational</span>] [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new validation. The validation is fully defined by the YAML configuration file specified with `--config`. The validation is registered in the shared Tool Registry under the name specified in the config file; the name must not conflict with any existing tool or validation. If a validation with the same name already exists, the command fails unless `--update` is provided. The validation YAML may use `wraps` to reference an existing Tool, reusing its implementation and interpreting its output through a `transform` function (see Tool Wrapping under Core Concepts > Validation). When `wraps` is used, the wrapped Tool must already be registered.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Path to the validation YAML configuration file (required). The file must fully define the validation, including the `name` field which determines the validation's registered name, the `validation.mode` field (`required` or `informational`), and either inline implementation (`source` + `code`) or wrapping (`wraps` + `transform`).
|
||
- `--required`: Override the mode in the YAML config to `required`. Mutually exclusive with `--informational`.
|
||
- `--informational`: Override the mode in the YAML config to `informational`. Mutually exclusive with `--required`.
|
||
- `--update`: Allow overwriting an existing validation registration.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/run-tests.yaml
|
||
|
||
╭─ Validation Registered ────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/run-tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Run unit tests with coverage │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./validations/run-tests.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:15 │
|
||
╰────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Capability ────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> true (enforced) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> false (enforced) │
|
||
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 600s │
|
||
╰─────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation add --config ./validations/run-tests.yaml
|
||
|
||
Validation Registered
|
||
Name: local/run-tests
|
||
Description: Run unit tests with coverage
|
||
Source: custom
|
||
Mode: required
|
||
Config: ./validations/run-tests.yaml
|
||
Created: 2026-02-09 10:15
|
||
|
||
Capability
|
||
Read-Only: true (enforced)
|
||
Checkpointable: false (enforced)
|
||
Timeout: 600s
|
||
|
||
[OK] Validation registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_registered": {
|
||
"name": "local/run-tests",
|
||
"description": "Run unit tests with coverage",
|
||
"source": "custom",
|
||
"mode": "required",
|
||
"config": "./validations/run-tests.yaml",
|
||
"created": "2026-02-09 10:15"
|
||
},
|
||
"capability": {
|
||
"read_only": "true (enforced)",
|
||
"checkpointable": "false (enforced)",
|
||
"timeout": "600s"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 120 },
|
||
"messages": ["Validation registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_registered:
|
||
name: local/run-tests
|
||
description: Run unit tests with coverage
|
||
source: custom
|
||
mode: required
|
||
config: ./validations/run-tests.yaml
|
||
created: "2026-02-09 10:15"
|
||
capability:
|
||
read_only: "true (enforced)"
|
||
checkpointable: "false (enforced)"
|
||
timeout: 600s
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 120
|
||
messages:
|
||
- "Validation registered"
|
||
```
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/lint-check.yaml
|
||
|
||
╭─ Validation Registered ──────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/lint-check │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Lint check │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 300s │
|
||
╰──────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation add --config ./validations/lint-check.yaml
|
||
|
||
Validation Registered
|
||
Name: local/lint-check
|
||
Description: Lint check
|
||
Source: custom
|
||
Mode: required
|
||
Timeout: 300s
|
||
|
||
[OK] Validation registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_registered": {
|
||
"name": "local/lint-check",
|
||
"description": "Lint check",
|
||
"source": "custom",
|
||
"mode": "required",
|
||
"timeout": "300s"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 95 },
|
||
"messages": ["Validation registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_registered:
|
||
name: local/lint-check
|
||
description: Lint check
|
||
source: custom
|
||
mode: required
|
||
timeout: 300s
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 95
|
||
messages:
|
||
- "Validation registered"
|
||
```
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation add <span style="color: cyan;">--config</span> ./validations/check-bundle-size.yaml
|
||
|
||
╭─ Validation Registered ───────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/check-bundle-size │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Check bundle size (advisory) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> custom │
|
||
│ <span style="color: yellow; font-weight: 600;">Mode:</span> informational │
|
||
│ <span style="color: yellow; font-weight: 600;">Timeout:</span> 300s │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation add --config ./validations/check-bundle-size.yaml
|
||
|
||
Validation Registered
|
||
Name: local/check-bundle-size
|
||
Description: Check bundle size (advisory)
|
||
Source: custom
|
||
Mode: informational
|
||
Timeout: 300s
|
||
|
||
[OK] Validation registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_registered": {
|
||
"name": "local/check-bundle-size",
|
||
"description": "Check bundle size (advisory)",
|
||
"source": "custom",
|
||
"mode": "informational",
|
||
"timeout": "300s"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 88 },
|
||
"messages": ["Validation registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_registered:
|
||
name: local/check-bundle-size
|
||
description: "Check bundle size (advisory)"
|
||
source: custom
|
||
mode: informational
|
||
timeout: 300s
|
||
timing:
|
||
started: "2026-02-09T10:16:00Z"
|
||
duration_ms: 88
|
||
messages:
|
||
- "Validation registered"
|
||
```
|
||
|
||
##### agents validation attach
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> validation attach [<span style="color: cyan;">--project</span> <span style="color: #66cc66;"><PROJECT></span>|<span style="color: cyan;">--plan</span> <span style="color: #66cc66;"><PLAN_ID></span>]
|
||
<span style="color: #66cc66;"><RESOURCE></span> <span style="color: #66cc66;"><VALIDATION></span> [<span style="color: #66cc66;"><ARGS></span>...]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Attach a registered validation to a resource, with an optional project or plan scope. A resource is always required — validations are fundamentally resource-centric. The optional `--project` or `--plan` flag narrows when the validation is active: without either flag, the validation runs whenever any plan or project accesses the resource; with `--project`, it only runs when the resource is accessed through that project; with `--plan`, it only runs when the resource is accessed through that plan. At most one scope flag may be provided per invocation.
|
||
|
||
The command returns a system-assigned **attachment ULID** that uniquely identifies this specific attachment association. This ULID is used to detach the validation later via `agents validation detach <ATTACHMENT_ID>`. The same validation can be attached to the same resource multiple times — directly, through different projects, through different plans, and even to the same resource and scope multiple times with different arguments.
|
||
|
||
**Arguments**
|
||
|
||
- `<RESOURCE>`: Resource name or ULID to attach the validation to (positional argument, required).
|
||
- `<VALIDATION>`: Validation name (positional argument, required).
|
||
- `--project PROJECT`: Scope the attachment to a specific project. The validation only runs for this resource when it is accessed through the specified project.
|
||
- `--plan PLAN_ID`: Scope the attachment to a specific plan. The validation only runs for this resource when it is accessed through the specified plan.
|
||
- `<ARGS>...`: Optional validation-specific arguments (passed through to the validation tool's `input_schema` at execution time).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach <span style="color: cyan;">--project</span> local/api-service local/api-repo local/run-tests
|
||
|
||
╭─ Validation Attached ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5A1B2C3D4E5F6G7H8J9K0 │
|
||
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> project local/api-service │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation attach --project local/api-service local/api-repo local/run-tests
|
||
|
||
Validation Attached
|
||
Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
Validation: local/run-tests
|
||
Mode: required
|
||
Resource: local/api-repo
|
||
Scope: project local/api-service
|
||
|
||
[OK] Validation attached
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation attach",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_attached": {
|
||
"attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0",
|
||
"validation": "local/run-tests",
|
||
"mode": "required",
|
||
"resource": "local/api-repo",
|
||
"scope": "project local/api-service"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 45 },
|
||
"messages": ["Validation attached"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation attach
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_attached:
|
||
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
validation: local/run-tests
|
||
mode: required
|
||
resource: local/api-repo
|
||
scope: project local/api-service
|
||
timing:
|
||
started: "2026-02-09T10:20:00Z"
|
||
duration_ms: 45
|
||
messages:
|
||
- "Validation attached"
|
||
```
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach local/api-repo local/lint-check
|
||
|
||
╭─ Validation Attached ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5B2C3D4E5F6G7H8J9K0L1 │
|
||
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/lint-check │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> direct (always active) │
|
||
│ <span style="opacity: 0.7;">This validation will run for ALL plans/projects</span> │
|
||
│ <span style="opacity: 0.7;">that access this resource.</span> │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation attach local/api-repo local/lint-check
|
||
|
||
Validation Attached
|
||
Attachment ID: 01HXM5B2C3D4E5F6G7H8J9K0L1
|
||
Validation: local/lint-check
|
||
Mode: required
|
||
Resource: local/api-repo
|
||
Scope: direct (always active)
|
||
This validation will run for ALL plans/projects
|
||
that access this resource.
|
||
|
||
[OK] Validation attached
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation attach",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_attached": {
|
||
"attachment_id": "01HXM5B2C3D4E5F6G7H8J9K0L1",
|
||
"validation": "local/lint-check",
|
||
"mode": "required",
|
||
"resource": "local/api-repo",
|
||
"scope": "direct (always active)",
|
||
"note": "This validation will run for ALL plans/projects that access this resource."
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:21:00Z", "duration_ms": 42 },
|
||
"messages": ["Validation attached"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation attach
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_attached:
|
||
attachment_id: 01HXM5B2C3D4E5F6G7H8J9K0L1
|
||
validation: local/lint-check
|
||
mode: required
|
||
resource: local/api-repo
|
||
scope: "direct (always active)"
|
||
note: "This validation will run for ALL plans/projects that access this resource."
|
||
timing:
|
||
started: "2026-02-09T10:21:00Z"
|
||
duration_ms: 42
|
||
messages:
|
||
- "Validation attached"
|
||
```
|
||
|
||
Attaching with validation-specific arguments:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation attach <span style="color: cyan;">--project</span> local/api-service local/api-repo local/run-tests <span style="color: cyan;">--coverage-threshold</span> 90
|
||
|
||
╭─ Validation Attached ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5C3D4E5F6G7H8J9K0L1M2 │
|
||
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> required │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Scope:</span> project local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Args:</span> coverage_threshold=90 │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation attached
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
|
||
|
||
Validation Attached
|
||
Attachment ID: 01HXM5C3D4E5F6G7H8J9K0L1M2
|
||
Validation: local/run-tests
|
||
Mode: required
|
||
Resource: local/api-repo
|
||
Scope: project local/api-service
|
||
Args: coverage_threshold=90
|
||
|
||
[OK] Validation attached
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation attach",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_attached": {
|
||
"attachment_id": "01HXM5C3D4E5F6G7H8J9K0L1M2",
|
||
"validation": "local/run-tests",
|
||
"mode": "required",
|
||
"resource": "local/api-repo",
|
||
"scope": "project local/api-service",
|
||
"args": {
|
||
"coverage_threshold": 90
|
||
}
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:22:00Z", "duration_ms": 48 },
|
||
"messages": ["Validation attached"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation attach
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_attached:
|
||
attachment_id: 01HXM5C3D4E5F6G7H8J9K0L1M2
|
||
validation: local/run-tests
|
||
mode: required
|
||
resource: local/api-repo
|
||
scope: project local/api-service
|
||
args:
|
||
coverage_threshold: 90
|
||
timing:
|
||
started: "2026-02-09T10:22:00Z"
|
||
duration_ms: 48
|
||
messages:
|
||
- "Validation attached"
|
||
```
|
||
|
||
##### agents validation detach
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> validation detach [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><ATTACHMENT_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Detach a validation by its attachment ULID. The attachment ULID is returned by `agents validation attach` when the attachment is created and is also displayed by `agents tool show <VALIDATION>` in the "Attached To" section. Because a validation may be attached to the same resource multiple times — directly, through different projects, through different plans, or even to the same resource and scope with different arguments — the ULID uniquely identifies the specific attachment to remove. The validation itself remains registered in the Tool Registry; only the attachment association is removed.
|
||
|
||
**Arguments**
|
||
|
||
- `<ATTACHMENT_ID>`: The ULID of the attachment to remove (returned by `agents validation attach`).
|
||
- `--yes, -y`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
|
||
Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
|
||
|
||
╭─ Validation Detached ───────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Attachment ID:</span> 01HXM5A1B2C3D4E5F6G7H8J9K0 │
|
||
│ <span style="color: cyan; font-weight: 600;">Validation:</span> local/run-tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> project local/api-service │
|
||
╰─────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Validation detached
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents validation detach 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
|
||
Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y
|
||
|
||
Validation Detached
|
||
Attachment ID: 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
Validation: local/run-tests
|
||
Resource: local/api-repo
|
||
Scope: project local/api-service
|
||
|
||
[OK] Validation detached
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "validation detach",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"validation_detached": {
|
||
"attachment_id": "01HXM5A1B2C3D4E5F6G7H8J9K0",
|
||
"validation": "local/run-tests",
|
||
"resource": "local/api-repo",
|
||
"scope": "project local/api-service"
|
||
},
|
||
"confirmation": "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y"
|
||
},
|
||
"timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 1200 },
|
||
"messages": ["Validation detached"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: validation detach
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
validation_detached:
|
||
attachment_id: 01HXM5A1B2C3D4E5F6G7H8J9K0
|
||
validation: local/run-tests
|
||
resource: local/api-repo
|
||
scope: project local/api-service
|
||
confirmation: "Detach validation local/run-tests from resource local/api-repo (scope: project local/api-service)? [y/N]: y"
|
||
timing:
|
||
started: "2026-02-09T10:25:00Z"
|
||
duration_ms: 1200
|
||
messages:
|
||
- "Validation detached"
|
||
```
|
||
|
||
#### agents resource type
|
||
|
||
**Purpose**
|
||
Manage resource type definitions. Resource types are schema-level definitions that constrain categories of resources — they define what CLI arguments `agents resource add <type>` accepts, whether instances are physical or virtual, allowed parent/child types, auto-discovery behavior, sandbox strategy, and handler implementation. Built-in types (`git-checkout`, `git`, `fs-mount`, `fs-directory`, and their child types) are hardcoded. Custom types are defined in YAML configuration files and extend the system with new `agents resource add` subcommands.
|
||
|
||
##### agents resource type add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource type add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new custom resource type. The resource type is fully defined by the YAML configuration file specified with `--config`.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: Path to the resource type YAML configuration file (required). The file must fully define the resource type, including the `name` field which determines the type's registered name.
|
||
- `--update`: If the type name already exists, overwrite it. Without this flag, adding a duplicate name fails with an error.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type add <span style="color: cyan;">--config</span> ./resource-types/svn.yaml
|
||
|
||
╭─ Resource Type ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/svn │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #5599ff; font-weight: 600;">User Addable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Registered:</span> 2026-02-09 10:15 │
|
||
╰────────────────────────────────────╯
|
||
|
||
╭─ CLI Arguments ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Argument</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">──────────── ──────── ─────────────</span> │
|
||
│ <span style="color: cyan;">--url</span> yes Repository URL │
|
||
│ <span style="color: cyan;">--checkout</span> no Local checkout │
|
||
╰────────────────────────────────────────╯
|
||
|
||
╭─ Child Types ──────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Auto-discover:</span> svn-revision, svn-file │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Manual link:</span> fs-mount │
|
||
╰────────────────────────────────────────╯
|
||
|
||
╭─ Sandbox ──────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> copy_on_write │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Handler:</span> SVNHandler (custom) │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type registered
|
||
<span style="color: cyan; font-weight: 600;">ℹ</span> New subcommand available: agents resource add local/svn
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource type add --config ./resource-types/svn.yaml
|
||
|
||
Resource Type
|
||
Name: local/svn
|
||
Physical/Virtual: physical
|
||
User Addable: yes
|
||
Registered: 2026-02-09 10:15
|
||
|
||
CLI Arguments
|
||
Argument Required Description
|
||
------------ -------- -------------
|
||
--url yes Repository URL
|
||
--checkout no Local checkout
|
||
|
||
Child Types
|
||
Auto-discover: svn-revision, svn-file
|
||
Manual link: fs-mount
|
||
|
||
Sandbox
|
||
Strategy: copy_on_write
|
||
Handler: SVNHandler (custom)
|
||
|
||
[OK] Resource type registered
|
||
Info: New subcommand available: agents resource add local/svn
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource type add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/svn",
|
||
"physical_virtual": "physical",
|
||
"user_addable": true,
|
||
"registered": "2026-02-09T10:15:00Z",
|
||
"cli_arguments": [
|
||
{ "argument": "--url", "required": true, "description": "Repository URL" },
|
||
{ "argument": "--checkout", "required": false, "description": "Local checkout" }
|
||
],
|
||
"child_types": {
|
||
"auto_discover": ["svn-revision", "svn-file"],
|
||
"manual_link": ["fs-mount"]
|
||
},
|
||
"sandbox": {
|
||
"strategy": "copy_on_write",
|
||
"handler": "SVNHandler (custom)"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 },
|
||
"messages": ["Resource type registered", "New subcommand available: agents resource add local/svn"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource type add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/svn
|
||
physical_virtual: physical
|
||
user_addable: true
|
||
registered: "2026-02-09T10:15:00Z"
|
||
cli_arguments:
|
||
- argument: "--url"
|
||
required: true
|
||
description: Repository URL
|
||
- argument: "--checkout"
|
||
required: false
|
||
description: Local checkout
|
||
child_types:
|
||
auto_discover:
|
||
- svn-revision
|
||
- svn-file
|
||
manual_link:
|
||
- fs-mount
|
||
sandbox:
|
||
strategy: copy_on_write
|
||
handler: "SVNHandler (custom)"
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 85
|
||
messages:
|
||
- "Resource type registered"
|
||
- "New subcommand available: agents resource add local/svn"
|
||
```
|
||
|
||
##### agents resource type remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource type remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! warning "Destructive Operation"
|
||
Remove a custom resource type. ==Built-in types cannot be removed.== Fails if any registered resources currently use this type — remove those resources first.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Resource type name.
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type remove local/svn
|
||
|
||
Remove resource type local/svn? [y/N]: y
|
||
|
||
╭─ Resource Type Removed ───────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/svn │
|
||
│ <span style="color: yellow; font-weight: 600;">Resources Using:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Subcommand Removed:</span> yes │
|
||
╰───────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource type remove local/svn
|
||
|
||
Remove resource type local/svn? [y/N]: y
|
||
|
||
Resource Type Removed
|
||
Name: local/svn
|
||
Resources Using: 0
|
||
Subcommand Removed: yes
|
||
|
||
[OK] Resource type removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource type remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/svn",
|
||
"resources_using": 0,
|
||
"subcommand_removed": true
|
||
},
|
||
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 60 },
|
||
"messages": ["Resource type removed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource type remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/svn
|
||
resources_using: 0
|
||
subcommand_removed: true
|
||
timing:
|
||
started: "2026-02-09T10:16:00Z"
|
||
duration_ms: 60
|
||
messages:
|
||
- "Resource type removed"
|
||
```
|
||
|
||
##### agents resource type list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource type list [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List all registered resource types (built-in and custom).
|
||
|
||
**Arguments**
|
||
|
||
None (use the global `--format` option to control output format).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type list
|
||
|
||
╭─ Resource Types ──────────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Phys/Virt</span> <span style="color: cyan; font-weight: 600;">Addable</span> <span style="color: cyan; font-weight: 600;">Auto-children</span> │
|
||
│ <span style="opacity: 0.7;">─────────────────── ──────── ───────── ─────── ──────────────────────────────────────</span> │
|
||
│ git-checkout built-in physical yes git, fs-directory │
|
||
│ git built-in physical yes git-remote, git-branch, git-tag, │
|
||
│ git-commit, git-stash, git-submodule │
|
||
│ git-remote built-in physical no (none) │
|
||
│ git-branch built-in physical no git-commit │
|
||
│ git-tag built-in physical no (none) │
|
||
│ git-commit built-in physical no git-tree │
|
||
│ git-tree built-in physical no git-tree-entry │
|
||
│ git-tree-entry built-in physical no (none) │
|
||
│ git-stash built-in physical no (none) │
|
||
│ git-submodule built-in physical no (none) │
|
||
│ fs-mount built-in physical yes fs-directory │
|
||
│ fs-directory built-in physical yes fs-file, fs-directory, │
|
||
│ fs-symlink, fs-hardlink │
|
||
│ fs-file built-in physical no (none) │
|
||
│ fs-symlink built-in physical no (none) │
|
||
│ fs-hardlink built-in physical no (none) │
|
||
│ file built-in virtual no (none) │
|
||
│ directory built-in virtual no (none) │
|
||
│ symlink built-in virtual no (none) │
|
||
│ commit built-in virtual no (none) │
|
||
│ branch built-in virtual no (none) │
|
||
│ tag built-in virtual no (none) │
|
||
│ remote built-in virtual no (none) │
|
||
│ submodule built-in virtual no (none) │
|
||
│ tree built-in virtual no (none) │
|
||
│ local/svn custom physical yes svn-revision, svn-file │
|
||
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Built-in:</span> 24 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">User Addable:</span> 4 │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 25 resource types listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource type list
|
||
|
||
Resource Types
|
||
-------------------
|
||
Name Source Phys/Virt Addable Auto-children
|
||
------------------- -------- --------- ------- --------------------------------------
|
||
git-checkout built-in physical yes git, fs-directory
|
||
git built-in physical yes git-remote, git-branch, git-tag, git-commit, git-stash, git-submodule
|
||
git-remote built-in physical no (none)
|
||
git-branch built-in physical no git-commit
|
||
git-tag built-in physical no (none)
|
||
git-commit built-in physical no git-tree
|
||
git-tree built-in physical no git-tree-entry
|
||
git-tree-entry built-in physical no (none)
|
||
git-stash built-in physical no (none)
|
||
git-submodule built-in physical no (none)
|
||
fs-mount built-in physical yes fs-directory
|
||
fs-directory built-in physical yes fs-file, fs-directory, fs-symlink, fs-hardlink
|
||
fs-file built-in physical no (none)
|
||
fs-symlink built-in physical no (none)
|
||
fs-hardlink built-in physical no (none)
|
||
file built-in virtual no (none)
|
||
directory built-in virtual no (none)
|
||
symlink built-in virtual no (none)
|
||
commit built-in virtual no (none)
|
||
branch built-in virtual no (none)
|
||
tag built-in virtual no (none)
|
||
remote built-in virtual no (none)
|
||
submodule built-in virtual no (none)
|
||
tree built-in virtual no (none)
|
||
local/svn custom physical yes svn-revision, svn-file
|
||
|
||
Summary
|
||
Built-in: 24
|
||
Custom: 1
|
||
User Addable: 4
|
||
|
||
[OK] 25 resource types listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource type list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource_types": [
|
||
{ "name": "git-checkout", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git", "fs-directory"] },
|
||
{ "name": "git", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["git-remote", "git-branch", "git-tag", "git-commit", "git-stash", "git-submodule"] },
|
||
{ "name": "git-remote", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "git-branch", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-commit"] },
|
||
{ "name": "git-tag", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "git-commit", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree"] },
|
||
{ "name": "git-tree", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": ["git-tree-entry"] },
|
||
{ "name": "git-tree-entry", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "git-stash", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "git-submodule", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "fs-mount", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-directory"] },
|
||
{ "name": "fs-directory", "source": "built-in", "physical_virtual": "physical", "addable": true, "auto_children": ["fs-file", "fs-directory", "fs-symlink", "fs-hardlink"] },
|
||
{ "name": "fs-file", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "fs-symlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "fs-hardlink", "source": "built-in", "physical_virtual": "physical", "addable": false, "auto_children": [] },
|
||
{ "name": "file", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "directory", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "symlink", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "commit", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "branch", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "tag", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "remote", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "submodule", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "tree", "source": "built-in", "physical_virtual": "virtual", "addable": false, "auto_children": [] },
|
||
{ "name": "local/svn", "source": "custom", "physical_virtual": "physical", "addable": true, "auto_children": ["svn-revision", "svn-file"] }
|
||
],
|
||
"summary": {
|
||
"built_in": 24,
|
||
"custom": 1,
|
||
"user_addable": 4
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:16:00Z", "duration_ms": 45 },
|
||
"messages": ["25 resource types listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource type list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource_types:
|
||
- name: git-checkout
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: true
|
||
auto_children: [git, fs-directory]
|
||
- name: git
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: true
|
||
auto_children: [git-remote, git-branch, git-tag, git-commit, git-stash, git-submodule]
|
||
- name: git-remote
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: git-branch
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: [git-commit]
|
||
- name: git-tag
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: git-commit
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: [git-tree]
|
||
- name: git-tree
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: [git-tree-entry]
|
||
- name: git-tree-entry
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: git-stash
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: git-submodule
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: fs-mount
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: true
|
||
auto_children: [fs-directory]
|
||
- name: fs-directory
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: true
|
||
auto_children: [fs-file, fs-directory, fs-symlink, fs-hardlink]
|
||
- name: fs-file
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: fs-symlink
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: fs-hardlink
|
||
source: built-in
|
||
physical_virtual: physical
|
||
addable: false
|
||
auto_children: []
|
||
- name: file
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: directory
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: symlink
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: commit
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: branch
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: tag
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: remote
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: submodule
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: tree
|
||
source: built-in
|
||
physical_virtual: virtual
|
||
addable: false
|
||
auto_children: []
|
||
- name: local/svn
|
||
source: custom
|
||
physical_virtual: physical
|
||
addable: true
|
||
auto_children: [svn-revision, svn-file]
|
||
summary:
|
||
built_in: 24
|
||
custom: 1
|
||
user_addable: 4
|
||
timing:
|
||
started: "2026-02-09T10:16:00Z"
|
||
duration_ms: 45
|
||
messages:
|
||
- "25 resource types listed"
|
||
```
|
||
|
||
##### agents resource type show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource type show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show detailed information about a resource type, including its full schema.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Resource type name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource type show git-checkout
|
||
|
||
╭─ Resource Type ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> git-checkout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> built-in │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> A locally checked-out git repository with worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">User Addable:</span> yes │
|
||
╰──────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ CLI Arguments (agents resource add git-checkout) ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Argument</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">────────── ──────── ────── ──────────────────────────────</span> │
|
||
│ <span style="color: cyan;">--path</span> yes path Local checkout directory │
|
||
│ <span style="color: cyan;">--branch</span> no string Default branch (default: main) │
|
||
╰────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Parent Types ───────────────╮
|
||
│ Allowed: (any, top-level OK) │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Child Types ────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Auto</span> <span style="color: cyan; font-weight: 600;">Manual Link</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">───────────── ──── ─────────── ──────────────────────────</span> │
|
||
│ git yes no Repo object DB and history │
|
||
│ fs-directory yes no Worktree root directory │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Sandbox ──────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpointable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Handler:</span> GitCheckoutHandler │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource type details loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource type show git-checkout
|
||
|
||
Resource Type
|
||
Name: git-checkout
|
||
Source: built-in
|
||
Description: A locally checked-out git repository with worktree
|
||
Physical/Virtual: physical
|
||
User Addable: yes
|
||
|
||
CLI Arguments (agents resource add git-checkout)
|
||
Argument Required Type Description
|
||
---------- -------- ------ ------------------------------
|
||
--path yes path Local checkout directory
|
||
--branch no string Default branch (default: main)
|
||
|
||
Parent Types
|
||
Allowed: (any, top-level OK)
|
||
|
||
Child Types
|
||
Type Auto Manual Link Description
|
||
------------- ---- ----------- --------------------------
|
||
git yes no Repo object DB and history
|
||
fs-directory yes no Worktree root directory
|
||
|
||
Sandbox
|
||
Strategy: git_worktree
|
||
Checkpointable: yes
|
||
Handler: GitCheckoutHandler
|
||
|
||
[OK] Resource type details loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource type show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "git-checkout",
|
||
"source": "built-in",
|
||
"description": "A locally checked-out git repository with worktree",
|
||
"physical_virtual": "physical",
|
||
"user_addable": true,
|
||
"cli_arguments": [
|
||
{ "argument": "--path", "required": true, "type": "path", "description": "Local checkout directory" },
|
||
{ "argument": "--branch", "required": false, "type": "string", "description": "Default branch (default: main)" }
|
||
],
|
||
"parent_types": {
|
||
"allowed": "any",
|
||
"top_level": true
|
||
},
|
||
"child_types": [
|
||
{ "type": "git", "auto": true, "manual_link": false, "description": "Repo object DB and history" },
|
||
{ "type": "fs-directory", "auto": true, "manual_link": false, "description": "Worktree root directory" }
|
||
],
|
||
"sandbox": {
|
||
"strategy": "git_worktree",
|
||
"checkpointable": true,
|
||
"handler": "GitCheckoutHandler"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 42 },
|
||
"messages": ["Resource type details loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource type show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: git-checkout
|
||
source: built-in
|
||
description: "A locally checked-out git repository with worktree"
|
||
physical_virtual: physical
|
||
user_addable: true
|
||
cli_arguments:
|
||
- argument: "--path"
|
||
required: true
|
||
type: path
|
||
description: "Local checkout directory"
|
||
- argument: "--branch"
|
||
required: false
|
||
type: string
|
||
description: "Default branch (default: main)"
|
||
parent_types:
|
||
allowed: any
|
||
top_level: true
|
||
child_types:
|
||
- type: git
|
||
auto: true
|
||
manual_link: false
|
||
description: "Repo object DB and history"
|
||
- type: fs-directory
|
||
auto: true
|
||
manual_link: false
|
||
description: "Worktree root directory"
|
||
sandbox:
|
||
strategy: git_worktree
|
||
checkpointable: true
|
||
handler: GitCheckoutHandler
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 42
|
||
messages:
|
||
- "Resource type details loaded"
|
||
```
|
||
|
||
#### agents resource
|
||
|
||
!!! info "Purpose"
|
||
Manage independently registered ==resources==. Resources represent anything that can be read, written, or queried — git repositories, filesystems, databases, APIs, and more. Resources are registered independently of projects and linked to one or more projects via `agents project link-resource`. Resources form a ==directed acyclic graph (DAG)== with parent/child relationships, and child resources are often auto-discovered when a parent resource is registered.
|
||
|
||
??? example "Supported Resource Types"
|
||
| Type | Physical | Description |
|
||
| :--- | :------: | :---------- |
|
||
| `git-checkout` | Yes | Local git working directory |
|
||
| `git` | Yes | Bare git repository |
|
||
| `fs-mount` | Yes | Filesystem mount point |
|
||
| `fs-directory` | Virtual | Directory within a mount |
|
||
| `fs-file` | Virtual | Individual file reference |
|
||
| `container-instance` | Yes | Container instance ([ADR-039](adr/ADR-039-container-resource-types.md)) |
|
||
| `devcontainer-instance` | Yes | Devcontainer instance ([ADR-043](adr/ADR-043-devcontainer-integration.md)) |
|
||
| Custom types | Varies | Registered via `agents resource type add` |
|
||
|
||
##### agents resource add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource add [(<span style="color: magenta;"><span style="color: cyan;">--description</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><DESC></span>] [<span style="color: cyan;">--update</span>] <span style="color: #66cc66;"><TYPE></span> <span style="color: #66cc66;"><NAME></span> [type-specific-flags...]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new resource. Every resource receives a system-assigned ULID. User-added resources also require a namespaced name (`[[server:]namespace/]name`) specified at creation time. The `add` command uses type-specific subcommands — each registered resource type (built-in or custom) provides its own subcommand with type-appropriate arguments. On success, the command returns both the name and the ULID assigned to the newly created resource.
|
||
|
||
**Arguments**
|
||
|
||
- `<TYPE>`: Resource type name (e.g., `git-checkout`, `git`, `fs-mount`, `fs-directory`, `local/svn`). Determines type-specific flags.
|
||
- `<NAME>`: Namespaced resource name (positional, required). Must be globally unique following the standard `[[server:]namespace/]name` format.
|
||
- `--description/-d TEXT`: Optional resource description.
|
||
|
||
Type-specific flags depend on the resource type. See `agents resource type show <TYPE>` for available arguments.
|
||
|
||
**Container-specific flags** (for `container-instance` and `devcontainer-instance` types):
|
||
|
||
- `--image IMAGE_REF`: Container image reference (e.g., `ubuntu:latest`, `python:3.12-slim`). Required for `container-instance` when `--container-id` is not provided. Not required for `devcontainer-instance` (image is derived from `devcontainer.json`).
|
||
- `--mount RESOURCE_OR_PATH:CONTAINER_PATH`: Mount a resource or host path into the container (repeatable). Accepts either a resource reference (`local/api-repo:/workspace`) or a raw host path (`/home/user/projects/api:/workspace`). See [ADR-043 §3.2](adr/ADR-043-devcontainer-integration.md).
|
||
- `--clone-into REPO_URL:CONTAINER_PATH`: Clone a remote repository into the container at the specified path. The clone happens lazily on first container start.
|
||
|
||
The command returns the name and ULID of the newly created resource. Auto-discovered child resources are created automatically with ULIDs only (no names).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/api-repo <span style="color: cyan;">--path</span> /home/user/projects/api-service <span style="color: cyan;">--branch</span> main
|
||
|
||
╭─ Resource ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR1A1B2C3D4E5F6G7H8J9K0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> main │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:20 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
╭─ Auto-discovered Children ─────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Status</span> │
|
||
│ <span style="opacity: 0.7;">─────────────── ────────────── ─────────────────</span> │
|
||
│ 01HXR1A1B2C3… git <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ 01HXR1A1B2C4… git-remote <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ 01HXR1A1B2C5… git-branch <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ 01HXR1A1B2C6… git-branch <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ 01HXR1A1B2C7… fs-directory <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ + 47 git-commit resources │
|
||
│ + 312 git-tree-entry resources │
|
||
│ + 3 fs-directory + 28 fs-file │
|
||
╰────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Capabilities ─────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
|
||
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> git_worktree │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (395 child resources discovered)
|
||
</code></pre></div>
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add fs-mount local/docs <span style="color: cyan;">--mount-path</span> /docs/api-reference
|
||
|
||
╭─ Resource ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/docs │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR2B3C4D5E6F7G8H9J0K1L2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> fs-mount │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Mount Path:</span> /docs/api-reference │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:22 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
╭─ Auto-discovered Children ────────────────────╮
|
||
│ + 1 fs-directory (root) │
|
||
│ + 3 fs-directory resources │
|
||
│ + 28 fs-file resources │
|
||
╰───────────────────────────────────────────────╯
|
||
|
||
╭─ Capabilities ──────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
|
||
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> copy_on_write │
|
||
╰─────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (31 child resources discovered)
|
||
</code></pre></div>
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance local/api-dev <span style="color: cyan;">--mount</span> local/api-repo:/workspace <span style="color: cyan;">--mount</span> /home/user/.config/nvim:/home/dev/.config/nvim
|
||
|
||
╭─ Resource ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-dev │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR3C4D5E6F7G8H9J0K1L2M3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:25 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
╭─ Mounts ──────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Container Path</span> <span style="color: cyan; font-weight: 600;">Kind</span> │
|
||
│ <span style="opacity: 0.7;">──────────────────────────────── ─────────────── ───────────</span> │
|
||
│ local/api-repo /workspace resource-ref │
|
||
│ /home/user/.config/nvim /home/dev/… host-path │
|
||
╰───────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered (container will start on first access)
|
||
</code></pre></div>
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add container-instance cloud/ci-runner <span style="color: cyan;">--clone-into</span> https://github.com/acme/api.git:/workspace
|
||
|
||
╭─ Resource ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> cloud/ci-runner │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR4D5E6F7G8H9J0K1L2M3N4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> container-instance │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">State:</span> created (not started) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Clone:</span> https://github.com/acme/api.git │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Clone Target:</span> /workspace │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:27 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Container resource registered (repo will be cloned on first start)
|
||
</code></pre></div>
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource add git-checkout local/webapp <span style="color: cyan;">--path</span> /home/user/projects/webapp
|
||
|
||
╭─ Resource ──────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/webapp │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR5E6F7G8H9J0K1L2M3N4O5 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/webapp │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Branch:</span> main │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:30 │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Auto-discovered Children ─────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Status</span> │
|
||
│ <span style="opacity: 0.7;">─────────────── ────────────────────── ───────────────────</span> │
|
||
│ 01HXR5E6F7G9… git <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ 01HXR5E6F7GA… <span style="color: yellow; font-weight: 600;">devcontainer-instance</span> <span style="color: yellow; font-weight: 600;">detected (not built)</span> │
|
||
│ 01HXR5E6F7GB… fs-directory <span style="color: #66cc66; font-weight: 600;">created</span> │
|
||
│ + 52 git-commit resources │
|
||
│ + 189 git-tree-entry resources │
|
||
╰────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: yellow; font-weight: 600;">⚠ Devcontainer detected</span> at .devcontainer/devcontainer.json
|
||
Container will be built lazily on first access.
|
||
Use <span style="color: cyan;">agents resource show</span> 01HXR5E6F7GA… to inspect.
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource registered (245 child resources discovered)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource add git-checkout local/api-repo --path /home/user/projects/api-service --branch main
|
||
|
||
Resource
|
||
Name: local/api-repo
|
||
ID: 01HXR1A1B2C3D4E5F6G7H8J9K0
|
||
Type: git-checkout
|
||
Physical/Virtual: physical
|
||
Path: /home/user/projects/api-service
|
||
Branch: main
|
||
Created: 2026-02-09 10:20
|
||
|
||
Auto-discovered Children
|
||
ID Type Status
|
||
--------------- -------------- -----------------
|
||
01HXR1A1B2C3.. git created
|
||
01HXR1A1B2C4.. git-remote created
|
||
01HXR1A1B2C5.. git-branch created
|
||
01HXR1A1B2C6.. git-branch created
|
||
01HXR1A1B2C7.. fs-directory created
|
||
+ 47 git-commit resources
|
||
+ 312 git-tree-entry resources
|
||
+ 3 fs-directory + 28 fs-file
|
||
|
||
Capabilities
|
||
Readable: yes
|
||
Writable: yes
|
||
Sandboxable: yes
|
||
Checkpointable: yes
|
||
Sandbox Strategy: git_worktree
|
||
|
||
[OK] Resource registered (395 child resources discovered)
|
||
|
||
$ agents resource add fs-mount local/docs --mount-path /docs/api-reference
|
||
|
||
Resource
|
||
Name: local/docs
|
||
ID: 01HXR2B3C4D5E6F7G8H9J0K1L2
|
||
Type: fs-mount
|
||
Physical/Virtual: physical
|
||
Mount Path: /docs/api-reference
|
||
Created: 2026-02-09 10:22
|
||
|
||
Auto-discovered Children
|
||
+ 1 fs-directory (root)
|
||
+ 3 fs-directory resources
|
||
+ 28 fs-file resources
|
||
|
||
Capabilities
|
||
Readable: yes
|
||
Writable: yes
|
||
Sandboxable: yes
|
||
Checkpointable: yes
|
||
Sandbox Strategy: copy_on_write
|
||
|
||
[OK] Resource registered (31 child resources discovered)
|
||
|
||
$ agents resource add container-instance local/api-dev --mount local/api-repo:/workspace --mount /home/user/.config/nvim:/home/dev/.config/nvim
|
||
|
||
Resource
|
||
Name: local/api-dev
|
||
ID: 01HXR3C4D5E6F7G8H9J0K1L2M3
|
||
Type: container-instance
|
||
Physical/Virtual: physical
|
||
State: created (not started)
|
||
Created: 2026-02-09 10:25
|
||
|
||
Mounts
|
||
Source Container Path Kind
|
||
-------------------------------- --------------- ---------
|
||
local/api-repo /workspace resource-ref
|
||
/home/user/.config/nvim /home/dev/... host-path
|
||
|
||
[OK] Container resource registered (container will start on first access)
|
||
|
||
$ agents resource add container-instance cloud/ci-runner --clone-into https://github.com/acme/api.git:/workspace
|
||
|
||
Resource
|
||
Name: cloud/ci-runner
|
||
ID: 01HXR4D5E6F7G8H9J0K1L2M3N4
|
||
Type: container-instance
|
||
Physical/Virtual: physical
|
||
State: created (not started)
|
||
Clone: https://github.com/acme/api.git
|
||
Clone Target: /workspace
|
||
Created: 2026-02-09 10:27
|
||
|
||
[OK] Container resource registered (repo will be cloned on first start)
|
||
|
||
$ agents resource add git-checkout local/webapp --path /home/user/projects/webapp
|
||
|
||
Resource
|
||
Name: local/webapp
|
||
ID: 01HXR5E6F7G8H9J0K1L2M3N4O5
|
||
Type: git-checkout
|
||
Physical/Virtual: physical
|
||
Path: /home/user/projects/webapp
|
||
Branch: main
|
||
Created: 2026-02-09 10:30
|
||
|
||
Auto-discovered Children
|
||
ID Type Status
|
||
--------------- ---------------------- -----------------
|
||
01HXR5E6F7G9.. git created
|
||
01HXR5E6F7GA.. devcontainer-instance detected (not built)
|
||
01HXR5E6F7GB.. fs-directory created
|
||
+ 52 git-commit resources
|
||
+ 189 git-tree-entry resources
|
||
|
||
[WARN] Devcontainer detected at .devcontainer/devcontainer.json
|
||
Container will be built lazily on first access.
|
||
Use agents resource show 01HXR5E6F7GA… to inspect.
|
||
|
||
[OK] Resource registered (245 child resources discovered)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/api-repo",
|
||
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
|
||
"type": "git-checkout",
|
||
"physical_virtual": "physical",
|
||
"path": "/home/user/projects/api-service",
|
||
"branch": "main",
|
||
"created": "2026-02-09T10:20:00Z",
|
||
"auto_discovered_children": [
|
||
{ "id": "01HXR1A1B2C3…", "type": "git", "status": "created" },
|
||
{ "id": "01HXR1A1B2C4…", "type": "git-remote", "status": "created" },
|
||
{ "id": "01HXR1A1B2C5…", "type": "git-branch", "status": "created" },
|
||
{ "id": "01HXR1A1B2C6…", "type": "git-branch", "status": "created" },
|
||
{ "id": "01HXR1A1B2C7…", "type": "fs-directory", "status": "created" }
|
||
],
|
||
"children_summary": {
|
||
"git_commit": 47,
|
||
"git_tree_entry": 312,
|
||
"fs_directory": 3,
|
||
"fs_file": 28
|
||
},
|
||
"total_children": 395,
|
||
"capabilities": {
|
||
"readable": true,
|
||
"writable": true,
|
||
"sandboxable": true,
|
||
"checkpointable": true,
|
||
"sandbox_strategy": "git_worktree"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:20:00Z", "duration_ms": 250 },
|
||
"messages": ["Resource registered (395 child resources discovered)"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/api-repo
|
||
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
|
||
type: git-checkout
|
||
physical_virtual: physical
|
||
path: /home/user/projects/api-service
|
||
branch: main
|
||
created: "2026-02-09T10:20:00Z"
|
||
auto_discovered_children:
|
||
- id: "01HXR1A1B2C3\u2026"
|
||
type: git
|
||
status: created
|
||
- id: "01HXR1A1B2C4\u2026"
|
||
type: git-remote
|
||
status: created
|
||
- id: "01HXR1A1B2C5\u2026"
|
||
type: git-branch
|
||
status: created
|
||
- id: "01HXR1A1B2C6\u2026"
|
||
type: git-branch
|
||
status: created
|
||
- id: "01HXR1A1B2C7\u2026"
|
||
type: fs-directory
|
||
status: created
|
||
children_summary:
|
||
git_commit: 47
|
||
git_tree_entry: 312
|
||
fs_directory: 3
|
||
fs_file: 28
|
||
total_children: 395
|
||
capabilities:
|
||
readable: true
|
||
writable: true
|
||
sandboxable: true
|
||
checkpointable: true
|
||
sandbox_strategy: git_worktree
|
||
timing:
|
||
started: "2026-02-09T10:20:00Z"
|
||
duration_ms: 250
|
||
messages:
|
||
- "Resource registered (395 child resources discovered)"
|
||
```
|
||
|
||
##### agents resource remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! danger "Cascading Deletion"
|
||
Removes a registered resource ==and all its auto-discovered child resources==. A `git-checkout` resource can have hundreds of child resources (files, directories). This operation fails if the resource is linked to any project — use `agents project unlink-resource` first.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Resource name (only user-added resources can be removed).
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource remove local/api-repo
|
||
|
||
Remove resource local/api-repo and 395 child resources? [y/N]: y
|
||
|
||
╭─ Resource Removed ──────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
│ <span style="color: yellow; font-weight: 600;">Children Removed:</span> 395 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Projects Unlinked:</span> 0 │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource remove local/api-repo
|
||
|
||
Remove resource local/api-repo and 395 child resources? [y/N]: y
|
||
|
||
Resource Removed
|
||
Name: local/api-repo
|
||
Type: git-checkout
|
||
Children Removed: 395
|
||
Projects Unlinked: 0
|
||
|
||
[OK] Resource removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/api-repo",
|
||
"type": "git-checkout",
|
||
"children_removed": 395,
|
||
"projects_unlinked": 0
|
||
},
|
||
"timing": { "started": "2026-02-09T10:24:00Z", "duration_ms": 120 },
|
||
"messages": ["Resource removed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/api-repo
|
||
type: git-checkout
|
||
children_removed: 395
|
||
projects_unlinked: 0
|
||
timing:
|
||
started: "2026-02-09T10:24:00Z"
|
||
duration_ms: 120
|
||
messages:
|
||
- "Resource removed"
|
||
```
|
||
|
||
##### agents resource list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource list [<span style="color: cyan;">--all</span>] [(<span style="color: magenta;"><span style="color: cyan;">--type</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TYPE></span>] </code></pre></div>
|
||
|
||
**Purpose**
|
||
List registered resources with optional filters. By default, lists only user-added (named) resources. Use `--all` to include auto-discovered child resources.
|
||
|
||
**Arguments**
|
||
|
||
- `--type/-t TYPE`: Filter by resource type (accepts a regex).
|
||
- `--all`: Include auto-discovered child resources (by default only user-added resources are shown).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource list
|
||
|
||
╭─ Resources ──────────────────────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Phys/Virt</span> <span style="color: cyan; font-weight: 600;">Children</span> <span style="color: cyan; font-weight: 600;">Projects</span> │
|
||
│ <span style="opacity: 0.7;">───────────────── ──────────────────────────── ─────────── ───────── ──────── ────────────────</span> │
|
||
│ local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service │
|
||
│ local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service │
|
||
│ local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, │
|
||
│ local/staging │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ───────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Virtual:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Children:</span> 405 │
|
||
╰─────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 resources listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource list
|
||
|
||
Resources
|
||
---------
|
||
Name ID Type Phys/Virt Children Projects
|
||
----------------- ---------------------------- ----------- --------- -------- ----------------
|
||
local/api-repo 01HXR1A1B2C3D4E5F6G7H8J9K0 git-checkout physical 395 local/api-service
|
||
local/docs 01HXR2B2C3D4E5F6G7H8J9K0L1 fs-mount physical 32 local/api-service
|
||
local/staging-db 01HXR3C3D4E5F6G7H8J9K0L1M2 database physical 12 local/api-service, local/staging
|
||
|
||
Summary
|
||
Total: 3
|
||
Physical: 3
|
||
Virtual: 0
|
||
Total Children: 405
|
||
|
||
[OK] 3 resources listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resources": [
|
||
{
|
||
"name": "local/api-repo",
|
||
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
|
||
"type": "git-checkout",
|
||
"physical_virtual": "physical",
|
||
"children": 395,
|
||
"projects": ["local/api-service"]
|
||
},
|
||
{
|
||
"name": "local/docs",
|
||
"id": "01HXR2B2C3D4E5F6G7H8J9K0L1",
|
||
"type": "fs-mount",
|
||
"physical_virtual": "physical",
|
||
"children": 32,
|
||
"projects": ["local/api-service"]
|
||
},
|
||
{
|
||
"name": "local/staging-db",
|
||
"id": "01HXR3C3D4E5F6G7H8J9K0L1M2",
|
||
"type": "database",
|
||
"physical_virtual": "physical",
|
||
"children": 12,
|
||
"projects": ["local/api-service", "local/staging"]
|
||
}
|
||
],
|
||
"summary": {
|
||
"total": 3,
|
||
"physical": 3,
|
||
"virtual": 0,
|
||
"total_children": 405
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:25:00Z", "duration_ms": 90 },
|
||
"messages": ["3 resources listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resources:
|
||
- name: local/api-repo
|
||
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
|
||
type: git-checkout
|
||
physical_virtual: physical
|
||
children: 395
|
||
projects:
|
||
- local/api-service
|
||
- name: local/docs
|
||
id: 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
type: fs-mount
|
||
physical_virtual: physical
|
||
children: 32
|
||
projects:
|
||
- local/api-service
|
||
- name: local/staging-db
|
||
id: 01HXR3C3D4E5F6G7H8J9K0L1M2
|
||
type: database
|
||
physical_virtual: physical
|
||
children: 12
|
||
projects:
|
||
- local/api-service
|
||
- local/staging
|
||
summary:
|
||
total: 3
|
||
physical: 3
|
||
virtual: 0
|
||
total_children: 405
|
||
timing:
|
||
started: "2026-02-09T10:25:00Z"
|
||
duration_ms: 90
|
||
messages:
|
||
- "3 resources listed"
|
||
```
|
||
|
||
##### agents resource show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource show <span style="color: #66cc66;"><RESOURCE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show detailed information about a registered resource including its type, capabilities, parent/child relationships, and linked projects.
|
||
|
||
**Arguments**
|
||
|
||
- `<RESOURCE>`: Resource name or ULID.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource show local/api-repo
|
||
|
||
╭─ Resource ─────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/api-repo │
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXR1A1B2C3D4E5F6G7H8J9K0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> git-checkout │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Physical/Virtual:</span> physical │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Path:</span> /home/user/projects/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> main │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-09 10:20 │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Capabilities ────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Readable:</span> yes │
|
||
│ <span style="color: yellow; font-weight: 600;">Writable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Sandboxable:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpointable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox Strategy:</span> git_worktree │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Parents ────╮
|
||
│ (top-level) │
|
||
╰──────────────╯
|
||
|
||
╭─ Direct Children ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Auto</span> <span style="color: cyan; font-weight: 600;">Children</span> │
|
||
│ <span style="opacity: 0.7;">──────────────────────────── ──────────── ──── ────────</span> │
|
||
│ 01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363 │
|
||
│ 01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32 │
|
||
╰────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Linked Projects ─────────────╮
|
||
│ - local/api-service (r/w) │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Tool Bindings ────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Tool</span> <span style="color: cyan; font-weight: 600;">Slot</span> <span style="color: cyan; font-weight: 600;">Access</span> │
|
||
│ <span style="opacity: 0.7;">──────────────────────── ───── ───────────</span> │
|
||
│ (builtin) git_status repo read_only │
|
||
│ (builtin) git_diff repo read_only │
|
||
│ (builtin) git_log repo read_only │
|
||
│ local/run-migrations db (not bound) │
|
||
╰────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource details loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource show local/api-repo
|
||
|
||
Resource
|
||
Name: local/api-repo
|
||
ID: 01HXR1A1B2C3D4E5F6G7H8J9K0
|
||
Type: git-checkout
|
||
Physical/Virtual: physical
|
||
Path: /home/user/projects/api-service
|
||
Branch: main
|
||
Created: 2026-02-09 10:20
|
||
|
||
Capabilities
|
||
Readable: yes
|
||
Writable: yes
|
||
Sandboxable: yes
|
||
Checkpointable: yes
|
||
Sandbox Strategy: git_worktree
|
||
|
||
Parents
|
||
(top-level)
|
||
|
||
Direct Children
|
||
ID Type Auto Children
|
||
---------------------------- ------------ ---- --------
|
||
01HXR4D4E5F6G7H8J9K0L1M2N3 git yes 363
|
||
01HXR5E5F6G7H8J9K0L1M2N3P4 fs-directory yes 32
|
||
|
||
Linked Projects
|
||
- local/api-service (r/w)
|
||
|
||
Tool Bindings
|
||
Tool Slot Access
|
||
------------------------ ----- -----------
|
||
(builtin) git_status repo read_only
|
||
(builtin) git_diff repo read_only
|
||
(builtin) git_log repo read_only
|
||
local/run-migrations db (not bound)
|
||
|
||
[OK] Resource details loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/api-repo",
|
||
"id": "01HXR1A1B2C3D4E5F6G7H8J9K0",
|
||
"type": "git-checkout",
|
||
"physical_virtual": "physical",
|
||
"path": "/home/user/projects/api-service",
|
||
"branch": "main",
|
||
"created": "2026-02-09T10:20:00Z",
|
||
"capabilities": {
|
||
"readable": true,
|
||
"writable": true,
|
||
"sandboxable": true,
|
||
"checkpointable": true,
|
||
"sandbox_strategy": "git_worktree"
|
||
},
|
||
"parents": ["(top-level)"],
|
||
"direct_children": [
|
||
{ "id": "01HXR4D4E5F6G7H8J9K0L1M2N3", "type": "git", "auto": true, "children": 363 },
|
||
{ "id": "01HXR5E5F6G7H8J9K0L1M2N3P4", "type": "fs-directory", "auto": true, "children": 32 }
|
||
],
|
||
"linked_projects": [
|
||
{ "name": "local/api-service", "access": "r/w" }
|
||
],
|
||
"tool_bindings": [
|
||
{ "tool": "(builtin) git_status", "slot": "repo", "access": "read_only" },
|
||
{ "tool": "(builtin) git_diff", "slot": "repo", "access": "read_only" },
|
||
{ "tool": "(builtin) git_log", "slot": "repo", "access": "read_only" },
|
||
{ "tool": "local/run-migrations", "slot": "db", "access": "(not bound)" }
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 65 },
|
||
"messages": ["Resource details loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/api-repo
|
||
id: 01HXR1A1B2C3D4E5F6G7H8J9K0
|
||
type: git-checkout
|
||
physical_virtual: physical
|
||
path: /home/user/projects/api-service
|
||
branch: main
|
||
created: "2026-02-09T10:20:00Z"
|
||
capabilities:
|
||
readable: true
|
||
writable: true
|
||
sandboxable: true
|
||
checkpointable: true
|
||
sandbox_strategy: git_worktree
|
||
parents:
|
||
- (top-level)
|
||
direct_children:
|
||
- id: 01HXR4D4E5F6G7H8J9K0L1M2N3
|
||
type: git
|
||
auto: true
|
||
children: 363
|
||
- id: 01HXR5E5F6G7H8J9K0L1M2N3P4
|
||
type: fs-directory
|
||
auto: true
|
||
children: 32
|
||
linked_projects:
|
||
- name: local/api-service
|
||
access: r/w
|
||
tool_bindings:
|
||
- tool: (builtin) git_status
|
||
slot: repo
|
||
access: read_only
|
||
- tool: (builtin) git_diff
|
||
slot: repo
|
||
access: read_only
|
||
- tool: (builtin) git_log
|
||
slot: repo
|
||
access: read_only
|
||
- tool: local/run-migrations
|
||
slot: db
|
||
access: (not bound)
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 65
|
||
messages:
|
||
- Resource details loaded
|
||
```
|
||
|
||
##### agents resource inspect
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource inspect [<span style="color: cyan;">--tree</span>] [<span style="color: cyan;">--file</span> <span style="color: #66cc66;"><PATH></span>] <span style="color: #66cc66;"><RESOURCE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Inspect a resource's contents. For file-based resources (git checkouts, filesystem mounts, directories), displays the file tree or the contents of a specific file. Works with any resource — user-added or auto-discovered — via name or ULID.
|
||
|
||
**Arguments**
|
||
|
||
- `<RESOURCE>`: Resource name or ULID.
|
||
- `--tree`: Show the resource's file/content tree.
|
||
- `--file PATH`: Show contents of a specific file within the resource.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource inspect local/api-repo <span style="color: cyan;">--tree</span>
|
||
|
||
╭─ Resource Tree: local/api-repo ──────────────────────────────────────╮
|
||
│ │
|
||
│ <span style="color: cyan; font-weight: 600;">/home/user/projects/api-service</span> │
|
||
│ ├── <span style="color: #5599ff; font-weight: 600;">src/</span> │
|
||
│ │ ├── <span style="color: #5599ff; font-weight: 600;">api/</span> │
|
||
│ │ │ ├── __init__.py │
|
||
│ │ │ ├── <span style="color: #5599ff; font-weight: 600;">auth/</span> │
|
||
│ │ │ │ ├── auth_middleware.py │
|
||
│ │ │ │ ├── token_service.py │
|
||
│ │ │ │ └── rbac.py │
|
||
│ │ │ ├── <span style="color: #5599ff; font-weight: 600;">routes/</span> │
|
||
│ │ │ └── <span style="color: #5599ff; font-weight: 600;">models/</span> │
|
||
│ │ └── <span style="color: #5599ff; font-weight: 600;">utils/</span> │
|
||
│ ├── <span style="color: #5599ff; font-weight: 600;">tests/</span> │
|
||
│ ├── README.md │
|
||
│ └── pyproject.toml │
|
||
│ │
|
||
╰──────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Directories:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Files:</span> 41 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Size:</span> 284 KB │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource tree displayed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource inspect local/api-repo --tree
|
||
|
||
Resource Tree: local/api-repo
|
||
|
||
/home/user/projects/api-service
|
||
+-- src/
|
||
| +-- api/
|
||
| | +-- __init__.py
|
||
| | +-- auth/
|
||
| | | +-- auth_middleware.py
|
||
| | | +-- token_service.py
|
||
| | | +-- rbac.py
|
||
| | +-- routes/
|
||
| | +-- models/
|
||
| +-- utils/
|
||
+-- tests/
|
||
+-- README.md
|
||
+-- pyproject.toml
|
||
|
||
Summary
|
||
Directories: 8
|
||
Files: 41
|
||
Total Size: 284 KB
|
||
|
||
[OK] Resource tree displayed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource inspect",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource": "local/api-repo",
|
||
"mode": "tree",
|
||
"root": "/home/user/projects/api-service",
|
||
"tree": [
|
||
{
|
||
"name": "src/",
|
||
"type": "directory",
|
||
"children": [
|
||
{
|
||
"name": "api/",
|
||
"type": "directory",
|
||
"children": [
|
||
{ "name": "__init__.py", "type": "file" },
|
||
{
|
||
"name": "auth/",
|
||
"type": "directory",
|
||
"children": [
|
||
{ "name": "auth_middleware.py", "type": "file" },
|
||
{ "name": "token_service.py", "type": "file" },
|
||
{ "name": "rbac.py", "type": "file" }
|
||
]
|
||
},
|
||
{ "name": "routes/", "type": "directory" },
|
||
{ "name": "models/", "type": "directory" }
|
||
]
|
||
},
|
||
{ "name": "utils/", "type": "directory" }
|
||
]
|
||
},
|
||
{ "name": "tests/", "type": "directory" },
|
||
{ "name": "README.md", "type": "file" },
|
||
{ "name": "pyproject.toml", "type": "file" }
|
||
],
|
||
"summary": {
|
||
"directories": 8,
|
||
"files": 41,
|
||
"total_size": "284 KB"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 150 },
|
||
"messages": ["Resource tree displayed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource inspect
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource: local/api-repo
|
||
mode: tree
|
||
root: /home/user/projects/api-service
|
||
tree:
|
||
- name: src/
|
||
type: directory
|
||
children:
|
||
- name: api/
|
||
type: directory
|
||
children:
|
||
- name: __init__.py
|
||
type: file
|
||
- name: auth/
|
||
type: directory
|
||
children:
|
||
- name: auth_middleware.py
|
||
type: file
|
||
- name: token_service.py
|
||
type: file
|
||
- name: rbac.py
|
||
type: file
|
||
- name: routes/
|
||
type: directory
|
||
- name: models/
|
||
type: directory
|
||
- name: utils/
|
||
type: directory
|
||
- name: tests/
|
||
type: directory
|
||
- name: README.md
|
||
type: file
|
||
- name: pyproject.toml
|
||
type: file
|
||
summary:
|
||
directories: 8
|
||
files: 41
|
||
total_size: 284 KB
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 150
|
||
messages:
|
||
- Resource tree displayed
|
||
```
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource inspect local/api-repo <span style="color: cyan;">--file</span> src/api/auth/auth_middleware.py
|
||
|
||
╭─ File: src/api/auth/auth_middleware.py ──────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Resource:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Size:</span> 2.4 KB │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Language:</span> Python │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Last Modified:</span> 2026-02-10 14:32 │
|
||
╰──────────────────────────────────────────────────────────╯
|
||
|
||
<span style="opacity: 0.7;"> 1</span> │ <span style="color: cyan;">from</span> fastapi <span style="color: cyan;">import</span> Request, HTTPException
|
||
<span style="opacity: 0.7;"> 2</span> │ <span style="color: cyan;">from</span> .token_service <span style="color: cyan;">import</span> validate_token
|
||
<span style="opacity: 0.7;"> 3</span> │
|
||
<span style="opacity: 0.7;"> 4</span> │ <span style="color: cyan;">async def</span> <span style="color: #66cc66;">auth_middleware</span>(request: Request):
|
||
<span style="opacity: 0.7;"> 5</span> │ token = request.headers.get(<span style="color: #66cc66;">"Authorization"</span>)
|
||
<span style="opacity: 0.7;"> 6</span> │ <span style="color: cyan;">if not</span> token:
|
||
<span style="opacity: 0.7;"> 7</span> │ <span style="color: cyan;">raise</span> HTTPException(status_code=<span style="color: yellow;">401</span>)
|
||
<span style="opacity: 0.7;"> 8</span> │ user = <span style="color: cyan;">await</span> validate_token(token)
|
||
<span style="opacity: 0.7;"> 9</span> │ request.state.user = user
|
||
<span style="opacity: 0.7;"> 10</span> │ <span style="color: cyan;">return</span> user
|
||
<span style="opacity: 0.7;"> </span> │ <span style="opacity: 0.5;">... (24 more lines)</span>
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> File displayed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource inspect local/api-repo --file src/api/auth/auth_middleware.py
|
||
|
||
File: src/api/auth/auth_middleware.py
|
||
Resource: local/api-repo
|
||
Size: 2.4 KB
|
||
Language: Python
|
||
Last Modified: 2026-02-10 14:32
|
||
|
||
1 | from fastapi import Request, HTTPException
|
||
2 | from .token_service import validate_token
|
||
3 |
|
||
4 | async def auth_middleware(request: Request):
|
||
5 | token = request.headers.get("Authorization")
|
||
6 | if not token:
|
||
7 | raise HTTPException(status_code=401)
|
||
8 | user = await validate_token(token)
|
||
9 | request.state.user = user
|
||
10 | return user
|
||
| ... (24 more lines)
|
||
|
||
[OK] File displayed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource inspect",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource": "local/api-repo",
|
||
"mode": "file",
|
||
"file": {
|
||
"path": "src/api/auth/auth_middleware.py",
|
||
"size": "2.4 KB",
|
||
"language": "Python",
|
||
"last_modified": "2026-02-10T14:32:00Z",
|
||
"lines_shown": 10,
|
||
"total_lines": 34,
|
||
"content": "from fastapi import Request, HTTPException\nfrom .token_service import validate_token\n\nasync def auth_middleware(request: Request):\n token = request.headers.get(\"Authorization\")\n if not token:\n raise HTTPException(status_code=401)\n user = await validate_token(token)\n request.state.user = user\n return user\n"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 30 },
|
||
"messages": ["File displayed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource inspect
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource: local/api-repo
|
||
mode: file
|
||
file:
|
||
path: src/api/auth/auth_middleware.py
|
||
size: 2.4 KB
|
||
language: Python
|
||
last_modified: "2026-02-10T14:32:00Z"
|
||
lines_shown: 10
|
||
total_lines: 34
|
||
content: |
|
||
from fastapi import Request, HTTPException
|
||
from .token_service import validate_token
|
||
|
||
async def auth_middleware(request: Request):
|
||
token = request.headers.get("Authorization")
|
||
if not token:
|
||
raise HTTPException(status_code=401)
|
||
user = await validate_token(token)
|
||
request.state.user = user
|
||
return user
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 30
|
||
messages:
|
||
- File displayed
|
||
```
|
||
|
||
##### agents resource tree
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource tree [(<span style="color: magenta;"><span style="color: cyan;">--depth</span>|<span style="color: yellow;">-d</span></span>) <span style="color: #66cc66;"><N></span>] [(<span style="color: magenta;"><span style="color: cyan;">--type</span>|<span style="color: yellow;">-t</span></span>) <span style="color: #66cc66;"><TYPE></span>] <span style="color: #66cc66;"><RESOURCE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Display the resource DAG as a tree starting from a given resource, showing parent/child relationships.
|
||
|
||
**Arguments**
|
||
|
||
- `<RESOURCE>`: Resource name or ULID.
|
||
- `--depth/-d N`: Maximum depth to display (default: 3).
|
||
- `--type/-t TYPE`: Filter to only show children of a specific type.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource tree local/api-repo <span style="color: cyan;">--depth</span> 2
|
||
|
||
╭─ Resource Tree: local/api-repo ─────────────────────────────────────╮
|
||
│ │
|
||
│ <span style="color: cyan; font-weight: 600;">git-checkout 01HXR1A1..J9K0</span> (physical) │
|
||
│ ├── <span style="color: #5599ff; font-weight: 600;">git 01HXR4D4..M2N3</span> (physical) │
|
||
│ │ ├── <span style="color: #5599ff; font-weight: 600;">git-remote 01HXR6F6..P4Q5</span> │
|
||
│ │ ├── <span style="color: magenta; font-weight: 600;">git-branch 01HXR7G7..Q5R6</span> │
|
||
│ │ │ ├── <span style="color: #66cc66; font-weight: 600;">git-commit 01HXR8H8..R6S7</span> │
|
||
│ │ │ └── <span style="opacity: 0.7;">... 22 more git-commit resources</span> │
|
||
│ │ └── <span style="color: magenta; font-weight: 600;">git-branch 01HXR9J9..S7T8</span> │
|
||
│ │ └── <span style="opacity: 0.7;">... 26 git-commit resources</span> │
|
||
│ └── <span style="color: #5599ff; font-weight: 600;">fs-directory 01HXR5E5..N3P4</span> (physical) │
|
||
│ ├── <span style="color: #66cc66; font-weight: 600;">fs-directory 01HXRAK1..T8U9</span> │
|
||
│ ├── <span style="color: #66cc66; font-weight: 600;">fs-directory 01HXRBL2..U9V0</span> │
|
||
│ └── <span style="opacity: 0.7;">... 28 more fs-file resources</span> │
|
||
│ │
|
||
╰─────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ──────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total shown:</span> 14 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total in subtree:</span> 395 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Max depth:</span> 2 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Resource tree displayed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource tree local/api-repo --depth 2
|
||
|
||
Resource Tree: local/api-repo
|
||
|
||
git-checkout 01HXR1A1..J9K0 (physical)
|
||
+-- git 01HXR4D4..M2N3 (physical)
|
||
| +-- git-remote 01HXR6F6..P4Q5
|
||
| +-- git-branch 01HXR7G7..Q5R6
|
||
| | +-- git-commit 01HXR8H8..R6S7
|
||
| | +-- ... 22 more git-commit resources
|
||
| +-- git-branch 01HXR9J9..S7T8
|
||
| +-- ... 26 git-commit resources
|
||
+-- fs-directory 01HXR5E5..N3P4 (physical)
|
||
+-- fs-directory 01HXRAK1..T8U9
|
||
+-- fs-directory 01HXRBL2..U9V0
|
||
+-- ... 28 more fs-file resources
|
||
|
||
Summary
|
||
Total shown: 14
|
||
Total in subtree: 395
|
||
Max depth: 2
|
||
|
||
[OK] Resource tree displayed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource tree",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"resource": "local/api-repo",
|
||
"max_depth": 2,
|
||
"tree": {
|
||
"type": "git-checkout",
|
||
"id": "01HXR1A1..J9K0",
|
||
"physical": true,
|
||
"children": [
|
||
{
|
||
"type": "git",
|
||
"id": "01HXR4D4..M2N3",
|
||
"physical": true,
|
||
"children": [
|
||
{ "type": "git-remote", "id": "01HXR6F6..P4Q5" },
|
||
{
|
||
"type": "git-branch",
|
||
"id": "01HXR7G7..Q5R6",
|
||
"children": [
|
||
{ "type": "git-commit", "id": "01HXR8H8..R6S7" },
|
||
"... 22 more git-commit resources"
|
||
]
|
||
},
|
||
{
|
||
"type": "git-branch",
|
||
"id": "01HXR9J9..S7T8",
|
||
"children": ["... 26 git-commit resources"]
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"type": "fs-directory",
|
||
"id": "01HXR5E5..N3P4",
|
||
"physical": true,
|
||
"children": [
|
||
{ "type": "fs-directory", "id": "01HXRAK1..T8U9" },
|
||
{ "type": "fs-directory", "id": "01HXRBL2..U9V0" },
|
||
"... 28 more fs-file resources"
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"summary": {
|
||
"total_shown": 14,
|
||
"total_in_subtree": 395,
|
||
"max_depth": 2
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 85 },
|
||
"messages": ["Resource tree displayed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource tree
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
resource: local/api-repo
|
||
max_depth: 2
|
||
tree:
|
||
type: git-checkout
|
||
id: 01HXR1A1..J9K0
|
||
physical: true
|
||
children:
|
||
- type: git
|
||
id: 01HXR4D4..M2N3
|
||
physical: true
|
||
children:
|
||
- type: git-remote
|
||
id: 01HXR6F6..P4Q5
|
||
- type: git-branch
|
||
id: 01HXR7G7..Q5R6
|
||
children:
|
||
- type: git-commit
|
||
id: 01HXR8H8..R6S7
|
||
- "... 22 more git-commit resources"
|
||
- type: git-branch
|
||
id: 01HXR9J9..S7T8
|
||
children:
|
||
- "... 26 git-commit resources"
|
||
- type: fs-directory
|
||
id: 01HXR5E5..N3P4
|
||
physical: true
|
||
children:
|
||
- type: fs-directory
|
||
id: 01HXRAK1..T8U9
|
||
- type: fs-directory
|
||
id: 01HXRBL2..U9V0
|
||
- "... 28 more fs-file resources"
|
||
summary:
|
||
total_shown: 14
|
||
total_in_subtree: 395
|
||
max_depth: 2
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 85
|
||
messages:
|
||
- Resource tree displayed
|
||
```
|
||
|
||
##### agents resource link-child
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource link-child <span style="color: #66cc66;"><PARENT></span> <span style="color: #66cc66;"><CHILD></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Manually link one resource as a child of another. The child resource must already be registered. The resource types must be compatible (the parent type must allow the child type). A resource can have multiple parents.
|
||
|
||
**Arguments**
|
||
|
||
- `<PARENT>`: Parent resource name or ULID.
|
||
- `<CHILD>`: Child resource name or ULID.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
|
||
╭─ Child Linked ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Parent:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child:</span> 01HXR2B2C3D4E5F6G7H8J9K0L1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child Type:</span> fs-mount │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> linked │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Child resource linked
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource link-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
|
||
Child Linked
|
||
Parent: local/api-repo
|
||
Child: 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
Child Type: fs-mount
|
||
Status: linked
|
||
|
||
[OK] Child resource linked
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource link-child",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"parent": "local/api-repo",
|
||
"child": "01HXR2B2C3D4E5F6G7H8J9K0L1",
|
||
"child_type": "fs-mount",
|
||
"status": "linked"
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 38 },
|
||
"messages": ["Child resource linked"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource link-child
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
parent: local/api-repo
|
||
child: 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
child_type: fs-mount
|
||
status: linked
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 38
|
||
messages:
|
||
- Child resource linked
|
||
```
|
||
|
||
##### agents resource unlink-child
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource unlink-child [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PARENT></span> <span style="color: #66cc66;"><CHILD></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Remove a manual parent/child link between two resources. Auto-discovered links cannot be manually unlinked.
|
||
|
||
**Arguments**
|
||
|
||
- `<PARENT>`: Parent resource name or ULID.
|
||
- `<CHILD>`: Child resource name or ULID.
|
||
- `--yes`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
|
||
Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
|
||
|
||
╭─ Child Unlinked ────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Parent:</span> local/api-repo │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child:</span> 01HXR2B2C3D4E5F6G7H8J9K0L1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> unlinked │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Child resource unlinked
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource unlink-child local/api-repo 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
|
||
Unlink 01HXR2B2C3D4E5F6G7H8J9K0L1 from parent local/api-repo? [y/N]: y
|
||
|
||
Child Unlinked
|
||
Parent: local/api-repo
|
||
Child: 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
Status: unlinked
|
||
|
||
[OK] Child resource unlinked
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "resource unlink-child",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"parent": "local/api-repo",
|
||
"child": "01HXR2B2C3D4E5F6G7H8J9K0L1",
|
||
"status": "unlinked"
|
||
},
|
||
"timing": { "started": "2026-02-09T10:15:00Z", "duration_ms": 45 },
|
||
"messages": ["Child resource unlinked"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: resource unlink-child
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
parent: local/api-repo
|
||
child: 01HXR2B2C3D4E5F6G7H8J9K0L1
|
||
status: unlinked
|
||
timing:
|
||
started: "2026-02-09T10:15:00Z"
|
||
duration_ms: 45
|
||
messages:
|
||
- Child resource unlinked
|
||
```
|
||
|
||
##### agents resource stop
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource stop <span style="color: #66cc66;"><NAME></span> [<span style="color: #66cc66;">--yes</span> | <span style="color: #66cc66;">-y</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Stop an active `devcontainer-instance` or `container-instance` resource. Transitions the container through `running → stopping → stopped`. Only container-typed resources may be stopped; attempting to stop other resource types produces an error.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Resource name or ULID of the devcontainer to stop.
|
||
|
||
**Options**
|
||
|
||
- `--yes` / `-y`: Skip the confirmation prompt (useful in scripts and automation).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource stop local/my-dc
|
||
|
||
Stopping container local/my-dc (state: running)...
|
||
<span style="color: #66cc66; font-weight: 600;">Stopped:</span> local/my-dc
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource stop local/my-dc
|
||
|
||
Stopping container local/my-dc (state: running)...
|
||
Stopped: local/my-dc
|
||
```
|
||
|
||
##### agents resource rebuild
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> resource rebuild <span style="color: #66cc66;"><NAME></span> [<span style="color: #66cc66;">--yes</span> | <span style="color: #66cc66;">-y</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Rebuild a stopped or failed `devcontainer-instance` resource. Transitions the container through `stopped/failed → building → running` by invoking `devcontainer up` with the resource's workspace location. Only `devcontainer-instance` resources may be rebuilt since the rebuild process invokes the devcontainer CLI; generic `container-instance` resources do not support rebuild.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Resource name or ULID of the devcontainer to rebuild.
|
||
|
||
**Options**
|
||
|
||
- `--yes` / `-y`: Skip the confirmation prompt (useful in scripts and automation).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> resource rebuild local/my-dc
|
||
|
||
Rebuilding local/my-dc...
|
||
<span style="color: #66cc66; font-weight: 600;">Rebuilt:</span> local/my-dc
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents resource rebuild local/my-dc
|
||
|
||
Rebuilding local/my-dc...
|
||
Rebuilt: local/my-dc
|
||
```
|
||
|
||
#### agents plan
|
||
|
||
!!! info "Purpose"
|
||
Manage ==plans== through the **Strategize → Execute → Apply** lifecycle (instantiated from Action templates).
|
||
|
||
??? abstract "Plan Lifecycle at a Glance"
|
||
```
|
||
Action ──use──▶ Strategize ──execute──▶ Execute ──apply──▶ Apply
|
||
▲ │ │
|
||
└──────────────────────┘ │
|
||
▲ (reversion) │
|
||
└────────────────────────────────────────┘
|
||
```
|
||
|
||
- [x] **Action** — Reusable template defining work, actors, and constraints
|
||
- [x] **Strategize** — Strategy actor produces a decision tree
|
||
- [x] **Execute** — Execution actor implements the strategy in a sandbox
|
||
- [x] **Apply** — Changeset is merged into real project resources
|
||
|
||
!!! note "Phase Reversion"
|
||
Both Execute and Apply can revert to Strategize when constraints are too restrictive. See `delete_content` and `access_network` automation profile flags.
|
||
|
||
##### agents plan list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan list [<span style="color: cyan;">--phase</span> <span style="color: #66cc66;"><PHASE></span>] [<span style="color: cyan;">--state</span> <span style="color: #66cc66;"><STATE></span>] [<span style="color: cyan;">--project</span> <span style="color: #66cc66;"><PROJECT></span>]
|
||
[<span style="color: cyan;">--action</span> <span style="color: #66cc66;"><ACTION></span>] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List plans with optional filtering.
|
||
|
||
**Arguments**
|
||
|
||
- `--phase PHASE`: Filter by phase.
|
||
- `--state STATE`: Filter by processing state.
|
||
- `--project PROJECT`: Filter by project.
|
||
- `--action ACTION`: Filter by action name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> <span style="color: cyan;">--format</span> table plan list <span style="color: cyan;">--phase</span> execute
|
||
|
||
╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
|
||
│ <span style="opacity: 0.7;">──────── ─────── ────────── ─────────────────── ───────────────── ─────────</span> │
|
||
│ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Filters ──────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: magenta; font-weight: 600;">State:</span> (any) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> (any) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> (any) │
|
||
╰────────────────╯
|
||
|
||
╭─ Summary ─────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 1 │
|
||
│ <span style="color: cyan; font-weight: 600;">Processing:</span> 1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Errored:</span> 0 │
|
||
╰───────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 plan listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents --format table plan list --phase execute
|
||
|
||
Plans
|
||
ID Phase State Action Project Elapsed
|
||
-------- ------- ---------- ------------------- ----------------- ---------
|
||
01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12
|
||
|
||
Filters
|
||
Phase: execute
|
||
State: (any)
|
||
Project: (any)
|
||
Action: (any)
|
||
|
||
Summary
|
||
Total: 1
|
||
Processing: 1
|
||
Completed: 0
|
||
Errored: 0
|
||
|
||
[OK] 1 plan listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plans": [
|
||
{
|
||
"id": "01HXM7A9",
|
||
"phase": "execute",
|
||
"state": "processing",
|
||
"action": "local/code-coverage",
|
||
"project": "local/api-service",
|
||
"elapsed": "00:01:12"
|
||
}
|
||
],
|
||
"filters": {
|
||
"phase": "execute",
|
||
"state": null,
|
||
"project": null,
|
||
"action": null
|
||
},
|
||
"summary": {
|
||
"total": 1,
|
||
"processing": 1,
|
||
"completed": 0,
|
||
"errored": 0
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
|
||
"messages": ["1 plan listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plans:
|
||
- id: "01HXM7A9"
|
||
phase: execute
|
||
state: processing
|
||
action: "local/code-coverage"
|
||
project: "local/api-service"
|
||
elapsed: "00:01:12"
|
||
filters:
|
||
phase: execute
|
||
state: null
|
||
project: null
|
||
action: null
|
||
summary:
|
||
total: 1
|
||
processing: 1
|
||
completed: 0
|
||
errored: 0
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 95
|
||
messages:
|
||
- "1 plan listed"
|
||
```
|
||
|
||
Listing all plans without filters shows plans across all phases and states:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan list
|
||
|
||
╭─ Plans ──────────────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
|
||
│ <span style="opacity: 0.7;">──────── ────────── ────────── ─────────────────── ───────────────── ─────────</span> │
|
||
│ 01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12 │
|
||
│ 01HXM6R3 <span style="color: #66cc66; font-weight: 600;">apply </span> <span style="color: #66cc66; font-weight: 600;">applied </span> local/add-auth local/api-service 00:07:14 │
|
||
│ 01HXM5K2 <span style="color: #ff6666; font-weight: 600;">execute</span> <span style="color: #ff6666; font-weight: 600;">errored</span> local/migrate-db local/api-service 00:04:33 │
|
||
│ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
|
||
│ 01HXM3H8 <span style="opacity: 0.5;">cancelled</span> <span style="opacity: 0.5;">cancelled</span> local/add-logging local/api-service 00:02:10 │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ─────────────╮
|
||
│ <span style="color: yellow;">Total:</span> 5 │
|
||
│ <span style="color: cyan; font-weight: 600;">Processing:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 1 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Errored:</span> 1 │
|
||
│ <span style="opacity: 0.5;">Cancelled:</span> 1 │
|
||
╰───────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 5 plans listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan list
|
||
|
||
Plans
|
||
ID Phase State Action Project Elapsed
|
||
-------- ---------- ---------- ------------------- ----------------- ---------
|
||
01HXM7A9 execute processing local/code-coverage local/api-service 00:01:12
|
||
01HXM6R3 apply applied local/add-auth local/api-service 00:07:14
|
||
01HXM5K2 execute errored local/migrate-db local/api-service 00:04:33
|
||
01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45
|
||
01HXM3H8 cancelled cancelled local/add-logging local/api-service 00:02:10
|
||
|
||
Summary
|
||
Total: 5
|
||
Processing: 2
|
||
Completed: 1
|
||
Errored: 1
|
||
Cancelled: 1
|
||
|
||
[OK] 5 plans listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plans": [
|
||
{ "id": "01HXM7A9", "phase": "execute", "state": "processing", "action": "local/code-coverage", "project": "local/api-service", "elapsed": "00:01:12" },
|
||
{ "id": "01HXM6R3", "phase": "apply", "state": "applied", "action": "local/add-auth", "project": "local/api-service", "elapsed": "00:07:14" },
|
||
{ "id": "01HXM5K2", "phase": "execute", "state": "errored", "action": "local/migrate-db", "project": "local/api-service", "elapsed": "00:04:33" },
|
||
{ "id": "01HXM4J1", "phase": "strategize", "state": "processing", "action": "local/refactor-api", "project": "local/web-app", "elapsed": "00:00:45" },
|
||
{ "id": "01HXM3H8", "phase": "cancelled", "state": "cancelled", "action": "local/add-logging", "project": "local/api-service", "elapsed": "00:02:10" }
|
||
],
|
||
"summary": {
|
||
"total": 5,
|
||
"processing": 2,
|
||
"completed": 1,
|
||
"errored": 1,
|
||
"cancelled": 1
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
|
||
"messages": ["5 plans listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plans:
|
||
- id: "01HXM7A9"
|
||
phase: execute
|
||
state: processing
|
||
action: "local/code-coverage"
|
||
project: "local/api-service"
|
||
elapsed: "00:01:12"
|
||
- id: "01HXM6R3"
|
||
phase: apply
|
||
state: applied
|
||
action: "local/add-auth"
|
||
project: "local/api-service"
|
||
elapsed: "00:07:14"
|
||
- id: "01HXM5K2"
|
||
phase: execute
|
||
state: errored
|
||
action: "local/migrate-db"
|
||
project: "local/api-service"
|
||
elapsed: "00:04:33"
|
||
- id: "01HXM4J1"
|
||
phase: strategize
|
||
state: processing
|
||
action: "local/refactor-api"
|
||
project: "local/web-app"
|
||
elapsed: "00:00:45"
|
||
- id: "01HXM3H8"
|
||
phase: cancelled
|
||
state: cancelled
|
||
action: "local/add-logging"
|
||
project: "local/api-service"
|
||
elapsed: "00:02:10"
|
||
summary:
|
||
total: 5
|
||
processing: 2
|
||
completed: 1
|
||
errored: 1
|
||
cancelled: 1
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 95
|
||
messages:
|
||
- "5 plans listed"
|
||
```
|
||
|
||
Filtering by project with `--project`:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan list <span style="color: cyan;">--project</span> local/web-app
|
||
|
||
╭─ Plans ──────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Action</span> <span style="color: cyan; font-weight: 600;">Project</span> <span style="color: cyan; font-weight: 600;">Elapsed</span> │
|
||
│ <span style="opacity: 0.7;">──────── ────────── ────────── ─────────────────── ───────────── ─────────</span> │
|
||
│ 01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45 │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Filters ─────────────────╮
|
||
│ <span style="color: yellow;">Phase:</span> (any) │
|
||
│ <span style="color: magenta; font-weight: 600;">State:</span> (any) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/web-app │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> (any) │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 plan listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan list --project local/web-app
|
||
|
||
Plans
|
||
ID Phase State Action Project Elapsed
|
||
-------- ---------- ---------- ------------------- ------------- ---------
|
||
01HXM4J1 strategize processing local/refactor-api local/web-app 00:00:45
|
||
|
||
Filters
|
||
Phase: (any)
|
||
State: (any)
|
||
Project: local/web-app
|
||
Action: (any)
|
||
|
||
[OK] 1 plan listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plans": [
|
||
{
|
||
"id": "01HXM4J1",
|
||
"phase": "strategize",
|
||
"state": "processing",
|
||
"action": "local/refactor-api",
|
||
"project": "local/web-app",
|
||
"elapsed": "00:00:45"
|
||
}
|
||
],
|
||
"filters": {
|
||
"phase": null,
|
||
"state": null,
|
||
"project": "local/web-app",
|
||
"action": null
|
||
},
|
||
"total": 1
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 85 },
|
||
"messages": ["1 plan listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plans:
|
||
- id: "01HXM4J1"
|
||
phase: strategize
|
||
state: processing
|
||
action: "local/refactor-api"
|
||
project: "local/web-app"
|
||
elapsed: "00:00:45"
|
||
filters:
|
||
phase: null
|
||
state: null
|
||
project: "local/web-app"
|
||
action: null
|
||
total: 1
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 85
|
||
messages:
|
||
- "1 plan listed"
|
||
```
|
||
|
||
##### agents plan use
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan use [<span style="color: cyan;">--automation-profile</span> <span style="color: #66cc66;"><PROFILE></span>]
|
||
[<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;"><INVARIANT></span>]...
|
||
[<span style="color: cyan;">--strategy-actor</span> <span style="color: #66cc66;"><STRATEGY_ACTOR></span>]
|
||
[<span style="color: cyan;">--execution-actor</span> <span style="color: #66cc66;"><EXEC_ACTOR></span>]
|
||
[<span style="color: cyan;">--estimation-actor</span> <span style="color: #66cc66;"><EST_ACTOR></span>]
|
||
[<span style="color: cyan;">--invariant-actor</span> <span style="color: #66cc66;"><INV_ACTOR></span>]
|
||
[<span style="color: cyan;">--execution-environment</span> <span style="color: #66cc66;"><RESOURCE_NAME></span>]
|
||
[<span style="color: cyan;">--execution-env-priority</span> (<span style="color: magenta;">fallback|override</span>)]
|
||
[<span style="color: cyan;">--arg</span>/<span style="color: yellow;">-a</span> name=value]...
|
||
<span style="color: #66cc66;"><ACTION></span> <span style="color: #66cc66;"><PROJECT></span>...</code></pre></div>
|
||
|
||
**Purpose**
|
||
Apply an action to one or more projects and start the Strategize phase.
|
||
|
||
**Arguments**
|
||
|
||
- `<ACTION_NAME>`: Action name.
|
||
- `<PROJECT>`: One or more project names (positional arguments, repeatable).
|
||
- `--arg/-a name=value`: Action argument (repeatable).
|
||
- `--automation-profile PROFILE`: Automation profile name (e.g., `trusted`, `auto`, `local/careful-auto`). Overrides the profile inherited from the action, project, or global config.
|
||
- `--strategy-actor ACTOR`: Override the action's strategy actor for this plan.
|
||
- `--execution-actor ACTOR`: Override the action's execution actor for this plan.
|
||
- `--estimation-actor ACTOR`: Override the action's estimation actor for this plan.
|
||
- `--invariant-actor ACTOR`: Override the action's Invariant Reconciliation Actor for this plan.
|
||
- `--invariant TEXT`: Invariant to attach to the created plan (repeatable). These are added as plan-level invariants in addition to any invariants inherited from the action, project, or global scope.
|
||
- `--execution-environment RESOURCE_NAME`: Name of a `container-instance` or `devcontainer-instance` resource to use as the execution environment for this plan. Overrides or supplements the project-level `execution_environment` setting depending on `--execution-env-priority`. See [ADR-043 §3.3](adr/ADR-043-devcontainer-integration.md).
|
||
- `--execution-env-priority fallback|override`: Priority semantics for the plan-level execution environment. `fallback` (default): defers to auto-detected devcontainers or project-level overrides. `override`: always uses the specified environment, bypassing all other resolution. See §Execution Environment Routing.
|
||
|
||
All actor arguments (`--strategy-actor`, `--execution-actor`, `--estimation-actor`, `--invariant-actor`) are optional overrides. When provided, they replace whatever was set when creating the action. When omitted, the action's configured actors are used.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/code-coverage local/api-service \
|
||
<span style="color: cyan;">--arg</span> target_coverage_percent=85 <span style="color: cyan;">--automation-profile</span> trusted
|
||
|
||
╭─ Plan Created ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan ID:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> strategize │
|
||
│ <span style="color: magenta; font-weight: 600;">Action:</span> local/code-coverage │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Automation:</span> trusted │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Inputs ──────────────────────╮
|
||
│ - target_coverage_percent=85 │
|
||
│ - automation_profile=trusted │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Actors ────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Strategy:</span> local/strategist │
|
||
│ <span style="color: magenta; font-weight: 600;">Execution:</span> local/executor │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimation:</span> (none) │
|
||
╰─────────────────────────────────╯
|
||
|
||
╭─ Automation ─────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Profile:</span> trusted │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> CLI flag │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read-Only:</span> no │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Context ───────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resources:</span> 2 (repo, db) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Indexed Files:</span> 347 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">View:</span> strategize │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Hot Token Budget:</span> 12,000 │
|
||
╰─────────────────────────────────╯
|
||
|
||
╭─ Next Steps ─────────────────────────────────────╮
|
||
│ - agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ - agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ - agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
╰──────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan use local/code-coverage local/api-service \
|
||
--arg target_coverage_percent=85 --automation-profile trusted
|
||
|
||
Plan Created
|
||
Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: strategize
|
||
Action: local/code-coverage
|
||
Project: local/api-service
|
||
Automation: trusted
|
||
Attempt: 1
|
||
|
||
Inputs
|
||
- target_coverage_percent=85
|
||
- automation_profile=trusted
|
||
|
||
Actors
|
||
Strategy: local/strategist
|
||
Execution: local/executor
|
||
Estimation: (none)
|
||
|
||
Automation
|
||
Profile: trusted
|
||
Source: CLI flag
|
||
Read-Only: no
|
||
|
||
Context
|
||
Resources: 2 (repo, db)
|
||
Indexed Files: 347
|
||
View: strategize
|
||
Hot Token Budget: 12,000
|
||
|
||
Next Steps
|
||
- agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
- agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
- agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
[OK] Plan created
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan use",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "strategize",
|
||
"action": "local/code-coverage",
|
||
"project": "local/api-service",
|
||
"automation_profile": "trusted",
|
||
"attempt": 1,
|
||
"inputs": {
|
||
"target_coverage_percent": 85,
|
||
"automation_profile": "trusted"
|
||
},
|
||
"actors": {
|
||
"strategy": "local/strategist",
|
||
"execution": "local/executor",
|
||
"estimation": null
|
||
},
|
||
"automation": {
|
||
"profile": "trusted",
|
||
"source": "CLI flag",
|
||
"read_only": false
|
||
},
|
||
"context": {
|
||
"resources": 2,
|
||
"indexed_files": 347,
|
||
"view": "strategize",
|
||
"hot_token_budget": 12000
|
||
},
|
||
"next_steps": [
|
||
"agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 95 },
|
||
"messages": ["Plan created"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan use
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: strategize
|
||
action: "local/code-coverage"
|
||
project: "local/api-service"
|
||
automation_profile: trusted
|
||
attempt: 1
|
||
inputs:
|
||
target_coverage_percent: 85
|
||
automation_profile: trusted
|
||
actors:
|
||
strategy: "local/strategist"
|
||
execution: "local/executor"
|
||
estimation: null
|
||
automation:
|
||
profile: trusted
|
||
source: "CLI flag"
|
||
read_only: false
|
||
context:
|
||
resources: 2
|
||
indexed_files: 347
|
||
view: strategize
|
||
hot_token_budget: 12000
|
||
next_steps:
|
||
- "agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
- "agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
- "agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 95
|
||
messages:
|
||
- "Plan created"
|
||
```
|
||
|
||
Applying an action to multiple projects simultaneously, with plan-level invariants:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/security-audit local/api-service local/web-app \
|
||
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"Never modify production database schemas"</span> \
|
||
<span style="color: cyan;">--invariant</span> <span style="color: #66cc66;">"All changes must include test coverage"</span> \
|
||
<span style="color: cyan;">--automation-profile</span> supervised
|
||
|
||
╭─ Plan Created ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9D2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/security-audit │
|
||
│ <span style="color: yellow;">Phase:</span> strategize (running) │
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> supervised │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Target Projects ───────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">1.</span> local/api-service (3 resources) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">2.</span> local/web-app (2 resources) │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Plan Invariants ──────────────────────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Scope</span> <span style="color: magenta; font-weight: 600;">Source</span> <span style="color: magenta; font-weight: 600;">Invariant</span> │
|
||
│ <span style="opacity: 0.7;">──────── ─────── ──────────────────────────────────</span> │
|
||
│ plan CLI Never modify production DB schemas │
|
||
│ plan CLI All changes must include test coverage │
|
||
│ project config API responses must be backward-compat │
|
||
│ global config Follow Python PEP 8 style guide │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created — strategize in progress
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan use local/security-audit local/api-service local/web-app \
|
||
--invariant "Never modify production database schemas" \
|
||
--invariant "All changes must include test coverage" \
|
||
--automation-profile supervised
|
||
|
||
Plan Created
|
||
Plan: 01HXM9D2ZK4Q7C2B3F2R4VYV6J
|
||
Action: local/security-audit
|
||
Phase: strategize (running)
|
||
Automation: supervised
|
||
|
||
Target Projects
|
||
1. local/api-service (3 resources)
|
||
2. local/web-app (2 resources)
|
||
|
||
Plan Invariants
|
||
Scope Source Invariant
|
||
-------- ------- ----------------------------------
|
||
plan CLI Never modify production DB schemas
|
||
plan CLI All changes must include test coverage
|
||
project config API responses must be backward-compat
|
||
global config Follow Python PEP 8 style guide
|
||
|
||
[OK] Plan created -- strategize in progress
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan use",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM9D2ZK4Q7C2B3F2R4VYV6J",
|
||
"action": "local/security-audit",
|
||
"phase": "strategize",
|
||
"phase_state": "running",
|
||
"automation_profile": "supervised",
|
||
"target_projects": [
|
||
{ "name": "local/api-service", "resources": 3 },
|
||
{ "name": "local/web-app", "resources": 2 }
|
||
],
|
||
"invariants": [
|
||
{ "scope": "plan", "source": "CLI", "text": "Never modify production DB schemas" },
|
||
{ "scope": "plan", "source": "CLI", "text": "All changes must include test coverage" },
|
||
{ "scope": "project", "source": "config", "text": "API responses must be backward-compat" },
|
||
{ "scope": "global", "source": "config", "text": "Follow Python PEP 8 style guide" }
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 130 },
|
||
"messages": ["Plan created -- strategize in progress"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan use
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM9D2ZK4Q7C2B3F2R4VYV6J"
|
||
action: "local/security-audit"
|
||
phase: strategize
|
||
phase_state: running
|
||
automation_profile: supervised
|
||
target_projects:
|
||
- name: "local/api-service"
|
||
resources: 3
|
||
- name: "local/web-app"
|
||
resources: 2
|
||
invariants:
|
||
- scope: plan
|
||
source: CLI
|
||
text: "Never modify production DB schemas"
|
||
- scope: plan
|
||
source: CLI
|
||
text: "All changes must include test coverage"
|
||
- scope: project
|
||
source: config
|
||
text: "API responses must be backward-compat"
|
||
- scope: global
|
||
source: config
|
||
text: "Follow Python PEP 8 style guide"
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 130
|
||
messages:
|
||
- "Plan created -- strategize in progress"
|
||
```
|
||
|
||
Using an action with custom actor overrides:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan use local/code-coverage local/api-service \
|
||
<span style="color: cyan;">--strategy-actor</span> local/senior-planner \
|
||
<span style="color: cyan;">--execution-actor</span> local/fast-executor \
|
||
<span style="color: cyan;">--arg</span> target_coverage_percent=95
|
||
|
||
╭─ Plan Created ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9E3ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/code-coverage │
|
||
│ <span style="color: yellow;">Phase:</span> strategize (running) │
|
||
│ <span style="color: magenta; font-weight: 600;">Automation:</span> trusted │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Actor Overrides ────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> local/senior-planner │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Execution:</span> local/fast-executor │
|
||
│ <span style="opacity: 0.7;">(Estimation: action default)</span> │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Arguments ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">target_coverage_percent:</span> 95 │
|
||
╰─────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan created — strategize in progress
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan use local/code-coverage local/api-service \
|
||
--strategy-actor local/senior-planner \
|
||
--execution-actor local/fast-executor \
|
||
--arg target_coverage_percent=95
|
||
|
||
Plan Created
|
||
Plan: 01HXM9E3ZK4Q7C2B3F2R4VYV6J
|
||
Action: local/code-coverage
|
||
Phase: strategize (running)
|
||
Automation: trusted
|
||
|
||
Actor Overrides
|
||
Strategy: local/senior-planner
|
||
Execution: local/fast-executor
|
||
(Estimation: action default)
|
||
|
||
Arguments
|
||
target_coverage_percent: 95
|
||
|
||
[OK] Plan created -- strategize in progress
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan use",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM9E3ZK4Q7C2B3F2R4VYV6J",
|
||
"action": "local/code-coverage",
|
||
"phase": "strategize",
|
||
"phase_state": "running",
|
||
"automation_profile": "trusted",
|
||
"actor_overrides": {
|
||
"strategy": "local/senior-planner",
|
||
"execution": "local/fast-executor",
|
||
"estimation": null
|
||
},
|
||
"arguments": {
|
||
"target_coverage_percent": 95
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 110 },
|
||
"messages": ["Plan created -- strategize in progress"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan use
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM9E3ZK4Q7C2B3F2R4VYV6J"
|
||
action: "local/code-coverage"
|
||
phase: strategize
|
||
phase_state: running
|
||
automation_profile: trusted
|
||
actor_overrides:
|
||
strategy: "local/senior-planner"
|
||
execution: "local/fast-executor"
|
||
estimation: null
|
||
arguments:
|
||
target_coverage_percent: 95
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 110
|
||
messages:
|
||
- "Plan created -- strategize in progress"
|
||
```
|
||
|
||
##### agents plan execute
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan execute <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Start or resume execution for a plan.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID (required).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Execution ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: magenta; font-weight: 600;">Sandbox:</span> git_worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Worker:</span> local/executor │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 12:58:10 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Sandbox ──────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /repos/api/.worktrees/plan-01HXM8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
|
||
╰────────────────────────────────────────────╯
|
||
|
||
╭─ Strategy Summary ─────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 8 │
|
||
│ <span style="color: magenta; font-weight: 600;">Invariants:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Planned Child Plans:</span> 2+ │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimated Files:</span> ~12 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Risk:</span> low │
|
||
╰────────────────────────────────────────╯
|
||
|
||
╭─ Progress ─────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">⏳</span> Collect context │
|
||
│ <span style="color: yellow; font-weight: 600;">•</span> Run tools │
|
||
│ <span style="color: yellow; font-weight: 600;">•</span> Build changeset │
|
||
│ <span style="color: yellow; font-weight: 600;">•</span> Validate │
|
||
╰────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution started
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Execution
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: execute
|
||
Sandbox: git_worktree
|
||
Worker: local/executor
|
||
Started: 12:58:10
|
||
Attempt: 1
|
||
|
||
Sandbox
|
||
Strategy: git_worktree
|
||
Path: /repos/api/.worktrees/plan-01HXM8
|
||
Branch: cleveragents/plan-01HXM8C2
|
||
Status: active
|
||
|
||
Strategy Summary
|
||
Decisions: 8
|
||
Invariants: 2
|
||
Planned Child Plans: 2+
|
||
Estimated Files: ~12
|
||
Risk: low
|
||
|
||
Progress
|
||
... Collect context
|
||
. Run tools
|
||
. Build changeset
|
||
. Validate
|
||
|
||
[OK] Execution started
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan execute",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"sandbox": {
|
||
"strategy": "git_worktree",
|
||
"path": "/repos/api/.worktrees/plan-01HXM8",
|
||
"branch": "cleveragents/plan-01HXM8C2",
|
||
"status": "active"
|
||
},
|
||
"worker": "local/executor",
|
||
"started": "12:58:10",
|
||
"attempt": 1,
|
||
"strategy_summary": {
|
||
"decisions": 8,
|
||
"invariants": 2,
|
||
"planned_child_plans": "2+",
|
||
"estimated_files": 12,
|
||
"risk": "low"
|
||
},
|
||
"progress": [
|
||
{ "label": "Collect context", "status": "running" },
|
||
{ "label": "Run tools", "status": "pending" },
|
||
{ "label": "Build changeset", "status": "pending" },
|
||
{ "label": "Validate", "status": "pending" }
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 150 },
|
||
"messages": ["Execution started"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan execute
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: execute
|
||
sandbox:
|
||
strategy: git_worktree
|
||
path: "/repos/api/.worktrees/plan-01HXM8"
|
||
branch: "cleveragents/plan-01HXM8C2"
|
||
status: active
|
||
worker: "local/executor"
|
||
started: "12:58:10"
|
||
attempt: 1
|
||
strategy_summary:
|
||
decisions: 8
|
||
invariants: 2
|
||
planned_child_plans: "2+"
|
||
estimated_files: 12
|
||
risk: low
|
||
progress:
|
||
- label: "Collect context"
|
||
status: running
|
||
- label: "Run tools"
|
||
status: pending
|
||
- label: "Build changeset"
|
||
status: pending
|
||
- label: "Validate"
|
||
status: pending
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 150
|
||
messages:
|
||
- "Execution started"
|
||
```
|
||
|
||
Resuming execution of a plan that was previously paused or errored:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Execution Resumed ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute (resumed) │
|
||
│ <span style="color: magenta; font-weight: 600;">Sandbox:</span> git_worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Worker:</span> local/executor │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (loaded) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Resumed From:</span> step 4 of 6 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Previous Progress ──────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 1: Collect context (0.8s) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 2: Analyze codebase (4.2s) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Step 3: Generate migrations (6.1s) │
|
||
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Step 4: Apply migrations (errored) │
|
||
│ <span style="opacity: 0.5;">○</span> Step 5: Update models (pending) │
|
||
│ <span style="opacity: 0.5;">○</span> Step 6: Run validations (pending) │
|
||
╰──────────────────────────────────────────╯
|
||
|
||
╭─ Guidance Applied ──────────────────────────────────────────────╮
|
||
│ <span style="opacity: 0.7;"><span style="color: #66cc66;">"Use smaller batch sizes for the migration to avoid timeouts"</span></span> │
|
||
╰─────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Execution resumed from checkpoint cp_01HXM8C2
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Execution Resumed
|
||
Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: execute (resumed)
|
||
Sandbox: git_worktree
|
||
Worker: local/executor
|
||
Checkpoint: cp_01HXM8C2 (loaded)
|
||
Resumed From: step 4 of 6
|
||
|
||
Previous Progress
|
||
v Step 1: Collect context (0.8s)
|
||
v Step 2: Analyze codebase (4.2s)
|
||
v Step 3: Generate migrations (6.1s)
|
||
x Step 4: Apply migrations (errored)
|
||
o Step 5: Update models (pending)
|
||
o Step 6: Run validations (pending)
|
||
|
||
Guidance Applied
|
||
"Use smaller batch sizes for the migration to avoid timeouts"
|
||
|
||
[OK] Execution resumed from checkpoint cp_01HXM8C2
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan execute",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"resumed": true,
|
||
"sandbox": "git_worktree",
|
||
"worker": "local/executor",
|
||
"checkpoint": "cp_01HXM8C2",
|
||
"resumed_from": "step 4 of 6",
|
||
"progress": [
|
||
{ "step": 1, "label": "Collect context", "status": "done", "duration_s": 0.8 },
|
||
{ "step": 2, "label": "Analyze codebase", "status": "done", "duration_s": 4.2 },
|
||
{ "step": 3, "label": "Generate migrations", "status": "done", "duration_s": 6.1 },
|
||
{ "step": 4, "label": "Apply migrations", "status": "errored" },
|
||
{ "step": 5, "label": "Update models", "status": "pending" },
|
||
{ "step": 6, "label": "Run validations", "status": "pending" }
|
||
],
|
||
"guidance": "Use smaller batch sizes for the migration to avoid timeouts"
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 180 },
|
||
"messages": ["Execution resumed from checkpoint cp_01HXM8C2"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan execute
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: execute
|
||
resumed: true
|
||
sandbox: git_worktree
|
||
worker: "local/executor"
|
||
checkpoint: "cp_01HXM8C2"
|
||
resumed_from: "step 4 of 6"
|
||
progress:
|
||
- step: 1
|
||
label: "Collect context"
|
||
status: done
|
||
duration_s: 0.8
|
||
- step: 2
|
||
label: "Analyze codebase"
|
||
status: done
|
||
duration_s: 4.2
|
||
- step: 3
|
||
label: "Generate migrations"
|
||
status: done
|
||
duration_s: 6.1
|
||
- step: 4
|
||
label: "Apply migrations"
|
||
status: errored
|
||
- step: 5
|
||
label: "Update models"
|
||
status: pending
|
||
- step: 6
|
||
label: "Run validations"
|
||
status: pending
|
||
guidance: "Use smaller batch sizes for the migration to avoid timeouts"
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 180
|
||
messages:
|
||
- "Execution resumed from checkpoint cp_01HXM8C2"
|
||
```
|
||
|
||
##### agents plan apply
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan apply [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Apply sandboxed changes to real resources.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID.
|
||
- `--yes`: Skip confirmation.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
|
||
|
||
╭─ Apply Summary ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Artifacts:</span> 6 files updated │
|
||
│ <span style="color: yellow; font-weight: 600;">Changes:</span> 42 insertions, 9 deletions │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Applied At:</span> 2026-02-08 13:04 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Validation (from Execute) ────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Tests:</span> passed (24/24) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Lint:</span> passed (0 warnings) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Type Check:</span> passed (0 errors) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Duration:</span> 12.4s │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Sandbox Cleanup ─────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Worktree:</span> removed │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Branch:</span> merged to main │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> archived │
|
||
╰───────────────────────────╯
|
||
|
||
╭─ Plan Lifecycle ────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Phase:</span> apply │
|
||
│ <span style="color: #66cc66; font-weight: 600;">State:</span> applied │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Duration:</span> 00:06:14 │
|
||
│ <span style="color: yellow; font-weight: 600;">Total Cost:</span> $0.0847 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 2 (completed) │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Next Steps ──────╮
|
||
│ - Review git diff │
|
||
│ - Commit changes │
|
||
╰───────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Changes applied
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Apply changes for plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J? [y/N]: y
|
||
|
||
Apply Summary
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Artifacts: 6 files updated
|
||
Changes: 42 insertions, 9 deletions
|
||
Project: local/api-service
|
||
Applied At: 2026-02-08 13:04
|
||
|
||
Validation (from Execute)
|
||
Tests: passed (24/24)
|
||
Lint: passed (0 warnings)
|
||
Type Check: passed (0 errors)
|
||
Duration: 12.4s
|
||
|
||
Sandbox Cleanup
|
||
Worktree: removed
|
||
Branch: merged to main
|
||
Checkpoint: archived
|
||
|
||
Plan Lifecycle
|
||
Phase: apply
|
||
State: applied
|
||
Total Duration: 00:06:14
|
||
Total Cost: $0.0847
|
||
Decisions Made: 8
|
||
Child Plans: 2 (completed)
|
||
|
||
Next Steps
|
||
- Review git diff
|
||
- Commit changes
|
||
|
||
[OK] Changes applied
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan apply",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"artifacts": 6,
|
||
"changes": {
|
||
"insertions": 42,
|
||
"deletions": 9
|
||
},
|
||
"project": "local/api-service",
|
||
"applied_at": "2026-02-08T13:04:00Z",
|
||
"validation": {
|
||
"tests": { "status": "passed", "passed": 24, "total": 24 },
|
||
"lint": { "status": "passed", "warnings": 0 },
|
||
"type_check": { "status": "passed", "errors": 0 },
|
||
"duration_s": 12.4
|
||
},
|
||
"sandbox_cleanup": {
|
||
"worktree": "removed",
|
||
"branch": "merged to main",
|
||
"checkpoint": "archived"
|
||
},
|
||
"lifecycle": {
|
||
"phase": "apply",
|
||
"state": "applied",
|
||
"total_duration": "00:06:14",
|
||
"total_cost": "$0.0847",
|
||
"decisions_made": 8,
|
||
"child_plans": 2
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 1250 },
|
||
"messages": ["Changes applied"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan apply
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
artifacts: 6
|
||
changes:
|
||
insertions: 42
|
||
deletions: 9
|
||
project: "local/api-service"
|
||
applied_at: "2026-02-08T13:04:00Z"
|
||
validation:
|
||
tests:
|
||
status: passed
|
||
passed: 24
|
||
total: 24
|
||
lint:
|
||
status: passed
|
||
warnings: 0
|
||
type_check:
|
||
status: passed
|
||
errors: 0
|
||
duration_s: 12.4
|
||
sandbox_cleanup:
|
||
worktree: removed
|
||
branch: merged to main
|
||
checkpoint: archived
|
||
lifecycle:
|
||
phase: apply
|
||
state: applied
|
||
total_duration: "00:06:14"
|
||
total_cost: "$0.0847"
|
||
decisions_made: 8
|
||
child_plans: 2
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 1250
|
||
messages:
|
||
- "Changes applied"
|
||
```
|
||
|
||
When Execute-phase validations failed and were not resolved (e.g., the execution actor exhausted its retry limit or failed outright), the plan cannot be applied. Apply checks the validation record and refuses to proceed:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan apply <span style="color: cyan;">--yes</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Apply Summary ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Artifacts:</span> 6 files updated │
|
||
│ <span style="color: yellow;">Changes:</span> 42 insertions, 9 deletions │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Validation ───────────────────────────────────────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Tests: <span style="color: #ff6666; font-weight: 600;">FAILED</span> (22/24 passed, 2 failed) │
|
||
│ <span style="opacity: 0.7;">FAIL test_auth.py::test_session_refresh — AssertionError</span> │
|
||
│ <span style="opacity: 0.7;">FAIL test_auth.py::test_token_expiry — TimeoutError</span> │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Lint: passed (0 warnings) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Type Check: passed (0 errors) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Duration:</span> 14.8s │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Sandbox Status ─────────────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Worktree:</span> preserved (changes NOT committed) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (pre-apply state available) │
|
||
│ <span style="opacity: 0.7;">The sandbox is preserved for correction or manual review.</span> │
|
||
╰──────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Recovery Options ──────────────────────────────────────────────────╮
|
||
│ - <span style="color: cyan;">agents plan prompt</span> <span style="opacity: 0.7;">— provide guidance to fix test failures</span> │
|
||
│ - <span style="color: cyan;">agents plan correct</span> <span style="opacity: 0.7;">— revert and re-execute with guidance</span> │
|
||
│ - <span style="color: cyan;">agents plan rollback</span> <span style="opacity: 0.7;">— restore to a previous checkpoint</span> │
|
||
│ - <span style="color: cyan;">agents plan cancel</span> <span style="opacity: 0.7;">— abort the plan entirely</span> │
|
||
╰─────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Apply refused — 2 required Execute-phase validations did not pass
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan apply --yes 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Apply Summary
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Artifacts: 6 files updated
|
||
Changes: 42 insertions, 9 deletions
|
||
Project: local/api-service
|
||
|
||
Validation
|
||
x Tests: FAILED (22/24 passed, 2 failed)
|
||
FAIL test_auth.py::test_session_refresh -- AssertionError
|
||
FAIL test_auth.py::test_token_expiry -- TimeoutError
|
||
v Lint: passed (0 warnings)
|
||
v Type Check: passed (0 errors)
|
||
Duration: 14.8s
|
||
|
||
Sandbox Status
|
||
Worktree: preserved (changes NOT committed)
|
||
Checkpoint: cp_01HXM8C2 (pre-apply state available)
|
||
The sandbox is preserved for correction or manual review.
|
||
|
||
Recovery Options
|
||
- agents plan prompt -- provide guidance to fix test failures
|
||
- agents plan correct -- revert and re-execute with guidance
|
||
- agents plan rollback -- restore to a previous checkpoint
|
||
- agents plan cancel -- abort the plan entirely
|
||
|
||
[ERROR] Apply refused -- 2 required Execute-phase validations did not pass
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan apply",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"artifacts": 6,
|
||
"changes": {
|
||
"insertions": 42,
|
||
"deletions": 9
|
||
},
|
||
"project": "local/api-service",
|
||
"validation": {
|
||
"tests": {
|
||
"status": "failed",
|
||
"passed": 22,
|
||
"total": 24,
|
||
"failures": [
|
||
"test_auth.py::test_session_refresh -- AssertionError",
|
||
"test_auth.py::test_token_expiry -- TimeoutError"
|
||
]
|
||
},
|
||
"lint": { "status": "passed", "warnings": 0 },
|
||
"type_check": { "status": "passed", "errors": 0 },
|
||
"duration_s": 14.8
|
||
},
|
||
"sandbox": {
|
||
"worktree": "preserved",
|
||
"checkpoint": "cp_01HXM8C2"
|
||
},
|
||
"recovery_options": [
|
||
"agents plan prompt",
|
||
"agents plan correct",
|
||
"agents plan rollback",
|
||
"agents plan cancel"
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-09T14:30:00Z", "duration_ms": 320 },
|
||
"messages": ["Apply refused -- 2 required Execute-phase validations did not pass"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan apply
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
artifacts: 6
|
||
changes:
|
||
insertions: 42
|
||
deletions: 9
|
||
project: "local/api-service"
|
||
validation:
|
||
tests:
|
||
status: failed
|
||
passed: 22
|
||
total: 24
|
||
failures:
|
||
- "test_auth.py::test_session_refresh -- AssertionError"
|
||
- "test_auth.py::test_token_expiry -- TimeoutError"
|
||
lint:
|
||
status: passed
|
||
warnings: 0
|
||
type_check:
|
||
status: passed
|
||
errors: 0
|
||
duration_s: 14.8
|
||
sandbox:
|
||
worktree: preserved
|
||
checkpoint: "cp_01HXM8C2"
|
||
recovery_options:
|
||
- "agents plan prompt"
|
||
- "agents plan correct"
|
||
- "agents plan rollback"
|
||
- "agents plan cancel"
|
||
timing:
|
||
started: "2026-02-09T14:30:00Z"
|
||
duration_ms: 320
|
||
messages:
|
||
- "Apply refused -- 2 required Execute-phase validations did not pass"
|
||
```
|
||
|
||
##### agents plan status
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan status <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show detailed status for a plan.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID (required).
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Plan Status ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: magenta; font-weight: 600;">State:</span> processing │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/code-coverage │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> review │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Progress ───────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
|
||
│ <span style="color: cyan; font-weight: 600;">⏳</span> Execute │
|
||
│ <span style="color: yellow; font-weight: 600;">•</span> Apply (queued) │
|
||
╰──────────────────╯
|
||
|
||
╭─ Timing ──────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 12:57:01 │
|
||
│ <span style="color: yellow; font-weight: 600;">Elapsed:</span> 00:01:12 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 00:03:45 │
|
||
╰───────────────────╯
|
||
|
||
╭─ Execution Detail ──────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> git_worktree │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Files Modified:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 1/2 complete │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> 2 created │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Cost ───────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tokens Used:</span> 12,420 │
|
||
│ <span style="color: yellow; font-weight: 600;">Cost So Far:</span> $0.041 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Estimated:</span> $0.085 │
|
||
╰──────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Status refreshed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Plan Status
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: execute
|
||
State: processing
|
||
Action: local/code-coverage
|
||
Project: local/api-service
|
||
Automation: review
|
||
Attempt: 1
|
||
|
||
Progress
|
||
[OK] Strategize
|
||
... Execute
|
||
. Apply (queued)
|
||
|
||
Timing
|
||
Started: 12:57:01
|
||
Elapsed: 00:01:12
|
||
ETA: 00:03:45
|
||
|
||
Execution Detail
|
||
Sandbox: git_worktree
|
||
Tool Calls: 8
|
||
Files Modified: 3
|
||
Child Plans: 1/2 complete
|
||
Checkpoints: 2 created
|
||
|
||
Cost
|
||
Tokens Used: 12,420
|
||
Cost So Far: $0.041
|
||
Estimated: $0.085
|
||
|
||
[OK] Status refreshed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan status",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"state": "processing",
|
||
"action": "local/code-coverage",
|
||
"project": "local/api-service",
|
||
"automation": "review",
|
||
"attempt": 1,
|
||
"progress": [
|
||
{ "step": "Strategize", "status": "done" },
|
||
{ "step": "Execute", "status": "running" },
|
||
{ "step": "Apply", "status": "queued" }
|
||
],
|
||
"timing": {
|
||
"started": "12:57:01",
|
||
"elapsed": "00:01:12",
|
||
"eta": "00:03:45"
|
||
},
|
||
"execution": {
|
||
"sandbox": "git_worktree",
|
||
"tool_calls": 8,
|
||
"files_modified": 3,
|
||
"child_plans": "1/2 complete",
|
||
"checkpoints": 2
|
||
},
|
||
"cost": {
|
||
"tokens_used": 12420,
|
||
"cost_so_far": 0.041,
|
||
"estimated": 0.085
|
||
}
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:57:01Z",
|
||
"duration_ms": 120
|
||
},
|
||
"messages": ["Status refreshed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan status
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: execute
|
||
state: processing
|
||
action: local/code-coverage
|
||
project: local/api-service
|
||
automation: review
|
||
attempt: 1
|
||
progress:
|
||
- step: Strategize
|
||
status: done
|
||
- step: Execute
|
||
status: running
|
||
- step: Apply
|
||
status: queued
|
||
timing:
|
||
started: "12:57:01"
|
||
elapsed: "00:01:12"
|
||
eta: "00:03:45"
|
||
execution:
|
||
sandbox: git_worktree
|
||
tool_calls: 8
|
||
files_modified: 3
|
||
child_plans: "1/2 complete"
|
||
checkpoints: 2
|
||
cost:
|
||
tokens_used: 12420
|
||
cost_so_far: 0.041
|
||
estimated: 0.085
|
||
timing:
|
||
started: "2026-02-08T12:57:01Z"
|
||
duration_ms: 120
|
||
messages:
|
||
- "Status refreshed"
|
||
```
|
||
|
||
Status of a plan that has completed successfully:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Plan Status ─────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM6R3ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Phase:</span> apply │
|
||
│ <span style="color: #66cc66; font-weight: 600;">State:</span> applied │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/add-auth │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> trusted │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Progress ───────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Execute │
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Apply (committed) │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Timing ─────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Started:</span> 2026-02-08 12:57:01 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Finished:</span> 2026-02-08 13:04:15 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Duration:</span> 00:07:14 │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Result ────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child Plans:</span> 2/2 complete │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Artifacts:</span> 6 files updated │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Validations:</span> 3/3 passed │
|
||
│ <span style="color: yellow;">Total Cost:</span> $0.085 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan completed successfully
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan status 01HXM6R3ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Plan Status
|
||
Plan: 01HXM6R3ZK4Q7C2B3F2R4VYV6J
|
||
Phase: apply
|
||
State: applied
|
||
Action: local/add-auth
|
||
Project: local/api-service
|
||
Automation: trusted
|
||
Attempt: 1
|
||
|
||
Progress
|
||
[OK] Strategize
|
||
[OK] Execute
|
||
[OK] Apply (committed)
|
||
|
||
Timing
|
||
Started: 2026-02-08 12:57:01
|
||
Finished: 2026-02-08 13:04:15
|
||
Total Duration: 00:07:14
|
||
|
||
Result
|
||
Decisions Made: 8
|
||
Child Plans: 2/2 complete
|
||
Artifacts: 6 files updated
|
||
Validations: 3/3 passed
|
||
Total Cost: $0.085
|
||
|
||
[OK] Plan completed successfully
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan status",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM6R3ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "apply",
|
||
"state": "applied",
|
||
"action": "local/add-auth",
|
||
"project": "local/api-service",
|
||
"automation": "trusted",
|
||
"attempt": 1,
|
||
"progress": [
|
||
{ "step": "Strategize", "status": "done" },
|
||
{ "step": "Execute", "status": "done" },
|
||
{ "step": "Apply", "status": "committed" }
|
||
],
|
||
"timing": {
|
||
"started": "2026-02-08T12:57:01Z",
|
||
"finished": "2026-02-08T13:04:15Z",
|
||
"total_duration": "00:07:14"
|
||
},
|
||
"result": {
|
||
"decisions_made": 8,
|
||
"child_plans": "2/2 complete",
|
||
"artifacts": "6 files updated",
|
||
"validations": "3/3 passed",
|
||
"total_cost": 0.085
|
||
}
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:57:01Z",
|
||
"duration_ms": 434000
|
||
},
|
||
"messages": ["Plan completed successfully"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan status
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM6R3ZK4Q7C2B3F2R4VYV6J"
|
||
phase: apply
|
||
state: applied
|
||
action: local/add-auth
|
||
project: local/api-service
|
||
automation: trusted
|
||
attempt: 1
|
||
progress:
|
||
- step: Strategize
|
||
status: done
|
||
- step: Execute
|
||
status: done
|
||
- step: Apply
|
||
status: committed
|
||
timing:
|
||
started: "2026-02-08T12:57:01Z"
|
||
finished: "2026-02-08T13:04:15Z"
|
||
total_duration: "00:07:14"
|
||
result:
|
||
decisions_made: 8
|
||
child_plans: "2/2 complete"
|
||
artifacts: "6 files updated"
|
||
validations: "3/3 passed"
|
||
total_cost: 0.085
|
||
timing:
|
||
started: "2026-02-08T12:57:01Z"
|
||
duration_ms: 434000
|
||
messages:
|
||
- "Plan completed successfully"
|
||
```
|
||
|
||
Status of a plan in the strategize phase:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Plan Status ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM9F2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow;">Phase:</span> strategize │
|
||
│ <span style="color: magenta; font-weight: 600;">State:</span> processing │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/refactor-auth │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> supervised │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Progress ───────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">⏳</span> Strategize (running) │
|
||
│ <span style="opacity: 0.5;">○</span> Execute (waiting) │
|
||
│ <span style="opacity: 0.5;">○</span> Apply (waiting) │
|
||
╰──────────────────────────╯
|
||
|
||
╭─ Strategy Progress ────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions Made:</span> 4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Invariants Enforced:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child Plans Planned:</span> 3 │
|
||
│ <span style="color: yellow;">Elapsed:</span> 00:00:28 │
|
||
╰────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Strategize in progress
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan status 01HXM9F2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Plan Status
|
||
Plan: 01HXM9F2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: strategize
|
||
State: processing
|
||
Action: local/refactor-auth
|
||
Project: local/api-service
|
||
Automation: supervised
|
||
|
||
Progress
|
||
... Strategize (running)
|
||
o Execute (waiting)
|
||
o Apply (waiting)
|
||
|
||
Strategy Progress
|
||
Decisions Made: 4
|
||
Invariants Enforced: 2
|
||
Child Plans Planned: 3
|
||
Elapsed: 00:00:28
|
||
|
||
[OK] Strategize in progress
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan status",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM9F2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "strategize",
|
||
"state": "processing",
|
||
"action": "local/refactor-auth",
|
||
"project": "local/api-service",
|
||
"automation": "supervised",
|
||
"progress": [
|
||
{ "step": "Strategize", "status": "running" },
|
||
{ "step": "Execute", "status": "waiting" },
|
||
{ "step": "Apply", "status": "waiting" }
|
||
],
|
||
"strategy_progress": {
|
||
"decisions_made": 4,
|
||
"invariants_enforced": 2,
|
||
"child_plans_planned": 3,
|
||
"elapsed": "00:00:28"
|
||
}
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:57:01Z",
|
||
"duration_ms": 28000
|
||
},
|
||
"messages": ["Strategize in progress"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan status
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM9F2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: strategize
|
||
state: processing
|
||
action: local/refactor-auth
|
||
project: local/api-service
|
||
automation: supervised
|
||
progress:
|
||
- step: Strategize
|
||
status: running
|
||
- step: Execute
|
||
status: waiting
|
||
- step: Apply
|
||
status: waiting
|
||
strategy_progress:
|
||
decisions_made: 4
|
||
invariants_enforced: 2
|
||
child_plans_planned: 3
|
||
elapsed: "00:00:28"
|
||
timing:
|
||
started: "2026-02-08T12:57:01Z"
|
||
duration_ms: 28000
|
||
messages:
|
||
- "Strategize in progress"
|
||
```
|
||
|
||
Status of a plan that encountered an error:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Plan Status ────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM7K2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: #ff6666; font-weight: 600;">State:</span> errored │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Action:</span> local/migrate-db │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Automation:</span> supervised │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Progress ───────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Strategize │
|
||
│ <span style="color: #ff6666; font-weight: 600;">✗</span> Execute │
|
||
│ <span style="opacity: 0.5;">○</span> Apply (skipped) │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Error Detail ──────────────────────────────────────────────────╮
|
||
│ <span style="color: #ff6666; font-weight: 600;">Error:</span> Tool invocation failed: connection refused │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool:</span> local/db-migrate │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Step:</span> 4 of 6 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 (sandbox state preserved) │
|
||
│ <span style="opacity: 0.7;">Recoverable: yes — use <span style="color: #66cc66;">"agents plan prompt"</span> to provide guidance</span> │
|
||
╰─────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Cost ───────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tokens Used:</span> 8,340 │
|
||
│ <span style="color: yellow;">Cost So Far:</span> $0.028 │
|
||
╰──────────────────────╯
|
||
|
||
<span style="color: #ff6666; font-weight: 600;">✗ ERROR</span> Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan status 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Plan Status
|
||
Plan: 01HXM7K2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: execute
|
||
State: errored
|
||
Action: local/migrate-db
|
||
Project: local/api-service
|
||
Automation: supervised
|
||
Attempt: 1
|
||
|
||
Progress
|
||
[OK] Strategize
|
||
[FAIL] Execute
|
||
o Apply (skipped)
|
||
|
||
Error Detail
|
||
Error: Tool invocation failed: connection refused
|
||
Tool: local/db-migrate
|
||
Step: 4 of 6
|
||
Checkpoint: cp_01HXM8C2 (sandbox state preserved)
|
||
Recoverable: yes -- use "agents plan prompt" to provide guidance
|
||
|
||
Cost
|
||
Tokens Used: 8,340
|
||
Cost So Far: $0.028
|
||
|
||
[ERROR] Plan errored -- use `agents plan prompt` to resume or `agents plan cancel` to abort
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan status",
|
||
"status": "error",
|
||
"exit_code": 1,
|
||
"data": {
|
||
"plan_id": "01HXM7K2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"state": "errored",
|
||
"action": "local/migrate-db",
|
||
"project": "local/api-service",
|
||
"automation": "supervised",
|
||
"attempt": 1,
|
||
"progress": [
|
||
{ "step": "Strategize", "status": "done" },
|
||
{ "step": "Execute", "status": "failed" },
|
||
{ "step": "Apply", "status": "skipped" }
|
||
],
|
||
"error": {
|
||
"message": "Tool invocation failed: connection refused",
|
||
"tool": "local/db-migrate",
|
||
"step": "4 of 6",
|
||
"checkpoint": "cp_01HXM8C2",
|
||
"recoverable": true
|
||
},
|
||
"cost": {
|
||
"tokens_used": 8340,
|
||
"cost_so_far": 0.028
|
||
}
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:57:01Z",
|
||
"duration_ms": 72000
|
||
},
|
||
"messages": ["Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan status
|
||
status: error
|
||
exit_code: 1
|
||
data:
|
||
plan_id: "01HXM7K2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: execute
|
||
state: errored
|
||
action: local/migrate-db
|
||
project: local/api-service
|
||
automation: supervised
|
||
attempt: 1
|
||
progress:
|
||
- step: Strategize
|
||
status: done
|
||
- step: Execute
|
||
status: failed
|
||
- step: Apply
|
||
status: skipped
|
||
error:
|
||
message: "Tool invocation failed: connection refused"
|
||
tool: local/db-migrate
|
||
step: "4 of 6"
|
||
checkpoint: cp_01HXM8C2
|
||
recoverable: true
|
||
cost:
|
||
tokens_used: 8340
|
||
cost_so_far: 0.028
|
||
timing:
|
||
started: "2026-02-08T12:57:01Z"
|
||
duration_ms: 72000
|
||
messages:
|
||
- "Plan errored — use `agents plan prompt` to resume or `agents plan cancel` to abort"
|
||
```
|
||
|
||
##### agents plan cancel
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan cancel [(<span style="color: magenta;"><span style="color: cyan;">--reason</span>|<span style="color: yellow;">-r</span></span>) <span style="color: #66cc66;"><REASON></span>] <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
!!! warning "Irreversible State Transition"
|
||
Cancel a plan that is not in a terminal state. Cancellation transitions the plan to the `cancelled` state, which is ==terminal==. The sandbox and any child plan artifacts are preserved for inspection but cannot be resumed.
|
||
|
||
!!! tip "Recovery After Cancel"
|
||
A cancelled plan cannot be resumed, but you can re-execute the same action with `agents plan use` to create a new plan instance.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID.
|
||
- `--reason/-r TEXT`: Optional reason.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: cyan;">--reason</span> <span style="color: #66cc66;">"blocked on credentials"</span>
|
||
|
||
╭─ Plan Cancelled ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: magenta; font-weight: 600;">Reason:</span> blocked on credentials │
|
||
│ <span style="color: #5599ff; font-weight: 600;">State:</span> cancelled │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Cancelled At:</span> 13:02:15 │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Sandbox ────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Status:</span> preserved │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Files Modified:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints:</span> 2 │
|
||
╰──────────────────────────╯
|
||
|
||
╭─ Child Plans ─────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 1 │
|
||
│ <span style="color: yellow; font-weight: 600;">Cancelled:</span> 1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Artifacts Preserved:</span> yes │
|
||
╰───────────────────────────╯
|
||
|
||
╭─ Recovery ───────────────────────────────────────────╮
|
||
│ - Resolve credentials │
|
||
│ - Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
╰──────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Plan cancelled
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan cancel 01HXM8C2ZK4Q7C2B3F2R4VYV6J --reason "blocked on credentials"
|
||
|
||
Plan Cancelled
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Phase: execute
|
||
Reason: blocked on credentials
|
||
State: cancelled
|
||
Cancelled At: 13:02:15
|
||
|
||
Sandbox
|
||
Status: preserved
|
||
Files Modified: 3
|
||
Checkpoints: 2
|
||
|
||
Child Plans
|
||
Completed: 1
|
||
Cancelled: 1
|
||
Artifacts Preserved: yes
|
||
|
||
Recovery
|
||
- Resolve credentials
|
||
- Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
[OK] Plan cancelled
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan cancel",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"phase": "execute",
|
||
"reason": "blocked on credentials",
|
||
"state": "cancelled",
|
||
"cancelled_at": "13:02:15",
|
||
"sandbox": {
|
||
"status": "preserved",
|
||
"files_modified": 3,
|
||
"checkpoints": 2
|
||
},
|
||
"child_plans": {
|
||
"completed": 1,
|
||
"cancelled": 1,
|
||
"artifacts_preserved": true
|
||
},
|
||
"recovery": [
|
||
"Resolve credentials",
|
||
"Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
]
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T13:02:15Z",
|
||
"duration_ms": 340
|
||
},
|
||
"messages": ["Plan cancelled"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan cancel
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
phase: execute
|
||
reason: "blocked on credentials"
|
||
state: cancelled
|
||
cancelled_at: "13:02:15"
|
||
sandbox:
|
||
status: preserved
|
||
files_modified: 3
|
||
checkpoints: 2
|
||
child_plans:
|
||
completed: 1
|
||
cancelled: 1
|
||
artifacts_preserved: true
|
||
recovery:
|
||
- "Resolve credentials"
|
||
- "Run agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
timing:
|
||
started: "2026-02-08T13:02:15Z"
|
||
duration_ms: 340
|
||
messages:
|
||
- "Plan cancelled"
|
||
```
|
||
|
||
##### agents plan tree
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan tree [<span style="color: cyan;">--show-superseded</span>] <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Render the decision tree for a plan.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID (required).
|
||
- `--show-superseded`: Include superseded decisions.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Decision Tree ──────────────────────────────────────────────────────────────────────────╮
|
||
│ Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ ├─ <span style="color: white;">[prompt_definition]</span> <span style="color: #66cc66;">"Increase test coverage to 85%"</span> │
|
||
│ ├─ <span style="color: magenta;">[invariant_enforced]</span> <span style="color: #66cc66;">"Prioritize financial transaction and user mgmt code"</span> │
|
||
│ ├─ <span style="color: magenta;">[invariant_enforced]</span> <span style="color: #66cc66;">"All API calls over TCP must be mocked"</span> │
|
||
│ ├─ <span style="color: #5599ff;">[strategy_choice]</span> <span style="color: #66cc66;">"Prioritize auth and payments"</span> <span style="opacity: 0.7;">(confidence: 0.82)</span> │
|
||
│ ├─ <span style="color: #66cc66;">[subplan_parallel_spawn]</span> "Implement auth and payment modules, in parallel" │
|
||
│ │ ├─ <span style="color: #66cc66;">[subplan_spawn]</span> "Write auth tests" → Plan: 01HXM9F1A │
|
||
│ │ └─ <span style="color: #66cc66;">[subplan_spawn]</span> "Write payment tests" → Plan: 01HXM9F2B │
|
||
│ └─ <span style="color: #66cc66;">[subplan_parallel_spawn]</span> "Write tests for remaining modules" │
|
||
│ └─ ... │
|
||
╰──────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Tree Summary ─────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Nodes:</span> 9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Depth:</span> 3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Child Plans:</span> 2+ │
|
||
│ <span style="color: magenta; font-weight: 600;">Invariants:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Superseded:</span> 0 (hidden) │
|
||
╰────────────────────────────╯
|
||
|
||
╭─ Child Plans ──────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Phase</span> <span style="color: cyan; font-weight: 600;">State</span> │
|
||
│ <span style="opacity: 0.7;">────────── ─────── ─────────</span> │
|
||
│ 01HXM9F1A execute processing │
|
||
│ 01HXM9F2B execute queued │
|
||
╰────────────────────────────────────────────────────╯
|
||
|
||
╭─ Decision IDs (for correction) ──────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Root:</span> 01HXM9A0B1Q2W3R5G8Z0P4Q1X8 │
|
||
│ <span style="color: magenta; font-weight: 600;">Invariant 1:</span> 01HXM9A0C1R3X4S6G9Z1P5Q2Y9 │
|
||
│ <span style="color: magenta; font-weight: 600;">Invariant 2:</span> 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Parallel 1:</span> 01HXM9A1D3R8X5S7H1Z2P5Q2Y0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Spawn Auth:</span> 01HXM9A2D3Q8W4R6H9Z1P5Q2X0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Spawn Payment:</span> 01HXM9A3E4Q9W5R7I0Z2P6Q3X1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Parallel 2:</span> 01HXM9A4F5Q0W6R8J1Z3P7Q4X2 │
|
||
╰──────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision tree rendered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Decision Tree
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
+-- [prompt_definition] "Increase test coverage to 85%"
|
||
+-- [invariant_enforced] "Prioritize financial transaction and user mgmt code"
|
||
+-- [invariant_enforced] "All API calls over TCP must be mocked"
|
||
+-- [strategy_choice] "Prioritize auth and payments" (confidence: 0.82)
|
||
+-- [subplan_parallel_spawn] "Implement auth and payment modules, in parallel"
|
||
| +-- [subplan_spawn] "Write auth tests" -> Plan: 01HXM9F1A
|
||
| +-- [subplan_spawn] "Write payment tests" -> Plan: 01HXM9F2B
|
||
+-- [subplan_parallel_spawn] "Write tests for remaining modules"
|
||
+-- ...
|
||
|
||
Tree Summary
|
||
Nodes: 9
|
||
Depth: 3
|
||
Child Plans: 2+
|
||
Invariants: 2
|
||
Superseded: 0 (hidden)
|
||
|
||
Child Plans
|
||
ID Phase State
|
||
---------- ------- ---------
|
||
01HXM9F1A execute processing
|
||
01HXM9F2B execute queued
|
||
|
||
Decision IDs (for correction)
|
||
Root: 01HXM9A0B1Q2W3R5G8Z0P4Q1X8
|
||
Invariant 1: 01HXM9A0C1R3X4S6G9Z1P5Q2Y9
|
||
Invariant 2: 01HXM9A0D2S4Y5T7H0Z2P6Q3Z0
|
||
Strategy: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
Parallel 1: 01HXM9A1D3R8X5S7H1Z2P5Q2Y0
|
||
Spawn Auth: 01HXM9A2D3Q8W4R6H9Z1P5Q2X0
|
||
Spawn Payment: 01HXM9A3E4Q9W5R7I0Z2P6Q3X1
|
||
Parallel 2: 01HXM9A4F5Q0W6R8J1Z3P7Q4X2
|
||
|
||
[OK] Decision tree rendered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan tree",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"tree": {
|
||
"type": "prompt_definition",
|
||
"description": "Increase test coverage to 85%",
|
||
"children": [
|
||
{ "type": "invariant_enforced", "description": "Prioritize financial transaction and user mgmt code" },
|
||
{ "type": "invariant_enforced", "description": "All API calls over TCP must be mocked" },
|
||
{ "type": "strategy_choice", "description": "Prioritize auth and payments", "confidence": 0.82 },
|
||
{
|
||
"type": "subplan_parallel_spawn",
|
||
"description": "Implement auth and payment modules, in parallel",
|
||
"children": [
|
||
{ "type": "subplan_spawn", "description": "Write auth tests", "plan_id": "01HXM9F1A" },
|
||
{ "type": "subplan_spawn", "description": "Write payment tests", "plan_id": "01HXM9F2B" }
|
||
]
|
||
},
|
||
{
|
||
"type": "subplan_parallel_spawn",
|
||
"description": "Write tests for remaining modules",
|
||
"children": ["..."]
|
||
}
|
||
]
|
||
},
|
||
"summary": {
|
||
"nodes": 9,
|
||
"depth": 3,
|
||
"child_plans": "2+",
|
||
"invariants": 2,
|
||
"superseded": 0
|
||
},
|
||
"child_plans": [
|
||
{ "id": "01HXM9F1A", "phase": "execute", "state": "processing" },
|
||
{ "id": "01HXM9F2B", "phase": "execute", "state": "queued" }
|
||
],
|
||
"decision_ids": {
|
||
"root": "01HXM9A0B1Q2W3R5G8Z0P4Q1X8",
|
||
"invariant_1": "01HXM9A0C1R3X4S6G9Z1P5Q2Y9",
|
||
"invariant_2": "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0",
|
||
"strategy": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
|
||
"parallel_1": "01HXM9A1D3R8X5S7H1Z2P5Q2Y0",
|
||
"spawn_auth": "01HXM9A2D3Q8W4R6H9Z1P5Q2X0",
|
||
"spawn_payment": "01HXM9A3E4Q9W5R7I0Z2P6Q3X1",
|
||
"parallel_2": "01HXM9A4F5Q0W6R8J1Z3P7Q4X2"
|
||
}
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:58:00Z",
|
||
"duration_ms": 85
|
||
},
|
||
"messages": ["Decision tree rendered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan tree
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
tree:
|
||
type: prompt_definition
|
||
description: "Increase test coverage to 85%"
|
||
children:
|
||
- type: invariant_enforced
|
||
description: "Prioritize financial transaction and user mgmt code"
|
||
- type: invariant_enforced
|
||
description: "All API calls over TCP must be mocked"
|
||
- type: strategy_choice
|
||
description: "Prioritize auth and payments"
|
||
confidence: 0.82
|
||
- type: subplan_parallel_spawn
|
||
description: "Implement auth and payment modules, in parallel"
|
||
children:
|
||
- type: subplan_spawn
|
||
description: "Write auth tests"
|
||
plan_id: "01HXM9F1A"
|
||
- type: subplan_spawn
|
||
description: "Write payment tests"
|
||
plan_id: "01HXM9F2B"
|
||
- type: subplan_parallel_spawn
|
||
description: "Write tests for remaining modules"
|
||
children:
|
||
- "..."
|
||
summary:
|
||
nodes: 9
|
||
depth: 3
|
||
child_plans: "2+"
|
||
invariants: 2
|
||
superseded: 0
|
||
child_plans:
|
||
- id: "01HXM9F1A"
|
||
phase: execute
|
||
state: processing
|
||
- id: "01HXM9F2B"
|
||
phase: execute
|
||
state: queued
|
||
decision_ids:
|
||
root: "01HXM9A0B1Q2W3R5G8Z0P4Q1X8"
|
||
invariant_1: "01HXM9A0C1R3X4S6G9Z1P5Q2Y9"
|
||
invariant_2: "01HXM9A0D2S4Y5T7H0Z2P6Q3Z0"
|
||
strategy: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
parallel_1: "01HXM9A1D3R8X5S7H1Z2P5Q2Y0"
|
||
spawn_auth: "01HXM9A2D3Q8W4R6H9Z1P5Q2X0"
|
||
spawn_payment: "01HXM9A3E4Q9W5R7I0Z2P6Q3X1"
|
||
parallel_2: "01HXM9A4F5Q0W6R8J1Z3P7Q4X2"
|
||
timing:
|
||
started: "2026-02-08T12:58:00Z"
|
||
duration_ms: 85
|
||
messages:
|
||
- "Decision tree rendered"
|
||
```
|
||
|
||
##### agents plan explain
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan explain [<span style="color: cyan;">--show-context</span>] [<span style="color: cyan;">--show-reasoning</span>] <span style="color: #66cc66;"><DECISION_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show a detailed explanation for a decision.
|
||
|
||
**Arguments**
|
||
|
||
- `<DECISION_ID>`: Decision ID.
|
||
- `--show-context`: Include the context snapshot.
|
||
- `--show-reasoning`: Include raw model reasoning if available.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--show-context</span>
|
||
|
||
╭─ Decision ─────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> strategy_choice │
|
||
│ <span style="color: magenta; font-weight: 600;">Question:</span> Which modules should be prioritized? │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Chosen:</span> Auth and payments │
|
||
│ <span style="color: yellow; font-weight: 600;">Confidence:</span> 0.82 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sequence:</span> 2 of 5 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:58 │
|
||
╰────────────────────────────────────────────────╯
|
||
|
||
╭─ Alternatives Considered ──────────────────────╮
|
||
│ 1. Auth and payments <span style="color: #66cc66; font-weight: 600;">(chosen)</span> │
|
||
│ 2. User module first (coverage 71%, med risk) │
|
||
│ 3. All modules equally (spread thin) │
|
||
╰────────────────────────────────────────────────╯
|
||
|
||
╭─ Impact ──────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Downstream Decisions:</span> 3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Downstream Child Plans:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Artifacts Produced:</span> 5 │
|
||
│ <span style="color: yellow; font-weight: 600;">Correction Impact:</span> medium │
|
||
╰───────────────────────────────╯
|
||
|
||
╭─ Context Snapshot ───────────────╮
|
||
│ - Coverage < 70% in auth │
|
||
│ - Payments failures last release │
|
||
│ - Auth: 12 files, 45% coverage │
|
||
│ - Payments: 8 files, 52% cover. │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Hot Context Hash:</span> sha256:4b2e... │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Rationale ───────────────────────────────────────╮
|
||
│ Auth and payment modules have the lowest coverage │
|
||
│ and highest business risk. Auth handles security │
|
||
│ tokens, payments handles money. Both had bugs in │
|
||
│ the last release traceable to missing tests. │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
╭─ Correction ──────────────────────────────────────────────╮
|
||
│ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: cyan;">--mode</span> revert <span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Prioritize payments first..."</span> │
|
||
╰───────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision explained
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan explain 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --show-context
|
||
|
||
Decision
|
||
ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
Type: strategy_choice
|
||
Question: Which modules should be prioritized?
|
||
Chosen: Auth and payments
|
||
Confidence: 0.82
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Sequence: 2 of 5
|
||
Created: 2026-02-08 12:58
|
||
|
||
Alternatives Considered
|
||
1. Auth and payments (chosen)
|
||
2. User module first (coverage 71%, med risk)
|
||
3. All modules equally (spread thin)
|
||
|
||
Impact
|
||
Downstream Decisions: 3
|
||
Downstream Child Plans: 2
|
||
Artifacts Produced: 5
|
||
Correction Impact: medium
|
||
|
||
Context Snapshot
|
||
- Coverage < 70% in auth
|
||
- Payments failures last release
|
||
- Auth: 12 files, 45% coverage
|
||
- Payments: 8 files, 52% cover.
|
||
Hot Context Hash: sha256:4b2e...
|
||
|
||
Rationale
|
||
Auth and payment modules have the lowest coverage
|
||
and highest business risk. Auth handles security
|
||
tokens, payments handles money. Both had bugs in
|
||
the last release traceable to missing tests.
|
||
|
||
Correction
|
||
agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
--mode revert --guidance "Prioritize payments first..."
|
||
|
||
[OK] Decision explained
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan explain",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
|
||
"type": "strategy_choice",
|
||
"question": "Which modules should be prioritized?",
|
||
"chosen": "Auth and payments",
|
||
"confidence": 0.82,
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"sequence": "2 of 5",
|
||
"created": "2026-02-08T12:58:00Z",
|
||
"alternatives": [
|
||
{ "index": 1, "description": "Auth and payments", "chosen": true },
|
||
{ "index": 2, "description": "User module first (coverage 71%, med risk)", "chosen": false },
|
||
{ "index": 3, "description": "All modules equally (spread thin)", "chosen": false }
|
||
],
|
||
"impact": {
|
||
"downstream_decisions": 3,
|
||
"downstream_child_plans": 2,
|
||
"artifacts_produced": 5,
|
||
"correction_impact": "medium"
|
||
},
|
||
"context_snapshot": {
|
||
"items": [
|
||
"Coverage < 70% in auth",
|
||
"Payments failures last release",
|
||
"Auth: 12 files, 45% coverage",
|
||
"Payments: 8 files, 52% cover."
|
||
],
|
||
"hot_context_hash": "sha256:4b2e..."
|
||
},
|
||
"rationale": "Auth and payment modules have the lowest coverage and highest business risk. Auth handles security tokens, payments handles money. Both had bugs in the last release traceable to missing tests.",
|
||
"correction_hint": "agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first...""
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:58:00Z",
|
||
"duration_ms": 110
|
||
},
|
||
"messages": ["Decision explained"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan explain
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
type: strategy_choice
|
||
question: "Which modules should be prioritized?"
|
||
chosen: "Auth and payments"
|
||
confidence: 0.82
|
||
plan_id: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
sequence: "2 of 5"
|
||
created: "2026-02-08T12:58:00Z"
|
||
alternatives:
|
||
- index: 1
|
||
description: "Auth and payments"
|
||
chosen: true
|
||
- index: 2
|
||
description: "User module first (coverage 71%, med risk)"
|
||
chosen: false
|
||
- index: 3
|
||
description: "All modules equally (spread thin)"
|
||
chosen: false
|
||
impact:
|
||
downstream_decisions: 3
|
||
downstream_child_plans: 2
|
||
artifacts_produced: 5
|
||
correction_impact: medium
|
||
context_snapshot:
|
||
items:
|
||
- "Coverage < 70% in auth"
|
||
- "Payments failures last release"
|
||
- "Auth: 12 files, 45% coverage"
|
||
- "Payments: 8 files, 52% cover."
|
||
hot_context_hash: "sha256:4b2e..."
|
||
rationale: >-
|
||
Auth and payment modules have the lowest coverage
|
||
and highest business risk. Auth handles security
|
||
tokens, payments handles money. Both had bugs in
|
||
the last release traceable to missing tests.
|
||
correction_hint: >-
|
||
agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
--mode revert --guidance "Prioritize payments first..."
|
||
timing:
|
||
started: "2026-02-08T12:58:00Z"
|
||
duration_ms: 110
|
||
messages:
|
||
- "Decision explained"
|
||
```
|
||
|
||
Including the raw model reasoning with `--show-reasoning`:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan explain <span style="color: cyan;">--show-reasoning</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
|
||
╭─ Decision ──────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> strategy_choice │
|
||
│ <span style="color: magenta; font-weight: 600;">Choice:</span> Convert to async/await │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Alternatives:</span> 3 │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Alternatives Considered ────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">1. Convert to async/await patterns</span> (chosen) │
|
||
│ <span style="opacity: 0.7;"> 2. Keep synchronous with thread pool</span> │
|
||
│ <span style="opacity: 0.7;"> 3. Use callback-based approach</span> │
|
||
╰──────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Rationale ──────────────────────────────────────────────────╮
|
||
│ Async/await is the modern Python standard for I/O-bound │
|
||
│ operations. The project already uses asyncio in 3 modules. │
|
||
│ Thread pools would add complexity without native support. │
|
||
╰──────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Model Reasoning (raw) ───────────────────────────────────────╮
|
||
│ <span style="opacity: 0.7;">I need to decide on the concurrency pattern for the payment</span> │
|
||
│ <span style="opacity: 0.7;">processing module. Let me analyze the current codebase:</span> │
|
||
│ <span style="opacity: 0.7;"></span> │
|
||
│ <span style="opacity: 0.7;">1. src/payments/api.py uses synchronous requests.</span> │
|
||
│ <span style="opacity: 0.7;">2. src/core/scheduler.py already uses asyncio.</span> │
|
||
│ <span style="opacity: 0.7;">3. The database driver (asyncpg) supports async natively.</span> │
|
||
│ <span style="opacity: 0.7;">4. Project invariant says <span style="color: #66cc66;">"prefer modern Python patterns"</span>.</span> │
|
||
│ <span style="opacity: 0.7;"></span> │
|
||
│ <span style="opacity: 0.7;">Given that 3/5 core modules already use asyncio, and the</span> │
|
||
│ <span style="opacity: 0.7;">database driver supports it, converting to async/await is</span> │
|
||
│ <span style="opacity: 0.7;">the most consistent choice. Thread pools would work but</span> │
|
||
│ <span style="opacity: 0.7;">add unnecessary complexity and don't integrate well with</span> │
|
||
│ <span style="opacity: 0.7;">the existing asyncio event loop in scheduler.py.</span> │
|
||
╰───────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Decision explained
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan explain --show-reasoning 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
|
||
Decision
|
||
ID: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
Type: strategy_choice
|
||
Choice: Convert to async/await
|
||
Alternatives: 3
|
||
|
||
Alternatives Considered
|
||
1. Convert to async/await patterns (chosen)
|
||
2. Keep synchronous with thread pool
|
||
3. Use callback-based approach
|
||
|
||
Rationale
|
||
Async/await is the modern Python standard for I/O-bound
|
||
operations. The project already uses asyncio in 3 modules.
|
||
Thread pools would add complexity without native support.
|
||
|
||
Model Reasoning (raw)
|
||
I need to decide on the concurrency pattern for the payment
|
||
processing module. Let me analyze the current codebase:
|
||
|
||
1. src/payments/api.py uses synchronous requests.
|
||
2. src/core/scheduler.py already uses asyncio.
|
||
3. The database driver (asyncpg) supports async natively.
|
||
4. Project invariant says "prefer modern Python patterns".
|
||
|
||
Given that 3/5 core modules already use asyncio, and the
|
||
database driver supports it, converting to async/await is
|
||
the most consistent choice. Thread pools would work but
|
||
add unnecessary complexity and don't integrate well with
|
||
the existing asyncio event loop in scheduler.py.
|
||
|
||
[OK] Decision explained
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan explain",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"decision_id": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
|
||
"type": "strategy_choice",
|
||
"choice": "Convert to async/await",
|
||
"alternatives_count": 3,
|
||
"alternatives": [
|
||
{ "index": 1, "description": "Convert to async/await patterns", "chosen": true },
|
||
{ "index": 2, "description": "Keep synchronous with thread pool", "chosen": false },
|
||
{ "index": 3, "description": "Use callback-based approach", "chosen": false }
|
||
],
|
||
"rationale": "Async/await is the modern Python standard for I/O-bound operations. The project already uses asyncio in 3 modules. Thread pools would add complexity without native support.",
|
||
"model_reasoning": "I need to decide on the concurrency pattern for the payment processing module. Let me analyze the current codebase:\n\n1. src/payments/api.py uses synchronous requests.\n2. src/core/scheduler.py already uses asyncio.\n3. The database driver (asyncpg) supports async natively.\n4. Project invariant says \"prefer modern Python patterns\".\n\nGiven that 3/5 core modules already use asyncio, and the database driver supports it, converting to async/await is the most consistent choice. Thread pools would work but add unnecessary complexity and don't integrate well with the existing asyncio event loop in scheduler.py."
|
||
},
|
||
"timing": {
|
||
"started": "2026-02-08T12:58:00Z",
|
||
"duration_ms": 95
|
||
},
|
||
"messages": ["Decision explained"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan explain
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
decision_id: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
type: strategy_choice
|
||
choice: "Convert to async/await"
|
||
alternatives_count: 3
|
||
alternatives:
|
||
- index: 1
|
||
description: "Convert to async/await patterns"
|
||
chosen: true
|
||
- index: 2
|
||
description: "Keep synchronous with thread pool"
|
||
chosen: false
|
||
- index: 3
|
||
description: "Use callback-based approach"
|
||
chosen: false
|
||
rationale: >-
|
||
Async/await is the modern Python standard for I/O-bound
|
||
operations. The project already uses asyncio in 3 modules.
|
||
Thread pools would add complexity without native support.
|
||
model_reasoning: >-
|
||
I need to decide on the concurrency pattern for the payment
|
||
processing module. Let me analyze the current codebase:
|
||
1. src/payments/api.py uses synchronous requests.
|
||
2. src/core/scheduler.py already uses asyncio.
|
||
3. The database driver (asyncpg) supports async natively.
|
||
4. Project invariant says "prefer modern Python patterns".
|
||
Given that 3/5 core modules already use asyncio, and the
|
||
database driver supports it, converting to async/await is
|
||
the most consistent choice.
|
||
timing:
|
||
started: "2026-02-08T12:58:00Z"
|
||
duration_ms: 95
|
||
messages:
|
||
- "Decision explained"
|
||
```
|
||
|
||
##### agents plan correct
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan correct <span style="color: cyan;">--mode</span> (<span style="color: magenta;">revert|append</span>) (<span style="color: magenta;"><span style="color: cyan;">--guidance</span>|<span style="color: yellow;">-g</span></span>) <span style="color: #66cc66;"><GUIDANCE></span>
|
||
[<span style="color: cyan;">--dry-run</span>] [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><DECISION_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Correct a decision either by reverting and re-executing or by appending a fix.
|
||
|
||
**Arguments**
|
||
|
||
- `<DECISION_ID>`: Decision ID.
|
||
- `--mode revert|append`: Correction mode.
|
||
- `--guidance/-g TEXT`: Guidance text.
|
||
- `--dry-run`: Show impact without executing.
|
||
- `--yes`: Skip confirmation for revert mode.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> revert \
|
||
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Prioritize payments first"</span> <span style="color: cyan;">--yes</span>
|
||
|
||
╭─ Correction ────────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> revert │
|
||
│ <span style="color: yellow; font-weight: 600;">Impact:</span> 3 decisions, 2 child plans, 5 artifacts │
|
||
│ <span style="color: #66cc66; font-weight: 600;">New Decision:</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
|
||
│ <span style="color: magenta; font-weight: 600;">Corrects:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 2 │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
╭─ Affected Subtree ──────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Decisions Invalidated:</span> 3 │
|
||
│ <span style="color: yellow; font-weight: 600;">Child Plans Rolled Back:</span> 2 │
|
||
│ <span style="color: yellow; font-weight: 600;">Artifacts Archived:</span> 5 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Unaffected Decisions:</span> 2 │
|
||
╰─────────────────────────────────╯
|
||
|
||
╭─ Sandbox Rollback ─────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Files Reverted:</span> 5 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> restored │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ Recompute ──────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Queued:</span> 2 child plans │
|
||
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 4m │
|
||
╰──────────────────────────╯
|
||
|
||
╭─ History ───────────────────────────────────────────╮
|
||
│ - Original decision superseded │
|
||
│ - Prior artifacts archived for comparison │
|
||
│ - agents plan diff <span style="color: cyan;">--correction</span> 01HXM9B7Z3Q1Q8K2.. │
|
||
╰─────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Correction applied
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Prioritize payments first" --yes
|
||
|
||
Correction
|
||
Mode: revert
|
||
Impact: 3 decisions, 2 child plans, 5 artifacts
|
||
New Decision: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
|
||
Corrects: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
Attempt: 2
|
||
|
||
Affected Subtree
|
||
Decisions Invalidated: 3
|
||
Child Plans Rolled Back: 2
|
||
Artifacts Archived: 5
|
||
Unaffected Decisions: 2
|
||
|
||
Sandbox Rollback
|
||
Checkpoint: cp_01HXM8C2
|
||
Files Reverted: 5
|
||
Status: restored
|
||
|
||
Recompute
|
||
Queued: 2 child plans
|
||
ETA: 4m
|
||
|
||
History
|
||
- Original decision superseded
|
||
- Prior artifacts archived for comparison
|
||
- agents plan diff --correction 01HXM9B7Z3Q1Q8K2..
|
||
|
||
[OK] Correction applied
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan correct",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"correction": {
|
||
"mode": "revert",
|
||
"impact": "3 decisions, 2 child plans, 5 artifacts",
|
||
"new_decision": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8",
|
||
"corrects": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
|
||
"attempt": 2
|
||
},
|
||
"affected_subtree": {
|
||
"decisions_invalidated": 3,
|
||
"child_plans_rolled_back": 2,
|
||
"artifacts_archived": 5,
|
||
"unaffected_decisions": 2
|
||
},
|
||
"sandbox_rollback": {
|
||
"checkpoint": "cp_01HXM8C2",
|
||
"files_reverted": 5,
|
||
"status": "restored"
|
||
},
|
||
"recompute": {
|
||
"queued": "2 child plans",
|
||
"eta": "4m"
|
||
},
|
||
"history": [
|
||
"Original decision superseded",
|
||
"Prior artifacts archived for comparison",
|
||
"agents plan diff --correction 01HXM9B7Z3Q1Q8K2.."
|
||
]
|
||
},
|
||
"timing": { "started": "2025-06-15T10:24:00Z", "duration_ms": 2350 },
|
||
"messages": ["Correction applied"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan correct
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
correction:
|
||
mode: revert
|
||
impact: "3 decisions, 2 child plans, 5 artifacts"
|
||
new_decision: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8"
|
||
corrects: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
attempt: 2
|
||
affected_subtree:
|
||
decisions_invalidated: 3
|
||
child_plans_rolled_back: 2
|
||
artifacts_archived: 5
|
||
unaffected_decisions: 2
|
||
sandbox_rollback:
|
||
checkpoint: cp_01HXM8C2
|
||
files_reverted: 5
|
||
status: restored
|
||
recompute:
|
||
queued: "2 child plans"
|
||
eta: "4m"
|
||
history:
|
||
- "Original decision superseded"
|
||
- "Prior artifacts archived for comparison"
|
||
- "agents plan diff --correction 01HXM9B7Z3Q1Q8K2.."
|
||
timing:
|
||
started: "2025-06-15T10:24:00Z"
|
||
duration_ms: 2350
|
||
messages:
|
||
- "Correction applied"
|
||
```
|
||
|
||
Using `--mode append` to add a corrective decision without reverting existing work (useful when the original decision was partially correct):
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> append \
|
||
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Also add rate limiting to the auth endpoints"</span>
|
||
|
||
╭─ Correction ─────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> append │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Impact:</span> adds to existing subtree, no rollback │
|
||
│ <span style="color: #66cc66; font-weight: 600;">New Decision:</span> 01HXM9C3Z5T2Q8K2E9H7K3W2M8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Appended After:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 2 │
|
||
╰──────────────────────────────────────────────────╯
|
||
|
||
╭─ Append Detail ─────────────────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Original decision preserved:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Existing artifacts kept:</span> yes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Additional work:</span> appended as new child plan │
|
||
│ <span style="opacity: 0.7;">The original 5 artifacts remain; a new child plan will add</span> │
|
||
│ <span style="opacity: 0.7;">rate-limiting code on top of the existing auth changes.</span> │
|
||
╰─────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Queued ──────────╮
|
||
│ <span style="color: yellow;">New child:</span> 1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">ETA:</span> 2m │
|
||
╰───────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Append correction queued
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode append --guidance "Also add rate limiting to the auth endpoints"
|
||
|
||
Correction
|
||
Mode: append
|
||
Impact: adds to existing subtree, no rollback
|
||
New Decision: 01HXM9C3Z5T2Q8K2E9H7K3W2M8
|
||
Appended After: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
Attempt: 2
|
||
|
||
Append Detail
|
||
Original decision preserved: yes
|
||
Existing artifacts kept: yes
|
||
Additional work: appended as new child plan
|
||
The original 5 artifacts remain; a new child plan will add
|
||
rate-limiting code on top of the existing auth changes.
|
||
|
||
Queued
|
||
New child: 1
|
||
ETA: 2m
|
||
|
||
[OK] Append correction queued
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan correct",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"correction": {
|
||
"mode": "append",
|
||
"impact": "adds to existing subtree, no rollback",
|
||
"new_decision": "01HXM9C3Z5T2Q8K2E9H7K3W2M8",
|
||
"appended_after": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9",
|
||
"attempt": 2
|
||
},
|
||
"append_detail": {
|
||
"original_decision_preserved": true,
|
||
"existing_artifacts_kept": true,
|
||
"additional_work": "appended as new child plan",
|
||
"note": "The original 5 artifacts remain; a new child plan will add rate-limiting code on top of the existing auth changes."
|
||
},
|
||
"queued": {
|
||
"new_child": 1,
|
||
"eta": "2m"
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:26:00Z", "duration_ms": 890 },
|
||
"messages": ["Append correction queued"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan correct
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
correction:
|
||
mode: append
|
||
impact: "adds to existing subtree, no rollback"
|
||
new_decision: "01HXM9C3Z5T2Q8K2E9H7K3W2M8"
|
||
appended_after: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
attempt: 2
|
||
append_detail:
|
||
original_decision_preserved: true
|
||
existing_artifacts_kept: true
|
||
additional_work: "appended as new child plan"
|
||
note: "The original 5 artifacts remain; a new child plan will add rate-limiting code on top of the existing auth changes."
|
||
queued:
|
||
new_child: 1
|
||
eta: "2m"
|
||
timing:
|
||
started: "2025-06-15T10:26:00Z"
|
||
duration_ms: 890
|
||
messages:
|
||
- "Append correction queued"
|
||
```
|
||
|
||
Using `--dry-run` to preview the impact of a correction before committing to it:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 <span style="color: cyan;">--mode</span> revert \
|
||
<span style="color: cyan;">--guidance</span> <span style="color: #66cc66;">"Use async/await pattern instead"</span> <span style="color: cyan;">--dry-run</span>
|
||
|
||
╭─ Dry Run — Correction Preview ─────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">⚠ This is a preview only. No changes will be made.</span> │
|
||
╰────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Would Revert ───────────────────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions to invalidate:</span> 3 │
|
||
│ <span style="opacity: 0.7;">01HXM9A1.. strategy_choice <span style="color: #66cc66;">"sync pattern"</span></span> │
|
||
│ <span style="opacity: 0.7;">01HXM9A2.. implementation_choice <span style="color: #66cc66;">"requests"</span></span> │
|
||
│ <span style="opacity: 0.7;">01HXM9A3.. tool_invocation write_file ×4</span> │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Child plans to roll back:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Artifacts to archive:</span> 5 files │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Unaffected decisions:</span> 2 (will be kept) │
|
||
╰──────────────────────────────────────────────────────╯
|
||
|
||
╭─ Estimated Cost ──────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Re-strategize:</span> ~$0.012 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Re-execute:</span> ~$0.035 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> ~$0.047 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ETA:</span> ~4 minutes │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="opacity: 0.7;">To execute this correction, remove --dry-run and add --yes</span>
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan correct 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --mode revert --guidance "Use async/await pattern instead" --dry-run
|
||
|
||
Dry Run -- Correction Preview
|
||
WARNING: This is a preview only. No changes will be made.
|
||
|
||
Would Revert
|
||
Decisions to invalidate: 3
|
||
01HXM9A1.. strategy_choice "sync pattern"
|
||
01HXM9A2.. implementation_choice "requests"
|
||
01HXM9A3.. tool_invocation write_file x4
|
||
Child plans to roll back: 2
|
||
Artifacts to archive: 5 files
|
||
Unaffected decisions: 2 (will be kept)
|
||
|
||
Estimated Cost
|
||
Re-strategize: ~$0.012
|
||
Re-execute: ~$0.035
|
||
Total: ~$0.047
|
||
ETA: ~4 minutes
|
||
|
||
To execute this correction, remove --dry-run and add --yes
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan correct",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"dry_run": true,
|
||
"would_revert": {
|
||
"decisions_to_invalidate": [
|
||
{ "id": "01HXM9A1..", "type": "strategy_choice", "label": "sync pattern" },
|
||
{ "id": "01HXM9A2..", "type": "implementation_choice", "label": "requests" },
|
||
{ "id": "01HXM9A3..", "type": "tool_invocation", "label": "write_file x4" }
|
||
],
|
||
"child_plans_to_roll_back": 2,
|
||
"artifacts_to_archive": 5,
|
||
"unaffected_decisions": 2
|
||
},
|
||
"estimated_cost": {
|
||
"re_strategize": "$0.012",
|
||
"re_execute": "$0.035",
|
||
"total": "$0.047",
|
||
"eta": "~4 minutes"
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:28:00Z", "duration_ms": 320 },
|
||
"messages": ["To execute this correction, remove --dry-run and add --yes"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan correct
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
dry_run: true
|
||
would_revert:
|
||
decisions_to_invalidate:
|
||
- id: "01HXM9A1.."
|
||
type: strategy_choice
|
||
label: "sync pattern"
|
||
- id: "01HXM9A2.."
|
||
type: implementation_choice
|
||
label: "requests"
|
||
- id: "01HXM9A3.."
|
||
type: tool_invocation
|
||
label: "write_file x4"
|
||
child_plans_to_roll_back: 2
|
||
artifacts_to_archive: 5
|
||
unaffected_decisions: 2
|
||
estimated_cost:
|
||
re_strategize: "$0.012"
|
||
re_execute: "$0.035"
|
||
total: "$0.047"
|
||
eta: "~4 minutes"
|
||
timing:
|
||
started: "2025-06-15T10:28:00Z"
|
||
duration_ms: 320
|
||
messages:
|
||
- "To execute this correction, remove --dry-run and add --yes"
|
||
```
|
||
|
||
##### agents plan diff
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan diff (<span style="color: magenta;"><span style="color: cyan;">--correction</span> <span style="color: #66cc66;"><CORRECTION_ATTEMPT_ID></span>|<span style="color: #66cc66;"><PLAN_ID></span></span>)</code></pre></div>
|
||
|
||
**Purpose**
|
||
Show diffs for a plan or a correction attempt.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Show diff for a plan (positional argument). Mutually exclusive with --correction.
|
||
- `--correction CORRECTION_ATTEMPT_ID`: Show diff for a correction attempt instead.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Diff Summary ─────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: yellow; font-weight: 600;">Files Changed:</span> 2 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Insertions:</span> 12 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Deletions:</span> 4 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Net Change:</span> +8 lines │
|
||
╰────────────────────────────────────────────────╯
|
||
|
||
╭─ Files ───────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Path</span> <span style="color: cyan; font-weight: 600;">Change</span> <span style="color: cyan; font-weight: 600;">Status</span> │
|
||
│ <span style="opacity: 0.7;">─────────────────── ────── ────────</span> │
|
||
│ src/auth/session.py <span style="color: #66cc66; font-weight: 600;">+8 -2</span> modified │
|
||
│ src/auth/tokens.py <span style="color: #66cc66; font-weight: 600;">+4 -2</span> modified │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Patch Preview ──────────────────────────╮
|
||
│ <span style="opacity: 0.7;">--- a/src/auth/session.py</span> │
|
||
│ <span style="opacity: 0.7;">+++ b/src/auth/session.py</span> │
|
||
│ <span style="color: cyan;">@@ -12,4 +12,10 @@</span> │
|
||
│ <span style="color: #ff6666;">- import jwt</span> │
|
||
│ <span style="color: #66cc66;">+ import sessionlib</span> │
|
||
│ <span style="color: #ff6666;">- def validate_token(...)</span> │
|
||
│ <span style="color: #66cc66;">+ def validate_session(...)</span> │
|
||
│ <span style="opacity: 0.7;">--- a/src/auth/tokens.py</span> │
|
||
│ <span style="opacity: 0.7;">+++ b/src/auth/tokens.py</span> │
|
||
│ <span style="color: cyan;">@@ -5,3 +5,7 @@</span> │
|
||
│ <span style="color: #ff6666;">- TOKEN_EXPIRY = 3600</span> │
|
||
│ <span style="color: #66cc66;">+ TOKEN_EXPIRY = 7200</span> │
|
||
╰──────────────────────────────────────────╯
|
||
|
||
╭─ Risk Assessment ────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">API Compatibility:</span> preserved │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Test Coverage:</span> maintained │
|
||
│ <span style="color: yellow; font-weight: 600;">Breaking Changes:</span> none detected │
|
||
╰──────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Diff generated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan diff 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Diff Summary
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Project: local/api-service
|
||
Files Changed: 2
|
||
Insertions: 12
|
||
Deletions: 4
|
||
Net Change: +8 lines
|
||
|
||
Files
|
||
Path Change Status
|
||
------------------- ------ --------
|
||
src/auth/session.py +8 -2 modified
|
||
src/auth/tokens.py +4 -2 modified
|
||
|
||
Patch Preview
|
||
--- a/src/auth/session.py
|
||
+++ b/src/auth/session.py
|
||
@@ -12,4 +12,10 @@
|
||
- import jwt
|
||
+ import sessionlib
|
||
- def validate_token(...)
|
||
+ def validate_session(...)
|
||
--- a/src/auth/tokens.py
|
||
+++ b/src/auth/tokens.py
|
||
@@ -5,3 +5,7 @@
|
||
- TOKEN_EXPIRY = 3600
|
||
+ TOKEN_EXPIRY = 7200
|
||
|
||
Risk Assessment
|
||
API Compatibility: preserved
|
||
Test Coverage: maintained
|
||
Breaking Changes: none detected
|
||
|
||
[OK] Diff generated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan diff",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"diff_summary": {
|
||
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"project": "local/api-service",
|
||
"files_changed": 2,
|
||
"insertions": 12,
|
||
"deletions": 4,
|
||
"net_change": "+8 lines"
|
||
},
|
||
"files": [
|
||
{ "path": "src/auth/session.py", "change": "+8 -2", "status": "modified" },
|
||
{ "path": "src/auth/tokens.py", "change": "+4 -2", "status": "modified" }
|
||
],
|
||
"patch_preview": [
|
||
{
|
||
"file": "src/auth/session.py",
|
||
"hunks": [
|
||
{
|
||
"range": "@@ -12,4 +12,10 @@",
|
||
"deletions": ["import jwt", "def validate_token(...)"],
|
||
"insertions": ["import sessionlib", "def validate_session(...)"]
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"file": "src/auth/tokens.py",
|
||
"hunks": [
|
||
{
|
||
"range": "@@ -5,3 +5,7 @@",
|
||
"deletions": ["TOKEN_EXPIRY = 3600"],
|
||
"insertions": ["TOKEN_EXPIRY = 7200"]
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"risk_assessment": {
|
||
"api_compatibility": "preserved",
|
||
"test_coverage": "maintained",
|
||
"breaking_changes": "none detected"
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:30:00Z", "duration_ms": 750 },
|
||
"messages": ["Diff generated"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan diff
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
diff_summary:
|
||
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
project: local/api-service
|
||
files_changed: 2
|
||
insertions: 12
|
||
deletions: 4
|
||
net_change: "+8 lines"
|
||
files:
|
||
- path: src/auth/session.py
|
||
change: "+8 -2"
|
||
status: modified
|
||
- path: src/auth/tokens.py
|
||
change: "+4 -2"
|
||
status: modified
|
||
patch_preview:
|
||
- file: src/auth/session.py
|
||
hunks:
|
||
- range: "@@ -12,4 +12,10 @@"
|
||
deletions:
|
||
- "import jwt"
|
||
- "def validate_token(...)"
|
||
insertions:
|
||
- "import sessionlib"
|
||
- "def validate_session(...)"
|
||
- file: src/auth/tokens.py
|
||
hunks:
|
||
- range: "@@ -5,3 +5,7 @@"
|
||
deletions:
|
||
- "TOKEN_EXPIRY = 3600"
|
||
insertions:
|
||
- "TOKEN_EXPIRY = 7200"
|
||
risk_assessment:
|
||
api_compatibility: preserved
|
||
test_coverage: maintained
|
||
breaking_changes: none detected
|
||
timing:
|
||
started: "2025-06-15T10:30:00Z"
|
||
duration_ms: 750
|
||
messages:
|
||
- "Diff generated"
|
||
```
|
||
|
||
Showing the diff for a specific correction attempt, comparing what changed between the original and corrected execution:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan diff <span style="color: cyan;">--correction</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
|
||
|
||
╭─ Correction Diff ───────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Correction:</span> 01HXM9B7Z3Q1Q8K2E9H7K3W2M8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Original Decision:</span> 01HXM9A1C2Q7W3R5.. │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Mode:</span> revert │
|
||
│ <span style="color: yellow;">Files Changed:</span> 3 │
|
||
│ <span style="color: #66cc66;">New Insertions:</span> 18 │
|
||
│ <span style="color: #ff6666;">New Deletions:</span> 6 │
|
||
╰─────────────────────────────────────────────────╯
|
||
|
||
╭─ Comparison ─────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">File</span> <span style="color: cyan; font-weight: 600;">Before (original)</span> <span style="color: cyan; font-weight: 600;">After (corrected)</span> │
|
||
│ <span style="opacity: 0.7;">──────────────────── ──────────────── ────────────────────</span> │
|
||
│ src/payments/api.py +12 -4 +18 -6 (expanded) │
|
||
│ src/auth/tokens.py +8 -2 (unchanged) │
|
||
│ tests/test_payments.py (new file) (new file, larger) │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Patch Preview (corrected vs original) ───────────╮
|
||
│ <span style="opacity: 0.7;">--- a/src/payments/api.py (original)</span> │
|
||
│ <span style="opacity: 0.7;">+++ b/src/payments/api.py (corrected)</span> │
|
||
│ <span style="color: cyan;">@@ -1,12 +1,18 @@</span> │
|
||
│ <span style="color: #ff6666;">- # sync payment processing</span> │
|
||
│ <span style="color: #66cc66;">+ # async payment processing (corrected)</span> │
|
||
│ <span style="color: #66cc66;">+ import asyncio</span> │
|
||
│ <span style="color: #66cc66;">+ from aiohttp import ClientSession</span> │
|
||
│ <span style="opacity: 0.7;">...</span> │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Correction diff generated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan diff --correction 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
|
||
|
||
Correction Diff
|
||
Correction: 01HXM9B7Z3Q1Q8K2E9H7K3W2M8
|
||
Original Decision: 01HXM9A1C2Q7W3R5..
|
||
Mode: revert
|
||
Files Changed: 3
|
||
New Insertions: 18
|
||
New Deletions: 6
|
||
|
||
Comparison
|
||
File Before (original) After (corrected)
|
||
-------------------- ----------------- --------------------
|
||
src/payments/api.py +12 -4 +18 -6 (expanded)
|
||
src/auth/tokens.py +8 -2 (unchanged)
|
||
tests/test_payments.py (new file) (new file, larger)
|
||
|
||
Patch Preview (corrected vs original)
|
||
--- a/src/payments/api.py (original)
|
||
+++ b/src/payments/api.py (corrected)
|
||
@@ -1,12 +1,18 @@
|
||
- # sync payment processing
|
||
+ # async payment processing (corrected)
|
||
+ import asyncio
|
||
+ from aiohttp import ClientSession
|
||
...
|
||
|
||
[OK] Correction diff generated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan diff",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"correction_diff": {
|
||
"correction": "01HXM9B7Z3Q1Q8K2E9H7K3W2M8",
|
||
"original_decision": "01HXM9A1C2Q7W3R5..",
|
||
"mode": "revert",
|
||
"files_changed": 3,
|
||
"new_insertions": 18,
|
||
"new_deletions": 6
|
||
},
|
||
"comparison": [
|
||
{ "file": "src/payments/api.py", "before": "+12 -4", "after": "+18 -6 (expanded)" },
|
||
{ "file": "src/auth/tokens.py", "before": "+8 -2", "after": "(unchanged)" },
|
||
{ "file": "tests/test_payments.py", "before": "(new file)", "after": "(new file, larger)" }
|
||
],
|
||
"patch_preview": [
|
||
{
|
||
"file": "src/payments/api.py",
|
||
"context": "corrected vs original",
|
||
"hunks": [
|
||
{
|
||
"range": "@@ -1,12 +1,18 @@",
|
||
"deletions": ["# sync payment processing"],
|
||
"insertions": ["# async payment processing (corrected)", "import asyncio", "from aiohttp import ClientSession"]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"timing": { "started": "2025-06-15T10:32:00Z", "duration_ms": 920 },
|
||
"messages": ["Correction diff generated"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan diff
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
correction_diff:
|
||
correction: "01HXM9B7Z3Q1Q8K2E9H7K3W2M8"
|
||
original_decision: "01HXM9A1C2Q7W3R5.."
|
||
mode: revert
|
||
files_changed: 3
|
||
new_insertions: 18
|
||
new_deletions: 6
|
||
comparison:
|
||
- file: src/payments/api.py
|
||
before: "+12 -4"
|
||
after: "+18 -6 (expanded)"
|
||
- file: src/auth/tokens.py
|
||
before: "+8 -2"
|
||
after: "(unchanged)"
|
||
- file: tests/test_payments.py
|
||
before: "(new file)"
|
||
after: "(new file, larger)"
|
||
patch_preview:
|
||
- file: src/payments/api.py
|
||
context: "corrected vs original"
|
||
hunks:
|
||
- range: "@@ -1,12 +1,18 @@"
|
||
deletions:
|
||
- "# sync payment processing"
|
||
insertions:
|
||
- "# async payment processing (corrected)"
|
||
- "import asyncio"
|
||
- "from aiohttp import ClientSession"
|
||
timing:
|
||
started: "2025-06-15T10:32:00Z"
|
||
duration_ms: 920
|
||
messages:
|
||
- "Correction diff generated"
|
||
```
|
||
|
||
##### agents plan artifacts
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan artifacts <span style="color: #66cc66;"><PLAN_ID></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
List artifacts produced by a plan.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
╭─ Artifacts ─────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Path</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Size</span> <span style="color: cyan; font-weight: 600;">Change</span> <span style="color: cyan; font-weight: 600;">Child Plan</span> │
|
||
│ <span style="opacity: 0.7;">───────────────────── ───── ────── ───────── ───────</span> │
|
||
│ src/auth/session.py write 2.1 KB <span style="color: #66cc66; font-weight: 600;">+8 -2</span> root │
|
||
│ tests/test_session.py write 4.7 KB <span style="color: #66cc66; font-weight: 600;">+47 -0</span> root │
|
||
│ src/auth/tokens.py edit 1.8 KB <span style="color: #66cc66; font-weight: 600;">+4 -2</span> root │
|
||
│ tests/test_tokens.py write 3.2 KB <span style="color: #66cc66; font-weight: 600;">+32 -0</span> auth │
|
||
╰─────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ───────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 4 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Writes:</span> 2 (new) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Edits:</span> 2 (modified) │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Deletes:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Size:</span> 11.8 KB │
|
||
╰─────────────────────╯
|
||
|
||
╭─ By Plan ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Root Plan:</span> 3 artifacts │
|
||
│ <span style="color: #5599ff; font-weight: 600;">auth-tests:</span> 1 artifact │
|
||
│ <span style="color: #5599ff; font-weight: 600;">payment-tests:</span> (pending) │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 4 artifacts listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
|
||
Artifacts
|
||
Path Type Size Change Child Plan
|
||
--------------------- ----- ------ --------- ----------
|
||
src/auth/session.py write 2.1 KB +8 -2 root
|
||
tests/test_session.py write 4.7 KB +47 -0 root
|
||
src/auth/tokens.py edit 1.8 KB +4 -2 root
|
||
tests/test_tokens.py write 3.2 KB +32 -0 auth
|
||
|
||
Summary
|
||
Total: 4
|
||
Writes: 2 (new)
|
||
Edits: 2 (modified)
|
||
Deletes: 0
|
||
Total Size: 11.8 KB
|
||
|
||
By Plan
|
||
Root Plan: 3 artifacts
|
||
auth-tests: 1 artifact
|
||
payment-tests: (pending)
|
||
|
||
[OK] 4 artifacts listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan artifacts",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"artifacts": [
|
||
{ "path": "src/auth/session.py", "type": "write", "size": "2.1 KB", "change": "+8 -2", "child_plan": "root" },
|
||
{ "path": "tests/test_session.py", "type": "write", "size": "4.7 KB", "change": "+47 -0", "child_plan": "root" },
|
||
{ "path": "src/auth/tokens.py", "type": "edit", "size": "1.8 KB", "change": "+4 -2", "child_plan": "root" },
|
||
{ "path": "tests/test_tokens.py", "type": "write", "size": "3.2 KB", "change": "+32 -0", "child_plan": "auth" }
|
||
],
|
||
"summary": {
|
||
"total": 4,
|
||
"writes": 2,
|
||
"edits": 2,
|
||
"deletes": 0,
|
||
"total_size": "11.8 KB"
|
||
},
|
||
"by_plan": {
|
||
"root": 3,
|
||
"auth-tests": 1,
|
||
"payment-tests": "pending"
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:33:00Z", "duration_ms": 480 },
|
||
"messages": ["4 artifacts listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan artifacts
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
artifacts:
|
||
- path: src/auth/session.py
|
||
type: write
|
||
size: "2.1 KB"
|
||
change: "+8 -2"
|
||
child_plan: root
|
||
- path: tests/test_session.py
|
||
type: write
|
||
size: "4.7 KB"
|
||
change: "+47 -0"
|
||
child_plan: root
|
||
- path: src/auth/tokens.py
|
||
type: edit
|
||
size: "1.8 KB"
|
||
change: "+4 -2"
|
||
child_plan: root
|
||
- path: tests/test_tokens.py
|
||
type: write
|
||
size: "3.2 KB"
|
||
change: "+32 -0"
|
||
child_plan: auth
|
||
summary:
|
||
total: 4
|
||
writes: 2
|
||
edits: 2
|
||
deletes: 0
|
||
total_size: "11.8 KB"
|
||
by_plan:
|
||
root: 3
|
||
auth-tests: 1
|
||
payment-tests: pending
|
||
timing:
|
||
started: "2025-06-15T10:33:00Z"
|
||
duration_ms: 480
|
||
messages:
|
||
- "4 artifacts listed"
|
||
```
|
||
|
||
##### agents plan prompt
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan prompt <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><GUIDANCE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Provide additional guidance to a plan, typically when it is errored or awaiting input.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID.
|
||
- `"<GUIDANCE>"`: Guidance text.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: #66cc66;">"Use mocks for database tests"</span>
|
||
|
||
╭─ Guidance Added ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: magenta; font-weight: 600;">Guidance:</span> Use mocks for database tests │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> next execution step │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: #5599ff; font-weight: 600;">State:</span> errored → processing │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Decision Created ────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> user_intervention │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> 01HXM9C5G7R2X8S3K4Z5Q8R6Y3 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Parent:</span> 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 │
|
||
╰───────────────────────────────────────────╯
|
||
|
||
╭─ Queue ────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Pending:</span> 1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Applied:</span> 0 │
|
||
╰────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Guidance queued
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan prompt 01HXM8C2ZK4Q7C2B3F2R4VYV6J "Use mocks for database tests"
|
||
|
||
Guidance Added
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Guidance: Use mocks for database tests
|
||
Scope: next execution step
|
||
Phase: execute
|
||
State: errored -> processing
|
||
|
||
Decision Created
|
||
Type: user_intervention
|
||
ID: 01HXM9C5G7R2X8S3K4Z5Q8R6Y3
|
||
Parent: 01HXM9A1C2Q7W3R5G8Z0P4Q1X9
|
||
|
||
Queue
|
||
Pending: 1
|
||
Applied: 0
|
||
|
||
[OK] Guidance queued
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan prompt",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"guidance_added": {
|
||
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"guidance": "Use mocks for database tests",
|
||
"scope": "next execution step",
|
||
"phase": "execute",
|
||
"state_transition": "errored -> processing"
|
||
},
|
||
"decision_created": {
|
||
"type": "user_intervention",
|
||
"id": "01HXM9C5G7R2X8S3K4Z5Q8R6Y3",
|
||
"parent": "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
},
|
||
"queue": {
|
||
"pending": 1,
|
||
"applied": 0
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:35:00Z", "duration_ms": 620 },
|
||
"messages": ["Guidance queued"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan prompt
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
guidance_added:
|
||
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
guidance: "Use mocks for database tests"
|
||
scope: next execution step
|
||
phase: execute
|
||
state_transition: "errored -> processing"
|
||
decision_created:
|
||
type: user_intervention
|
||
id: "01HXM9C5G7R2X8S3K4Z5Q8R6Y3"
|
||
parent: "01HXM9A1C2Q7W3R5G8Z0P4Q1X9"
|
||
queue:
|
||
pending: 1
|
||
applied: 0
|
||
timing:
|
||
started: "2025-06-15T10:35:00Z"
|
||
duration_ms: 620
|
||
messages:
|
||
- "Guidance queued"
|
||
```
|
||
|
||
##### agents plan rollback
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> plan rollback [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><PLAN_ID></span> <span style="color: #66cc66;"><CHECKPOINT_ID></span></code></pre></div>
|
||
|
||
!!! danger "Destructive Operation"
|
||
Rollback a plan sandbox to a previous checkpoint. All changes made ==after== the target checkpoint are **reverted**: files are restored or removed, decisions are discarded, and tool calls are undone. Child plans spawned after the checkpoint are invalidated.
|
||
|
||
**Arguments**
|
||
|
||
- `<PLAN_ID>`: Plan ID.
|
||
- `<CHECKPOINT_ID>`: Checkpoint ID.
|
||
- `--yes`: Skip confirmation.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
|
||
|
||
Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
|
||
|
||
╭─ Rollback Summary ───────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: magenta; font-weight: 600;">Checkpoint:</span> cp_01HXM8C2 │
|
||
│ <span style="color: yellow; font-weight: 600;">Label:</span> before auth refactor │
|
||
│ <span style="color: yellow; font-weight: 600;">Files:</span> 6 reverted │
|
||
╰──────────────────────────────────╯
|
||
|
||
╭─ Changes Reverted ──────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">File</span> <span style="color: yellow; font-weight: 600;">Action</span> │
|
||
│ <span style="opacity: 0.7;">────────────────────── ──────────</span> │
|
||
│ src/auth/session.py restored │
|
||
│ src/auth/tokens.py restored │
|
||
│ tests/test_session.py removed │
|
||
│ tests/test_tokens.py removed │
|
||
│ src/auth/fixtures.py restored │
|
||
│ src/auth/__init__.py restored │
|
||
╰─────────────────────────────────────╯
|
||
|
||
╭─ Impact ──────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Child Plans Invalidated:</span> 2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sandbox:</span> restored to cp_01HXM8C2 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Decisions After CP:</span> 2 discarded │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Tool Calls After CP:</span> 5 undone │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Post-Rollback State ──────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Phase:</span> execute │
|
||
│ <span style="color: #5599ff; font-weight: 600;">State:</span> queued (awaiting input) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Checkpoints Remaining:</span> 2 │
|
||
╰────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Rollback complete
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents plan rollback 01HXM8C2ZK4Q7C2B3F2R4VYV6J cp_01HXM8C2
|
||
|
||
Rollback plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J to cp_01HXM8C2? [y/N]: y
|
||
|
||
Rollback Summary
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Checkpoint: cp_01HXM8C2
|
||
Label: before auth refactor
|
||
Files: 6 reverted
|
||
|
||
Changes Reverted
|
||
File Action
|
||
---------------------- ----------
|
||
src/auth/session.py restored
|
||
src/auth/tokens.py restored
|
||
tests/test_session.py removed
|
||
tests/test_tokens.py removed
|
||
src/auth/fixtures.py restored
|
||
src/auth/__init__.py restored
|
||
|
||
Impact
|
||
Child Plans Invalidated: 2
|
||
Sandbox: restored to cp_01HXM8C2
|
||
Decisions After CP: 2 discarded
|
||
Tool Calls After CP: 5 undone
|
||
|
||
Post-Rollback State
|
||
Phase: execute
|
||
State: queued (awaiting input)
|
||
Checkpoints Remaining: 2
|
||
|
||
[OK] Rollback complete
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "plan rollback",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"rollback_summary": {
|
||
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"checkpoint": "cp_01HXM8C2",
|
||
"label": "before auth refactor",
|
||
"files_reverted": 6
|
||
},
|
||
"changes_reverted": [
|
||
{ "file": "src/auth/session.py", "action": "restored" },
|
||
{ "file": "src/auth/tokens.py", "action": "restored" },
|
||
{ "file": "tests/test_session.py", "action": "removed" },
|
||
{ "file": "tests/test_tokens.py", "action": "removed" },
|
||
{ "file": "src/auth/fixtures.py", "action": "restored" },
|
||
{ "file": "src/auth/__init__.py", "action": "restored" }
|
||
],
|
||
"impact": {
|
||
"child_plans_invalidated": 2,
|
||
"sandbox": "restored to cp_01HXM8C2",
|
||
"decisions_after_cp": "2 discarded",
|
||
"tool_calls_after_cp": "5 undone"
|
||
},
|
||
"post_rollback_state": {
|
||
"phase": "execute",
|
||
"state": "queued (awaiting input)",
|
||
"checkpoints_remaining": 2
|
||
}
|
||
},
|
||
"timing": { "started": "2025-06-15T10:37:00Z", "duration_ms": 1850 },
|
||
"messages": ["Rollback complete"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: plan rollback
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
rollback_summary:
|
||
plan: "01HXM8C2ZK4Q7C2B3F2R4VYV6J"
|
||
checkpoint: cp_01HXM8C2
|
||
label: before auth refactor
|
||
files_reverted: 6
|
||
changes_reverted:
|
||
- file: src/auth/session.py
|
||
action: restored
|
||
- file: src/auth/tokens.py
|
||
action: restored
|
||
- file: tests/test_session.py
|
||
action: removed
|
||
- file: tests/test_tokens.py
|
||
action: removed
|
||
- file: src/auth/fixtures.py
|
||
action: restored
|
||
- file: src/auth/__init__.py
|
||
action: restored
|
||
impact:
|
||
child_plans_invalidated: 2
|
||
sandbox: "restored to cp_01HXM8C2"
|
||
decisions_after_cp: "2 discarded"
|
||
tool_calls_after_cp: "5 undone"
|
||
post_rollback_state:
|
||
phase: execute
|
||
state: "queued (awaiting input)"
|
||
checkpoints_remaining: 2
|
||
timing:
|
||
started: "2025-06-15T10:37:00Z"
|
||
duration_ms: 1850
|
||
messages:
|
||
- "Rollback complete"
|
||
```
|
||
|
||
#### agents action
|
||
|
||
!!! info "Purpose"
|
||
Manage ==reusable actions== — named templates that define a complete unit of work including strategy actors, execution actors, definition of done, arguments, and invariants. Actions serve as the entry point to the plan lifecycle.
|
||
|
||
??? tip "Action vs Plan"
|
||
An **action** is a ==template==; a **plan** is an ==instance==. When you run `agents plan use <ACTION> <PROJECT>`, the action template spawns a new plan that progresses through the lifecycle phases. Actions can be reused many times (default) or configured as single-use (`reusable: false`).
|
||
|
||
##### agents action create
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><CFG_FILE></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Create a new action template from a YAML configuration file. The `--config` file is required and must fully define the action.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: YAML configuration file defining the action (required). The file must fully define the action, including the `name` field, `strategy-actor`, `execution-actor`, and `definition-of-done`.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action create <span style="color: cyan;">--config</span> ./actions/code-coverage.yaml
|
||
|
||
╭─ Action Created ────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/code-coverage │
|
||
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
|
||
│ <span style="color: magenta; font-weight: 600;">Strategy Actor:</span> local/strategist │
|
||
│ <span style="color: magenta; font-weight: 600;">Execution Actor:</span> local/executor │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Reusable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read Only:</span> no │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Config:</span> ./actions/code-coverage.yaml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:20 │
|
||
╰─────────────────────────────────────────╯
|
||
|
||
╭─ Definition of Done ─╮
|
||
│ Coverage reaches 85% │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Arguments ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">─────────────────────── ────── ──────── ─────────────────────</span> │
|
||
│ target_coverage_percent int yes Target coverage % │
|
||
│ test_command string no Test framework to use │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Automation ──────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Profile:</span> supervised │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> default │
|
||
╰───────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action created
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents action create --config ./actions/code-coverage.yaml
|
||
|
||
Action Created
|
||
Name: local/code-coverage
|
||
State: available
|
||
Strategy Actor: local/strategist
|
||
Execution Actor: local/executor
|
||
Reusable: yes
|
||
Read Only: no
|
||
Config: ./actions/code-coverage.yaml
|
||
Created: 2026-02-08 12:20
|
||
|
||
Definition of Done
|
||
Coverage reaches 85%
|
||
|
||
Arguments
|
||
Name Type Required Description
|
||
----------------------- ------ -------- ---------------------
|
||
target_coverage_percent int yes Target coverage %
|
||
test_command string no Test framework to use
|
||
|
||
Automation
|
||
Profile: supervised
|
||
Source: default
|
||
|
||
[OK] Action created
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "action create",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/code-coverage",
|
||
"state": "available",
|
||
"strategy_actor": "local/strategist",
|
||
"execution_actor": "local/executor",
|
||
"reusable": true,
|
||
"read_only": false,
|
||
"config": "./actions/code-coverage.yaml",
|
||
"created": "2026-02-08T12:20:00Z",
|
||
"definition_of_done": "Coverage reaches 85%",
|
||
"arguments": [
|
||
{ "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" },
|
||
{ "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" }
|
||
],
|
||
"automation": {
|
||
"profile": "supervised",
|
||
"source": "default"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T12:20:00Z", "duration_ms": 110 },
|
||
"messages": ["Action created"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: action create
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/code-coverage
|
||
state: available
|
||
strategy_actor: local/strategist
|
||
execution_actor: local/executor
|
||
reusable: true
|
||
read_only: false
|
||
config: "./actions/code-coverage.yaml"
|
||
created: "2026-02-08T12:20:00Z"
|
||
definition_of_done: "Coverage reaches 85%"
|
||
arguments:
|
||
- name: target_coverage_percent
|
||
type: int
|
||
required: true
|
||
description: "Target coverage %"
|
||
- name: test_command
|
||
type: string
|
||
required: false
|
||
description: "Test framework to use"
|
||
automation:
|
||
profile: supervised
|
||
source: default
|
||
timing:
|
||
started: "2026-02-08T12:20:00Z"
|
||
duration_ms: 110
|
||
messages:
|
||
- "Action created"
|
||
```
|
||
|
||
##### agents action list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> action list [(<span style="color: magenta;"><span style="color: cyan;">--namespace</span>|<span style="color: yellow;">-n</span></span>) <span style="color: #66cc66;"><NS></span>] [(<span style="color: magenta;"><span style="color: cyan;">--state</span>|<span style="color: yellow;">-s</span></span>) <span style="color: #66cc66;"><STATE></span>] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List actions with optional filters.
|
||
|
||
**Arguments**
|
||
|
||
- `--namespace/-n NS`: Filter by namespace.
|
||
- `--state/-s STATE`: Filter by state.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action list
|
||
|
||
╭─ Actions ──────────────────────────────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">State</span> <span style="color: cyan; font-weight: 600;">Strategy Actor</span> <span style="color: cyan; font-weight: 600;">Execution Actor</span> <span style="color: cyan; font-weight: 600;">Reusable</span> <span style="color: cyan; font-weight: 600;">Plans</span> │
|
||
│ <span style="opacity: 0.7;">─────────────────── ───────── ──────────────── ─────────────── ──────── ─────</span> │
|
||
│ local/code-coverage available local/strategist local/executor ✓ 3 │
|
||
╰────────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Filters ────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Namespace:</span> (any) │
|
||
╰──────────────────╯
|
||
|
||
╭─ Summary ──────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Total:</span> 1 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Available:</span> 1 │
|
||
│ <span style="color: yellow; font-weight: 600;">Archived:</span> 0 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Plans Created:</span> 3 │
|
||
╰────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 1 action listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents action list
|
||
|
||
Actions
|
||
Name State Strategy Actor Execution Actor Reusable Plans
|
||
------------------- --------- ---------------- --------------- -------- -----
|
||
local/code-coverage available local/strategist local/executor yes 3
|
||
|
||
Filters
|
||
State: available
|
||
Namespace: (any)
|
||
|
||
Summary
|
||
Total: 1
|
||
Available: 1
|
||
Archived: 0
|
||
Total Plans Created: 3
|
||
|
||
[OK] 1 action listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "action list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"actions": [
|
||
{
|
||
"name": "local/code-coverage",
|
||
"state": "available",
|
||
"strategy_actor": "local/strategist",
|
||
"execution_actor": "local/executor",
|
||
"reusable": true,
|
||
"plans": 3
|
||
}
|
||
],
|
||
"filters": { "state": "available", "namespace": null },
|
||
"summary": { "total": 1, "available": 1, "archived": 0, "total_plans_created": 3 }
|
||
},
|
||
"timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 45 },
|
||
"messages": ["1 action listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: action list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
actions:
|
||
- name: local/code-coverage
|
||
state: available
|
||
strategy_actor: local/strategist
|
||
execution_actor: local/executor
|
||
reusable: true
|
||
plans: 3
|
||
filters:
|
||
state: available
|
||
namespace: null
|
||
summary:
|
||
total: 1
|
||
available: 1
|
||
archived: 0
|
||
total_plans_created: 3
|
||
timing:
|
||
started: "2026-02-08T12:21:00Z"
|
||
duration_ms: 45
|
||
messages:
|
||
- "1 action listed"
|
||
```
|
||
|
||
##### agents action show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> action show <span style="color: #66cc66;"><ACTION_NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show details for an action.
|
||
|
||
**Arguments**
|
||
|
||
- `<ACTION_NAME>`: Action name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action show local/code-coverage
|
||
|
||
╭─ Action Details ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/code-coverage │
|
||
│ <span style="color: yellow; font-weight: 600;">State:</span> available │
|
||
│ <span style="color: magenta; font-weight: 600;">Strategy Actor:</span> local/strategist │
|
||
│ <span style="color: magenta; font-weight: 600;">Execution Actor:</span> local/executor │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Reusable:</span> yes │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Read Only:</span> no │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 12:20 │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Definition of Done ─╮
|
||
│ Coverage reaches 85% │
|
||
╰──────────────────────╯
|
||
|
||
╭─ Arguments ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Type</span> <span style="color: cyan; font-weight: 600;">Required</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">─────────────────────── ────── ──────── ─────────────────────</span> │
|
||
│ target_coverage_percent int yes Target coverage % │
|
||
│ test_command string no Test framework to use │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Automation ──────────────────────────╮
|
||
│ <span style="color: magenta; font-weight: 600;">Profile:</span> supervised │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> default │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ History ────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Plans Created:</span> 3 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Plans Completed:</span> 2 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Plans Failed:</span> 0 │
|
||
│ <span style="color: yellow; font-weight: 600;">Avg Duration:</span> 00:04:30 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Avg Cost:</span> $0.072 │
|
||
╰──────────────────────────────╯
|
||
|
||
╭─ Usage ───────────────────────────────────────────────────────────╮
|
||
│ - agents plan use local/code-coverage local/api-service │
|
||
│ <span style="color: cyan;">--arg</span> target_coverage_percent=85 │
|
||
╰───────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents action show local/code-coverage
|
||
|
||
Action Details
|
||
Name: local/code-coverage
|
||
State: available
|
||
Strategy Actor: local/strategist
|
||
Execution Actor: local/executor
|
||
Reusable: yes
|
||
Read Only: no
|
||
Created: 2026-02-08 12:20
|
||
|
||
Definition of Done
|
||
Coverage reaches 85%
|
||
|
||
Arguments
|
||
Name Type Required Description
|
||
----------------------- ------ -------- ---------------------
|
||
target_coverage_percent int yes Target coverage %
|
||
test_command string no Test framework to use
|
||
|
||
Automation
|
||
Profile: supervised
|
||
Source: default
|
||
|
||
History
|
||
Plans Created: 3
|
||
Plans Completed: 2
|
||
Plans Failed: 0
|
||
Avg Duration: 00:04:30
|
||
Avg Cost: $0.072
|
||
|
||
Usage
|
||
agents plan use local/code-coverage local/api-service
|
||
--arg target_coverage_percent=85
|
||
|
||
[OK] Action loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "action show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/code-coverage",
|
||
"state": "available",
|
||
"strategy_actor": "local/strategist",
|
||
"execution_actor": "local/executor",
|
||
"reusable": true,
|
||
"read_only": false,
|
||
"created": "2026-02-08T12:20:00Z",
|
||
"definition_of_done": "Coverage reaches 85%",
|
||
"arguments": [
|
||
{ "name": "target_coverage_percent", "type": "int", "required": true, "description": "Target coverage %" },
|
||
{ "name": "test_command", "type": "string", "required": false, "description": "Test framework to use" }
|
||
],
|
||
"automation": { "profile": "supervised", "source": "default" },
|
||
"history": {
|
||
"plans_created": 3,
|
||
"plans_completed": 2,
|
||
"plans_failed": 0,
|
||
"avg_duration": "00:04:30",
|
||
"avg_cost": "$0.072"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T12:21:00Z", "duration_ms": 60 },
|
||
"messages": ["Action loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: action show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/code-coverage
|
||
state: available
|
||
strategy_actor: local/strategist
|
||
execution_actor: local/executor
|
||
reusable: true
|
||
read_only: false
|
||
created: "2026-02-08T12:20:00Z"
|
||
definition_of_done: "Coverage reaches 85%"
|
||
arguments:
|
||
- name: target_coverage_percent
|
||
type: int
|
||
required: true
|
||
description: "Target coverage %"
|
||
- name: test_command
|
||
type: string
|
||
required: false
|
||
description: "Test framework to use"
|
||
automation:
|
||
profile: supervised
|
||
source: default
|
||
history:
|
||
plans_created: 3
|
||
plans_completed: 2
|
||
plans_failed: 0
|
||
avg_duration: "00:04:30"
|
||
avg_cost: "$0.072"
|
||
timing:
|
||
started: "2026-02-08T12:21:00Z"
|
||
duration_ms: 60
|
||
messages:
|
||
- "Action loaded"
|
||
```
|
||
|
||
##### agents action archive
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> action archive <span style="color: #66cc66;"><ACTION_NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Archive an action.
|
||
|
||
**Arguments**
|
||
|
||
- `<ACTION_NAME>`: Action name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> action archive local/old-action
|
||
|
||
╭─ Action Archived ───────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/old-action │
|
||
│ <span style="color: yellow; font-weight: 600;">State:</span> available → archived │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Archived:</span> 2026-02-08 12:22 │
|
||
╰─────────────────────────────╯
|
||
|
||
╭─ Impact ───────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Availability:</span> hidden from list │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Existing Plans:</span> unchanged │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Active Plans:</span> 0 affected │
|
||
╰────────────────────────────────╯
|
||
|
||
╭─ History ─────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total Plans:</span> 5 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Completed:</span> 4 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">Failed:</span> 1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Last Used:</span> 2026-02-06 │
|
||
╰───────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Action archived
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents action archive local/old-action
|
||
|
||
Action Archived
|
||
Name: local/old-action
|
||
State: available -> archived
|
||
Archived: 2026-02-08 12:22
|
||
|
||
Impact
|
||
Availability: hidden from list
|
||
Existing Plans: unchanged
|
||
Active Plans: 0 affected
|
||
|
||
History
|
||
Total Plans: 5
|
||
Completed: 4
|
||
Failed: 1
|
||
Last Used: 2026-02-06
|
||
|
||
[OK] Action archived
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "action archive",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/old-action",
|
||
"state_transition": "available -> archived",
|
||
"archived": "2026-02-08T12:22:00Z",
|
||
"impact": {
|
||
"availability": "hidden from list",
|
||
"existing_plans": "unchanged",
|
||
"active_plans_affected": 0
|
||
},
|
||
"history": {
|
||
"total_plans": 5,
|
||
"completed": 4,
|
||
"failed": 1,
|
||
"last_used": "2026-02-06"
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T12:22:00Z", "duration_ms": 55 },
|
||
"messages": ["Action archived"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: action archive
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/old-action
|
||
state_transition: "available -> archived"
|
||
archived: "2026-02-08T12:22:00Z"
|
||
impact:
|
||
availability: hidden from list
|
||
existing_plans: unchanged
|
||
active_plans_affected: 0
|
||
history:
|
||
total_plans: 5
|
||
completed: 4
|
||
failed: 1
|
||
last_used: "2026-02-06"
|
||
timing:
|
||
started: "2026-02-08T12:22:00Z"
|
||
duration_ms: 55
|
||
messages:
|
||
- "Action archived"
|
||
```
|
||
|
||
#### agents automation-profile
|
||
|
||
!!! info "Purpose"
|
||
Manage ==automation profiles== — named collections of confidence thresholds (floating-point values from `0.0` to `1.0`) that control which tasks are automated vs. require human approval. Each threshold specifies the minimum confidence level at which the system proceeds automatically; below the threshold, the system drops to manual mode.
|
||
|
||
!!! tip "Threshold Scale"
|
||
| Value | Meaning |
|
||
| :---: | :------ |
|
||
| `0.0` | ==Always automatic== — no human approval needed |
|
||
| `0.5` | Automatic when confidence ≥ 50% |
|
||
| `1.0` | ==Always manual== — always requires human approval |
|
||
|
||
??? example "Built-in Profiles"
|
||
The following profiles are always available and cannot be removed:
|
||
|
||
| Profile | Description |
|
||
| :------ | :---------- |
|
||
| `manual` | All thresholds at `1.0` — everything requires approval |
|
||
| `review` | Automatic strategize and execute, manual apply |
|
||
| `supervised` | Automatic strategize, manual execute and apply |
|
||
| `cautious` | Most operations automatic, manual for risky decisions |
|
||
| `trusted` | Nearly fully automatic, manual only for apply |
|
||
| `auto` | Fully automatic except apply |
|
||
| `ci` | Optimized for CI/CD pipelines |
|
||
| `full-auto` | All thresholds at `0.0` — fully autonomous |
|
||
|
||
Custom profiles follow the same `<namespace>/<name>` naming convention as other entities.
|
||
|
||
##### agents automation-profile add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> automation-profile add <span style="color: cyan;">--config</span>|<span style="color: yellow;">-c</span> <span style="color: #66cc66;"><FILE></span> [<span style="color: cyan;">--update</span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
Register a new custom automation profile from a YAML configuration file. The profile is fully defined by the config file. If a profile with the same name already exists, the command fails unless the `--update` flag is provided.
|
||
|
||
**Arguments**
|
||
|
||
- `--config/-c FILE`: YAML configuration file defining the profile (required). The file must fully define the profile, including the `name` field which determines the profile's registered name.
|
||
- `--update`: Replace an existing profile with the same name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile add <span style="color: cyan;">--config</span> ./profiles/careful-auto.yaml
|
||
|
||
╭─ Profile Registered ─────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/careful-auto │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Autonomous execution with mandatory sandbox │
|
||
│ and manual apply │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Created:</span> 2026-02-08 14:30 │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Confidence Thresholds ────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">decompose_task:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">create_tool:</span> 0.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">select_tool:</span> 1.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">edit_code:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">execute_command:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">create_file:</span> 0.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">delete_content:</span> 1.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">access_network:</span> 1.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">install_dependency:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">modify_config:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">approve_plan:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">require_sandbox:</span> true │
|
||
│ <span style="color: #66cc66; font-weight: 600;">require_checkpoints:</span> true │
|
||
│ <span style="color: #ff6666; font-weight: 600;">allow_unsafe_tools:</span> false │
|
||
╰────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile registered
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents automation-profile add --config ./profiles/careful-auto.yaml
|
||
|
||
Profile Registered
|
||
Name: local/careful-auto
|
||
Description: Autonomous execution with mandatory sandbox and manual apply
|
||
Created: 2026-02-08 14:30
|
||
|
||
Confidence Thresholds
|
||
decompose_task: 0.0
|
||
create_tool: 0.0
|
||
select_tool: 1.0
|
||
edit_code: 0.0
|
||
execute_command: 0.0
|
||
create_file: 0.0
|
||
delete_content: 1.0
|
||
access_network: 1.0
|
||
install_dependency: 0.0
|
||
modify_config: 0.0
|
||
approve_plan: 0.0
|
||
require_sandbox: true
|
||
require_checkpoints: true
|
||
allow_unsafe_tools: false
|
||
|
||
[OK] Profile registered
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "automation-profile add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/careful-auto",
|
||
"description": "Autonomous execution with mandatory sandbox and manual apply",
|
||
"created": "2026-02-08T14:30:00Z",
|
||
"thresholds": {
|
||
"decompose_task": 0.0,
|
||
"create_tool": 0.0,
|
||
"select_tool": 1.0,
|
||
"edit_code": 0.0,
|
||
"execute_command": 0.0,
|
||
"create_file": 0.0,
|
||
"delete_content": 1.0,
|
||
"access_network": 1.0,
|
||
"install_dependency": 0.0,
|
||
"modify_config": 0.0,
|
||
"approve_plan": 0.0
|
||
},
|
||
"flags": {
|
||
"require_sandbox": true,
|
||
"require_checkpoints": true,
|
||
"allow_unsafe_tools": false
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T14:30:00Z", "duration_ms": 70 },
|
||
"messages": ["Profile registered"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: automation-profile add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/careful-auto
|
||
description: "Autonomous execution with mandatory sandbox and manual apply"
|
||
created: "2026-02-08T14:30:00Z"
|
||
thresholds:
|
||
decompose_task: 0.0
|
||
create_tool: 0.0
|
||
select_tool: 1.0
|
||
edit_code: 0.0
|
||
execute_command: 0.0
|
||
create_file: 0.0
|
||
delete_content: 1.0
|
||
access_network: 1.0
|
||
install_dependency: 0.0
|
||
modify_config: 0.0
|
||
approve_plan: 0.0
|
||
flags:
|
||
require_sandbox: true
|
||
require_checkpoints: true
|
||
allow_unsafe_tools: false
|
||
timing:
|
||
started: "2026-02-08T14:30:00Z"
|
||
duration_ms: 70
|
||
messages:
|
||
- "Profile registered"
|
||
```
|
||
|
||
##### agents automation-profile remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> automation-profile remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
!!! warning "Destructive Operation"
|
||
Remove a custom automation profile. ==Built-in profiles cannot be removed.== Plans and projects currently referencing this profile will fall back to their inherited or global default profile.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Profile name.
|
||
- `--yes, -y`: Skip confirmation prompt.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile remove local/careful-auto
|
||
|
||
Remove automation profile local/careful-auto? [y/N]: y
|
||
|
||
╭─ Profile Removed ──────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> local/careful-auto │
|
||
╰────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents automation-profile remove local/careful-auto
|
||
|
||
Remove automation profile local/careful-auto? [y/N]: y
|
||
|
||
Profile Removed
|
||
Name: local/careful-auto
|
||
|
||
[OK] Profile removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "automation-profile remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "local/careful-auto"
|
||
},
|
||
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 40 },
|
||
"messages": ["Profile removed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: automation-profile remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: local/careful-auto
|
||
timing:
|
||
started: "2026-02-08T14:31:00Z"
|
||
duration_ms: 40
|
||
messages:
|
||
- "Profile removed"
|
||
```
|
||
|
||
##### agents automation-profile list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> automation-profile list [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List all available automation profiles (built-in and custom).
|
||
|
||
**Arguments**
|
||
|
||
- `[REGEX]`: Optional filter pattern.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile list
|
||
|
||
╭─ Automation Profiles ──────────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Auto-Apply</span> <span style="color: cyan; font-weight: 600;">Sandbox</span> <span style="color: cyan; font-weight: 600;">Description</span> │
|
||
│ <span style="opacity: 0.7;">────────────────── ──────── ────────── ─────── ────────────────────────</span> │
|
||
│ manual built-in 1.0 yes Human-driven (default) │
|
||
│ review built-in 1.0 yes Auto-phase, manual decisions │
|
||
│ supervised built-in 1.0 yes Auto-plan, manual exec │
|
||
│ cautious built-in 1.0 yes Confidence-gated automation │
|
||
│ trusted built-in 1.0 yes Auto-exec, manual apply │
|
||
│ auto built-in 1.0 yes Full auto except apply │
|
||
│ ci built-in 0.0 yes Full auto, safe CI/CD │
|
||
│ full-auto built-in 0.0 no Complete automation │
|
||
│ local/careful-auto custom 0.8 yes Custom careful profile │
|
||
╰────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Summary ───────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Built-in:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Custom:</span> 1 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Total:</span> 9 │
|
||
╰─────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 9 profiles listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents automation-profile list
|
||
|
||
Automation Profiles
|
||
Name Source Auto-Apply Sandbox Description
|
||
------------------ -------- ---------- ------- ----------------------------
|
||
manual built-in 1.0 yes Human-driven (default)
|
||
review built-in 1.0 yes Auto-phase, manual decisions
|
||
supervised built-in 1.0 yes Auto-plan, manual exec
|
||
cautious built-in 1.0 yes Confidence-gated automation
|
||
trusted built-in 1.0 yes Auto-exec, manual apply
|
||
auto built-in 1.0 yes Full auto except apply
|
||
ci built-in 0.0 yes Full auto, safe CI/CD
|
||
full-auto built-in 0.0 no Complete automation
|
||
local/careful-auto custom 0.8 yes Custom careful profile
|
||
|
||
Summary
|
||
Built-in: 8
|
||
Custom: 1
|
||
Total: 9
|
||
|
||
[OK] 9 profiles listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "automation-profile list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"profiles": [
|
||
{ "name": "manual", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Human-driven (default)" },
|
||
{ "name": "review", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-phase, manual decisions" },
|
||
{ "name": "supervised", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-plan, manual exec" },
|
||
{ "name": "cautious", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Confidence-gated automation" },
|
||
{ "name": "trusted", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Auto-exec, manual apply" },
|
||
{ "name": "auto", "source": "built-in", "select_tool": 1.0, "sandbox": true, "description": "Full auto except apply" },
|
||
{ "name": "ci", "source": "built-in", "select_tool": 0.0, "sandbox": true, "description": "Full auto, safe CI/CD" },
|
||
{ "name": "full-auto", "source": "built-in", "select_tool": 0.0, "sandbox": false, "description": "Complete automation" },
|
||
{ "name": "local/careful-auto", "source": "custom", "select_tool": 0.8, "sandbox": true, "description": "Custom careful profile" }
|
||
],
|
||
"summary": { "built_in": 8, "custom": 1, "total": 9 }
|
||
},
|
||
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 50 },
|
||
"messages": ["9 profiles listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: automation-profile list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
profiles:
|
||
- name: manual
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Human-driven (default)"
|
||
- name: review
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Auto-phase, manual decisions"
|
||
- name: supervised
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Auto-plan, manual exec"
|
||
- name: cautious
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Confidence-gated automation"
|
||
- name: trusted
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Auto-exec, manual apply"
|
||
- name: auto
|
||
source: built-in
|
||
select_tool: 1.0
|
||
sandbox: true
|
||
description: "Full auto except apply"
|
||
- name: ci
|
||
source: built-in
|
||
select_tool: 0.0
|
||
sandbox: true
|
||
description: "Full auto, safe CI/CD"
|
||
- name: full-auto
|
||
source: built-in
|
||
select_tool: 0.0
|
||
sandbox: false
|
||
description: "Complete automation"
|
||
- name: local/careful-auto
|
||
source: custom
|
||
select_tool: 0.8
|
||
sandbox: true
|
||
description: "Custom careful profile"
|
||
summary:
|
||
built_in: 8
|
||
custom: 1
|
||
total: 9
|
||
timing:
|
||
started: "2026-02-08T14:31:00Z"
|
||
duration_ms: 50
|
||
messages:
|
||
- "9 profiles listed"
|
||
```
|
||
|
||
##### agents automation-profile show
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> automation-profile show <span style="color: #66cc66;"><NAME></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Show full details for an automation profile, including all flag values.
|
||
|
||
**Arguments**
|
||
|
||
- `<NAME>`: Profile name.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> automation-profile show trusted
|
||
|
||
╭─ Automation Profile ───────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Name:</span> trusted │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> built-in │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Description:</span> Auto-exec, manual apply. Day-to-day development │
|
||
╰────────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Phase Transitions (thresholds) ─────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">decompose_task:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">create_tool:</span> 0.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">select_tool:</span> 1.0 │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Decision Automation (thresholds) ───╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">edit_code:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">execute_command:</span> 0.0 │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Self-Repair (thresholds) ───────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">create_file:</span> 0.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">delete_content:</span> 1.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">access_network:</span> 1.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">modify_config:</span> 0.0 │
|
||
│ <span style="color: #ff6666; font-weight: 600;">approve_plan:</span> 1.0 │
|
||
╰──────────────────────────────────────╯
|
||
|
||
╭─ Execution Controls (thresholds) ────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">install_dependency:</span> 0.0 │
|
||
│ <span style="color: #66cc66; font-weight: 600;">require_sandbox:</span> true │
|
||
│ <span style="color: #66cc66; font-weight: 600;">require_checkpoints:</span> true │
|
||
│ <span style="color: #ff6666; font-weight: 600;">allow_unsafe_tools:</span> false │
|
||
╰──────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Profile loaded
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents automation-profile show trusted
|
||
|
||
Automation Profile
|
||
Name: trusted
|
||
Source: built-in
|
||
Description: Auto-exec, manual apply. Day-to-day development
|
||
|
||
Phase Transitions (thresholds)
|
||
decompose_task: 0.0
|
||
create_tool: 0.0
|
||
select_tool: 1.0
|
||
|
||
Decision Automation (thresholds)
|
||
edit_code: 0.0
|
||
execute_command: 0.0
|
||
|
||
Self-Repair (thresholds)
|
||
create_file: 0.0
|
||
delete_content: 1.0
|
||
access_network: 1.0
|
||
modify_config: 0.0
|
||
approve_plan: 1.0
|
||
|
||
Execution Controls (thresholds)
|
||
install_dependency: 0.0
|
||
require_sandbox: true
|
||
require_checkpoints: true
|
||
allow_unsafe_tools: false
|
||
|
||
[OK] Profile loaded
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "automation-profile show",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"name": "trusted",
|
||
"source": "built-in",
|
||
"description": "Auto-exec, manual apply. Day-to-day development",
|
||
"phase_transitions": {
|
||
"decompose_task": 0.0,
|
||
"create_tool": 0.0,
|
||
"select_tool": 1.0
|
||
},
|
||
"decision_automation": {
|
||
"edit_code": 0.0,
|
||
"execute_command": 0.0
|
||
},
|
||
"self_repair": {
|
||
"create_file": 0.0,
|
||
"delete_content": 1.0,
|
||
"access_network": 1.0,
|
||
"modify_config": 0.0,
|
||
"approve_plan": 1.0
|
||
},
|
||
"execution_controls": {
|
||
"install_dependency": 0.0,
|
||
"require_sandbox": true,
|
||
"require_checkpoints": true,
|
||
"allow_unsafe_tools": false
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T14:31:00Z", "duration_ms": 55 },
|
||
"messages": ["Profile loaded"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: automation-profile show
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
name: trusted
|
||
source: built-in
|
||
description: "Auto-exec, manual apply. Day-to-day development"
|
||
phase_transitions:
|
||
decompose_task: 0.0
|
||
create_tool: 0.0
|
||
select_tool: 1.0
|
||
decision_automation:
|
||
edit_code: 0.0
|
||
execute_command: 0.0
|
||
self_repair:
|
||
create_file: 0.0
|
||
delete_content: 1.0
|
||
access_network: 1.0
|
||
modify_config: 0.0
|
||
approve_plan: 1.0
|
||
execution_controls:
|
||
install_dependency: 0.0
|
||
require_sandbox: true
|
||
require_checkpoints: true
|
||
allow_unsafe_tools: false
|
||
timing:
|
||
started: "2026-02-08T14:31:00Z"
|
||
duration_ms: 55
|
||
messages:
|
||
- "Profile loaded"
|
||
```
|
||
|
||
#### agents config
|
||
|
||
!!! info "Purpose"
|
||
Manage ==global configuration values== that control system-wide defaults. Configuration keys use hierarchical dot-path notation (e.g., `core.automation-profile`, `core.log.level`).
|
||
|
||
??? tip "Key Configuration Categories"
|
||
| Category | Example Keys | Description |
|
||
| :------- | :----------- | :---------- |
|
||
| **Core** | `core.automation-profile`, `core.format`, `core.log.level` | System-wide defaults |
|
||
| **Actor** | `actor.default.invariant` | Default actor assignments |
|
||
| **Output** | `core.format` | Default rendering format (`rich`, `json`, `yaml`, etc.) |
|
||
|
||
##### agents config set
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> config set <span style="color: #66cc66;"><key></span> <span style="color: #66cc66;"><value></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Set a configuration key.
|
||
|
||
**Arguments**
|
||
|
||
- `<key>`: Hierarchical dot-path key name (e.g., `core.automation-profile`, `core.log.level`, `actor.default.invariant`, `core.format`). See **Global Configuration Keys** for the complete reference.
|
||
- `<value>`: Value to set.
|
||
|
||
The `actor.default.invariant` key sets the default Invariant Reconciliation Actor used globally. This actor is used to reconcile invariant conflicts when neither the plan nor the project specifies one.
|
||
|
||
The `core.format` key sets the default output rendering format used by all commands. Accepted values are `rich`, `color`, `table`, `plain`, `json`, `yaml`. When set, this value is used unless overridden by the `--format` CLI flag. See **Output Rendering Framework** for details.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set core.automation-profile trusted
|
||
|
||
╭─ Config Updated ──────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.automation-profile │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Value:</span> trusted │
|
||
│ <span style="color: yellow; font-weight: 600;">Previous:</span> manual │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> config │
|
||
│ <span style="color: yellow; font-weight: 600;">Scope:</span> global │
|
||
╰───────────────────────────────────────╯
|
||
|
||
╭─ Effective ────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Sessions:</span> new sessions │
|
||
│ <span style="color: yellow; font-weight: 600;">Plans:</span> future plans (unless set) │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Existing:</span> unchanged │
|
||
╰────────────────────────────────────╯
|
||
|
||
╭─ Saved To ──────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">File:</span> ~/.cleveragents/config.toml │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Line:</span> 8 │
|
||
╰─────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Config updated
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents config set core.automation-profile trusted
|
||
|
||
Config Updated
|
||
Key: core.automation-profile
|
||
Value: trusted
|
||
Previous: manual
|
||
Source: config
|
||
Scope: global
|
||
|
||
Effective
|
||
Sessions: new sessions
|
||
Plans: future plans (unless set)
|
||
Existing: unchanged
|
||
|
||
Saved To
|
||
File: ~/.cleveragents/config.toml
|
||
Line: 8
|
||
|
||
[OK] Config updated
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "config set",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"key": "core.automation-profile",
|
||
"value": "trusted",
|
||
"previous": "manual",
|
||
"source": "config",
|
||
"scope": "global",
|
||
"effective": {
|
||
"sessions": "new sessions",
|
||
"plans": "future plans (unless set)",
|
||
"existing": "unchanged"
|
||
},
|
||
"saved_to": { "file": "~/.cleveragents/config.toml", "line": 8 }
|
||
},
|
||
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 30 },
|
||
"messages": ["Config updated"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: config set
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
key: core.automation-profile
|
||
value: trusted
|
||
previous: manual
|
||
source: config
|
||
scope: global
|
||
effective:
|
||
sessions: new sessions
|
||
plans: "future plans (unless set)"
|
||
existing: unchanged
|
||
saved_to:
|
||
file: "~/.cleveragents/config.toml"
|
||
line: 8
|
||
timing:
|
||
started: "2026-02-08T14:32:00Z"
|
||
duration_ms: 30
|
||
messages:
|
||
- "Config updated"
|
||
```
|
||
|
||
Setting the default output format:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set core.format table
|
||
|
||
╭─ Config Updated ─────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.format │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Previous:</span> rich │
|
||
│ <span style="color: #66cc66; font-weight: 600;">New Value:</span> table │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> user (~/.cleveragents) │
|
||
╰──────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Set core.format = table
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents config set core.format table
|
||
|
||
Config Updated
|
||
Key: core.format
|
||
Previous: rich
|
||
New Value: table
|
||
Scope: user (~/.cleveragents)
|
||
|
||
[OK] Set core.format = table
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "config set",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"key": "core.format",
|
||
"previous": "rich",
|
||
"value": "table",
|
||
"scope": "user (~/.cleveragents)"
|
||
},
|
||
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 25 },
|
||
"messages": ["Set core.format = table"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: config set
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
key: core.format
|
||
previous: rich
|
||
value: table
|
||
scope: "user (~/.cleveragents)"
|
||
timing:
|
||
started: "2026-02-08T14:32:00Z"
|
||
duration_ms: 25
|
||
messages:
|
||
- "Set core.format = table"
|
||
```
|
||
|
||
Setting a global invariant actor:
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config set actor.default.invariant local/invariant-resolver
|
||
|
||
╭─ Config Updated ──────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Key:</span> actor.default.invariant │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Previous:</span> (not set) │
|
||
│ <span style="color: #66cc66; font-weight: 600;">New Value:</span> local/invariant-resolver │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> user (~/.cleveragents) │
|
||
╰───────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Set actor.default.invariant = local/invariant-resolver
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents config set actor.default.invariant local/invariant-resolver
|
||
|
||
Config Updated
|
||
Key: actor.default.invariant
|
||
Previous: (not set)
|
||
New Value: local/invariant-resolver
|
||
Scope: user (~/.cleveragents)
|
||
|
||
[OK] Set actor.default.invariant = local/invariant-resolver
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "config set",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"key": "actor.default.invariant",
|
||
"previous": null,
|
||
"value": "local/invariant-resolver",
|
||
"scope": "user (~/.cleveragents)"
|
||
},
|
||
"timing": { "started": "2026-02-08T14:32:00Z", "duration_ms": 28 },
|
||
"messages": ["Set actor.default.invariant = local/invariant-resolver"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: config set
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
key: actor.default.invariant
|
||
previous: null
|
||
value: local/invariant-resolver
|
||
scope: "user (~/.cleveragents)"
|
||
timing:
|
||
started: "2026-02-08T14:32:00Z"
|
||
duration_ms: 28
|
||
messages:
|
||
- "Set actor.default.invariant = local/invariant-resolver"
|
||
```
|
||
|
||
##### agents config get
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> config get <span style="color: #66cc66;"><key></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Get a configuration value.
|
||
|
||
**Arguments**
|
||
|
||
- `<key>`: Key to read.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config get core.automation-profile
|
||
|
||
╭─ Config ──────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Key:</span> core.automation-profile │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Value:</span> trusted │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Source:</span> config │
|
||
│ <span style="color: yellow; font-weight: 600;">Overridden:</span> no │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Type:</span> string │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Origin ──────────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">File:</span> ~/.cleveragents/config.toml │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Line:</span> 8 │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Default:</span> supervised │
|
||
╰───────────────────────────────────╯
|
||
|
||
╭─ Resolution Chain ──────────────╮
|
||
│ 1. CLI flag: (not set) │
|
||
│ 2. Env var: (not set) │
|
||
│ 3. Config file: trusted │
|
||
│ 4. Default: supervised │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Winner:</span> config file (level 3) │
|
||
╰─────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Config read
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents config get core.automation-profile
|
||
|
||
Config
|
||
Key: core.automation-profile
|
||
Value: trusted
|
||
Source: config
|
||
Overridden: no
|
||
Type: string
|
||
|
||
Origin
|
||
File: ~/.cleveragents/config.toml
|
||
Line: 8
|
||
Default: supervised
|
||
|
||
Resolution Chain
|
||
1. CLI flag: (not set)
|
||
2. Env var: (not set)
|
||
3. Config file: trusted
|
||
4. Default: supervised
|
||
Winner: config file (level 3)
|
||
|
||
[OK] Config read
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "config get",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"key": "core.automation-profile",
|
||
"value": "trusted",
|
||
"source": "config",
|
||
"overridden": false,
|
||
"type": "string",
|
||
"origin": {
|
||
"file": "~/.cleveragents/config.toml",
|
||
"line": 8,
|
||
"default": "supervised"
|
||
},
|
||
"resolution_chain": [
|
||
{ "level": 1, "source": "CLI flag", "value": null },
|
||
{ "level": 2, "source": "Env var", "value": null },
|
||
{ "level": 3, "source": "Config file", "value": "trusted" },
|
||
{ "level": 4, "source": "Default", "value": "supervised" }
|
||
],
|
||
"winner": { "source": "config file", "level": 3 }
|
||
},
|
||
"timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 20 },
|
||
"messages": ["Config read"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: config get
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
key: core.automation-profile
|
||
value: trusted
|
||
source: config
|
||
overridden: false
|
||
type: string
|
||
origin:
|
||
file: "~/.cleveragents/config.toml"
|
||
line: 8
|
||
default: supervised
|
||
resolution_chain:
|
||
- level: 1
|
||
source: "CLI flag"
|
||
value: null
|
||
- level: 2
|
||
source: "Env var"
|
||
value: null
|
||
- level: 3
|
||
source: "Config file"
|
||
value: trusted
|
||
- level: 4
|
||
source: Default
|
||
value: supervised
|
||
winner:
|
||
source: "config file"
|
||
level: 3
|
||
timing:
|
||
started: "2026-02-08T14:33:00Z"
|
||
duration_ms: 20
|
||
messages:
|
||
- "Config read"
|
||
```
|
||
|
||
##### agents config list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> config list [<span style="color: cyan;">--filter-values</span> <span style="color: #66cc66;"><REGEX></span>] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List all configuration values.
|
||
|
||
**Arguments**
|
||
|
||
None.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> config list
|
||
|
||
╭─ Config ───────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Key</span> <span style="color: cyan; font-weight: 600;">Value</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Modified</span> │
|
||
│ <span style="opacity: 0.7;">──────────────── ────────────────── ─────── ────────</span> │
|
||
│ core.automation-profile trusted config yes │
|
||
│ actor.default.invariant local/reconciler config yes │
|
||
│ core.log.level FATAL default no │
|
||
╰────────────────────────────────────────────────────────────╯
|
||
|
||
╭─ Overrides ─────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Env:</span> none │
|
||
│ <span style="color: #5599ff; font-weight: 600;">CLI Flags:</span> none │
|
||
╰─────────────────╯
|
||
|
||
╭─ Config File ───────────────────────╮
|
||
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> ~/.cleveragents/config.toml │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Size:</span> 284 bytes │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Valid:</span> yes │
|
||
╰─────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 6 settings listed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents config list
|
||
|
||
Config
|
||
Key Value Source Modified
|
||
----------------------- ------------------ ------- --------
|
||
core.automation-profile trusted config yes
|
||
actor.default.invariant local/reconciler config yes
|
||
core.log.level FATAL default no
|
||
|
||
Overrides
|
||
Env: none
|
||
CLI Flags: none
|
||
|
||
Config File
|
||
Path: ~/.cleveragents/config.toml
|
||
Size: 284 bytes
|
||
Valid: yes
|
||
|
||
[OK] 6 settings listed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "config list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"settings": [
|
||
{ "key": "core.automation-profile", "value": "trusted", "source": "config", "modified": true },
|
||
{ "key": "actor.default.invariant", "value": "local/reconciler", "source": "config", "modified": true },
|
||
{ "key": "core.log.level", "value": "FATAL", "source": "default", "modified": false }
|
||
],
|
||
"overrides": { "env": null, "cli_flags": null },
|
||
"config_file": {
|
||
"path": "~/.cleveragents/config.toml",
|
||
"size_bytes": 284,
|
||
"valid": true
|
||
}
|
||
},
|
||
"timing": { "started": "2026-02-08T14:33:00Z", "duration_ms": 25 },
|
||
"messages": ["6 settings listed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: config list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
settings:
|
||
- key: core.automation-profile
|
||
value: trusted
|
||
source: config
|
||
modified: true
|
||
- key: actor.default.invariant
|
||
value: local/reconciler
|
||
source: config
|
||
modified: true
|
||
- key: core.log.level
|
||
value: FATAL
|
||
source: default
|
||
modified: false
|
||
overrides:
|
||
env: null
|
||
cli_flags: null
|
||
config_file:
|
||
path: "~/.cleveragents/config.toml"
|
||
size_bytes: 284
|
||
valid: true
|
||
timing:
|
||
started: "2026-02-08T14:33:00Z"
|
||
duration_ms: 25
|
||
messages:
|
||
- "6 settings listed"
|
||
```
|
||
|
||
#### agents invariant
|
||
|
||
!!! info "Purpose"
|
||
Manage ==invariants== — named constraints that guide and constrain plan execution. Invariants can be attached to any scope: global (all plans), project (all plans targeting that project), plan (a specific plan and its child plans), or action (carried forward when the action is used).
|
||
|
||
!!! warning "Scope Requirements"
|
||
Exactly ==one scope flag== is required for `add` and `list`. The available scopes are:
|
||
|
||
| Scope | Flag | Applies To |
|
||
| :---- | :--- | :--------- |
|
||
| **Global** | `--global` | All plans across all projects |
|
||
| **Project** | `--project <NAME>` | All plans targeting that project |
|
||
| **Plan** | `--plan <ID>` | A specific plan and its child plans |
|
||
| **Action** | `--action <NAME>` | Carried forward when the action is used |
|
||
|
||
When multiple scopes apply to a plan, the ==union== of all applicable invariants is enforced.
|
||
|
||
##### agents invariant add
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> invariant add [<span style="color: cyan;">--global</span>] [(<span style="color: cyan;">--project</span>|<span style="color: yellow;">-p</span>) PROJECT] [<span style="color: cyan;">--plan</span> PLAN_ID]...
|
||
[<span style="color: cyan;">--action</span> ACTION]... <span style="color: #66cc66;"><INVARIANT_TEXT></span></code></pre></div>
|
||
|
||
**Purpose**
|
||
Add an invariant at the specified scope.
|
||
|
||
**Arguments**
|
||
|
||
- `<INVARIANT_TEXT>`: The invariant text (positional argument at end of command).
|
||
- `--global`: Attach as a global invariant (applies to all plans).
|
||
- `--project/-p PROJECT`: Attach to a project (applies to all plans targeting this project).
|
||
- `--plan PLAN_ID`: Attach to a plan (plan-level invariant). Repeatable.
|
||
- `--action ACTION`: Attach to an action (action-level invariant). Repeatable.
|
||
|
||
At least one scope flag (`--global`, `--project`, `--plan`, or `--action`) must be provided. `--plan` and `--action` can be repeated to attach the same invariant to multiple plans or actions.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--global</span> <span style="color: #66cc66;">"All public APIs must maintain backward compatibility"</span>
|
||
|
||
╭─ Invariant Added ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All public APIs must maintain backward compatibility │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> global │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A1B │
|
||
╰────────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--project</span> local/api-service <span style="color: #66cc66;">"All endpoints must validate auth tokens"</span>
|
||
|
||
╭─ Invariant Added ──────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Project:</span> local/api-service │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All endpoints must validate auth tokens │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> project │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A2C │
|
||
╰────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--plan</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: #66cc66;">"All database queries must use parameterized statements"</span>
|
||
|
||
╭─ Invariant Added ─────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Plan:</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> All database queries must use parameterized statements │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> plan │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9G3A │
|
||
╰───────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant add <span style="color: cyan;">--action</span> local/code-coverage <span style="color: #66cc66;">"Test files must not import production secrets"</span>
|
||
|
||
╭─ Invariant Added ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">Action:</span> local/code-coverage │
|
||
│ <span style="color: #66cc66; font-weight: 600;">Invariant:</span> Test files must not import production secrets │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> action │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9H4B │
|
||
╰────────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant added
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents invariant add --global "All public APIs must maintain backward compatibility"
|
||
|
||
Invariant Added
|
||
Invariant: All public APIs must maintain backward compatibility
|
||
Scope: global
|
||
ID: inv_01HXM9A1B
|
||
|
||
[OK] Invariant added
|
||
|
||
$ agents invariant add --project local/api-service "All endpoints must validate auth tokens"
|
||
|
||
Invariant Added
|
||
Project: local/api-service
|
||
Invariant: All endpoints must validate auth tokens
|
||
Scope: project
|
||
ID: inv_01HXM9A2C
|
||
|
||
[OK] Invariant added
|
||
|
||
$ agents invariant add --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J "All database queries must use parameterized statements"
|
||
|
||
Invariant Added
|
||
Plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
Invariant: All database queries must use parameterized statements
|
||
Scope: plan
|
||
ID: inv_01HXM9G3A
|
||
|
||
[OK] Invariant added
|
||
|
||
$ agents invariant add --action local/code-coverage "Test files must not import production secrets"
|
||
|
||
Invariant Added
|
||
Action: local/code-coverage
|
||
Invariant: Test files must not import production secrets
|
||
Scope: action
|
||
ID: inv_01HXM9H4B
|
||
|
||
[OK] Invariant added
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "invariant add",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": [
|
||
{
|
||
"invariant": "All public APIs must maintain backward compatibility",
|
||
"scope": "global",
|
||
"id": "inv_01HXM9A1B"
|
||
},
|
||
{
|
||
"project": "local/api-service",
|
||
"invariant": "All endpoints must validate auth tokens",
|
||
"scope": "project",
|
||
"id": "inv_01HXM9A2C"
|
||
},
|
||
{
|
||
"plan": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"invariant": "All database queries must use parameterized statements",
|
||
"scope": "plan",
|
||
"id": "inv_01HXM9G3A"
|
||
},
|
||
{
|
||
"action": "local/code-coverage",
|
||
"invariant": "Test files must not import production secrets",
|
||
"scope": "action",
|
||
"id": "inv_01HXM9H4B"
|
||
}
|
||
],
|
||
"timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 45 },
|
||
"messages": ["Invariant added"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: invariant add
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
- invariant: "All public APIs must maintain backward compatibility"
|
||
scope: global
|
||
id: inv_01HXM9A1B
|
||
- project: local/api-service
|
||
invariant: "All endpoints must validate auth tokens"
|
||
scope: project
|
||
id: inv_01HXM9A2C
|
||
- plan: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
invariant: "All database queries must use parameterized statements"
|
||
scope: plan
|
||
id: inv_01HXM9G3A
|
||
- action: local/code-coverage
|
||
invariant: "Test files must not import production secrets"
|
||
scope: action
|
||
id: inv_01HXM9H4B
|
||
timing:
|
||
started: "2026-02-08T14:35:00Z"
|
||
duration_ms: 45
|
||
messages:
|
||
- "Invariant added"
|
||
```
|
||
|
||
##### agents invariant list
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> invariant list [<span style="color: cyan;">--global</span>] [(<span style="color: cyan;">--project</span>|<span style="color: yellow;">-p</span>) PROJECT] [<span style="color: cyan;">--plan</span> PLAN_ID] [<span style="color: cyan;">--action</span> ACTION]
|
||
[<span style="color: cyan;">--effective</span>] [<span style="color: #66cc66;"><REGEX></span>]</code></pre></div>
|
||
|
||
**Purpose**
|
||
List invariants at a given scope. Use `--effective` with `--plan` to show the final reconciled view of invariants (after precedence resolution) rather than just the invariants directly attached at that scope.
|
||
|
||
**Arguments**
|
||
|
||
- `--global`: List global invariants.
|
||
- `--project/-p PROJECT`: List invariants attached to a project.
|
||
- `--plan PLAN_ID`: List invariants attached to a plan.
|
||
- `--action ACTION`: List invariants attached to an action.
|
||
- `--effective`: (Only with `--plan`) Show the reconciled invariant view after precedence resolution across all scopes.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant list <span style="color: cyan;">--global</span>
|
||
|
||
╭─ Global Invariants ──────────────────────────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Text</span> │
|
||
│ <span style="opacity: 0.7;">────────────── ────────────────────────────────────────────────────</span> │
|
||
│ inv_01HXM9A1B All public APIs must maintain backward compatibility │
|
||
│ inv_01HXM9A1C Payment processing must be idempotent │
|
||
╰──────────────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 2 invariants
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant list <span style="color: cyan;">--plan</span> 01HXM8C2ZK4Q7C2B3F2R4VYV6J <span style="color: cyan;">--effective</span>
|
||
|
||
╭─ Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J) ──────────────────────────────────╮
|
||
│ <span style="color: cyan; font-weight: 600;">ID</span> <span style="color: cyan; font-weight: 600;">Source</span> <span style="color: cyan; font-weight: 600;">Text</span> │
|
||
│ <span style="opacity: 0.7;">────────────── ─────── ──────────────────────────────────────────────────────</span> │
|
||
│ inv_01HXM9A1B global All public APIs must maintain backward compatibility │
|
||
│ inv_01HXM9A2C project All endpoints must validate auth tokens │
|
||
│ inv_01HXM9G3A plan All database queries must use parameterized statements │
|
||
╰───────────────────────────────────────────────────────────────────────────────────────────╯
|
||
|
||
│ <span style="color: yellow; font-weight: 600;">Conflicts Resolved:</span> 1 │
|
||
│ <span style="opacity: 0.7;"> Global <span style="color: #66cc66;">"Use shared DB pool"</span> overridden by plan "All database queries must use │
|
||
│ parameterized statements"</span> │
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents invariant list --global
|
||
|
||
Global Invariants
|
||
ID Text
|
||
-------------- --------------------------------------------------------
|
||
inv_01HXM9A1B All public APIs must maintain backward compatibility
|
||
inv_01HXM9A1C Payment processing must be idempotent
|
||
|
||
[OK] 2 invariants
|
||
|
||
$ agents invariant list --plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J --effective
|
||
|
||
Effective Invariants (Plan 01HXM8C2ZK4Q7C2B3F2R4VYV6J)
|
||
ID Source Text
|
||
-------------- ------- --------------------------------------------------
|
||
inv_01HXM9A1B global All public APIs must maintain backward compatibility
|
||
inv_01HXM9A2C project All endpoints must validate auth tokens
|
||
inv_01HXM9G3A plan All database queries must use parameterized statements
|
||
|
||
Conflicts Resolved: 1
|
||
Global "Use shared DB pool" overridden by plan "All database queries must use
|
||
parameterized statements"
|
||
|
||
[OK] 3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "invariant list",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"scope": "plan",
|
||
"plan_id": "01HXM8C2ZK4Q7C2B3F2R4VYV6J",
|
||
"effective": true,
|
||
"invariants": [
|
||
{ "id": "inv_01HXM9A1B", "source": "global", "text": "All public APIs must maintain backward compatibility" },
|
||
{ "id": "inv_01HXM9A2C", "source": "project", "text": "All endpoints must validate auth tokens" },
|
||
{ "id": "inv_01HXM9G3A", "source": "plan", "text": "All database queries must use parameterized statements" }
|
||
],
|
||
"conflicts_resolved": [
|
||
{
|
||
"overridden": { "source": "global", "text": "Use shared DB pool" },
|
||
"by": { "source": "plan", "text": "All database queries must use parameterized statements" }
|
||
}
|
||
]
|
||
},
|
||
"timing": { "started": "2026-02-08T14:35:00Z", "duration_ms": 35 },
|
||
"messages": ["3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: invariant list
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
scope: plan
|
||
plan_id: 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||
effective: true
|
||
invariants:
|
||
- id: inv_01HXM9A1B
|
||
source: global
|
||
text: "All public APIs must maintain backward compatibility"
|
||
- id: inv_01HXM9A2C
|
||
source: project
|
||
text: "All endpoints must validate auth tokens"
|
||
- id: inv_01HXM9G3A
|
||
source: plan
|
||
text: "All database queries must use parameterized statements"
|
||
conflicts_resolved:
|
||
- overridden:
|
||
source: global
|
||
text: "Use shared DB pool"
|
||
by:
|
||
source: plan
|
||
text: "All database queries must use parameterized statements"
|
||
timing:
|
||
started: "2026-02-08T14:35:00Z"
|
||
duration_ms: 35
|
||
messages:
|
||
- "3 effective invariants (1 global, 1 project, 1 plan; 1 conflict resolved)"
|
||
```
|
||
|
||
##### agents invariant remove
|
||
|
||
<div class="highlight"><pre><code><span style="color: cyan; font-weight: 600;">agents</span> invariant remove [<span style="color: cyan;">--yes</span>|<span style="color: yellow;">-y</span>] <span style="color: #66cc66;"><INVARIANT_ID></span></code></pre></div>
|
||
|
||
!!! warning "Constraint Removal"
|
||
Remove an invariant by ID. The invariant is removed from whichever scope it was originally attached to. ==Active plans== that have already incorporated this invariant into their decision trees are not retroactively affected, but future plans will no longer enforce this constraint.
|
||
|
||
**Arguments**
|
||
|
||
- `<INVARIANT_ID>`: Invariant ID to remove.
|
||
- `--yes`: Skip confirmation.
|
||
|
||
**Examples**
|
||
|
||
=== "Rich"
|
||
|
||
<div class="highlight"><pre><code>
|
||
<span style="color: #66cc66; font-weight: 600;">$</span> <span style="color: cyan; font-weight: 600;">agents</span> invariant remove inv_01HXM9A1C
|
||
|
||
Remove invariant inv_01HXM9A1C (<span style="color: #66cc66;">"Payment processing must be idempotent"</span>, scope: global)? [y/N]: y
|
||
|
||
╭─ Invariant Removed ──────────────────────────────────────────────╮
|
||
│ <span style="color: yellow; font-weight: 600;">Removed:</span> Payment processing must be idempotent │
|
||
│ <span style="color: #5599ff; font-weight: 600;">Scope:</span> global │
|
||
│ <span style="color: #5599ff; font-weight: 600;">ID:</span> inv_01HXM9A1C │
|
||
╰──────────────────────────────────────────────────────────────────╯
|
||
|
||
<span style="color: #66cc66; font-weight: 600;">✓ OK</span> Invariant removed
|
||
</code></pre></div>
|
||
|
||
=== "Plain"
|
||
|
||
```
|
||
$ agents invariant remove inv_01HXM9A1C
|
||
|
||
Remove invariant inv_01HXM9A1C ("Payment processing must be idempotent", scope: global)? [y/N]: y
|
||
|
||
Invariant Removed
|
||
Removed: Payment processing must be idempotent
|
||
Scope: global
|
||
ID: inv_01HXM9A1C
|
||
|
||
[OK] Invariant removed
|
||
```
|
||
|
||
=== "JSON"
|
||
|
||
```json
|
||
{
|
||
"command": "invariant remove",
|
||
"status": "ok",
|
||
"exit_code": 0,
|
||
"data": {
|
||
"removed": "Payment processing must be idempotent",
|
||
"scope": "global",
|
||
"id": "inv_01HXM9A1C"
|
||
},
|
||
"timing": { "started": "2026-02-08T14:36:00Z", "duration_ms": 30 },
|
||
"messages": ["Invariant removed"]
|
||
}
|
||
```
|
||
|
||
=== "YAML"
|
||
|
||
```yaml
|
||
command: invariant remove
|
||
status: ok
|
||
exit_code: 0
|
||
data:
|
||
removed: "Payment processing must be idempotent"
|
||
scope: global
|
||
id: inv_01HXM9A1C
|
||
timing:
|
||
started: "2026-02-08T14:36:00Z"
|
||
duration_ms: 30
|
||
messages:
|
||
- "Invariant removed"
|
||
```
|