cleveragents-core/docs/cli.md

CLI Reference

This page documents all agents CLI commands introduced in the v3.0.0 (Minimal Local Source-Code Workflow) and v3.1.0 (Actor Compiler + Full LLM Integration) milestones.

For the full command tree run agents --help or agents <command> --help.

---

Workflow Overview

The typical end-to-end workflow introduced in v3.0.0 and extended in v3.1.0:

# 1. Register an actor (v3.1.0)
agents actor add --config actor.yaml

# 2. Register a resource (v3.0.0)
agents resource add git-checkout --name local/my-repo --path /path/to/repo

# 3. Create a project and link the resource (v3.0.0)
agents project create --name local/my-project
agents project link-resource --project local/my-project --resource local/my-repo

# 4. Create an action (v3.0.0)
agents action create --config action.yaml

# 5. Create a plan from the action (v3.0.0)
agents plan use --action local/my-action --project local/my-project

# 6. Execute the plan (v3.0.0)
agents plan execute <plan_id>

# 7. Review the diff (v3.0.0)
agents plan diff <plan_id>

# 8. Apply the changes (v3.0.0)
agents plan apply <plan_id>

---

v3.0.0 Commands

agents action create

Creates and persists an action record to SQLite from a YAML configuration file. Actions define the goal, definition of done, invariants, and argument schema for a family of plans.

agents action create --config <path> [options]

Options:

Flag	Description
--config <path>	Path to the action YAML file (required)
--name <name>	Override the action name from the YAML
--force	Overwrite an existing action with the same name

Example action.yaml:

name: local/add-feature
description: "Add a new feature to the project"
definition_of_done:
  - "Feature is implemented and tested"
  - "All existing tests pass"
invariants:
  - "Do not modify files outside src/"
arguments:
  feature_name:
    type: string
    description: "Name of the feature to add"
    required: true

Example:

agents action create --config action.yaml
# Action 'local/add-feature' created (ID: 01HZ...)

---

agents resource add

Registers a resource in the resource registry. Resources are the target repositories or directories that plans read from and write to.

agents resource add <resource-type> [options]

Supported resource types (v3.0.0):

Type	Description
git-checkout	A local git repository
fs-directory	A plain filesystem directory

Options for git-checkout:

Flag	Description
--name <name>	Resource name (namespaced, e.g. local/my-repo) (required)
--path <path>	Absolute path to the git repository root (required)
--branch <branch>	Branch to check out (default: current HEAD)

Example:

agents resource add git-checkout \
  --name local/my-repo \
  --path /home/user/projects/my-repo
# Resource 'local/my-repo' registered (ID: 01HZ...)

---

agents project create

Creates a named project record. Projects group resources together and provide the context for plan execution.

agents project create --name <name> [options]

Options:

Flag	Description
--name <name>	Project name (namespaced, e.g. local/my-project) (required)
--description <text>	Human-readable description

Example:

agents project create --name local/my-project
# Project 'local/my-project' created (ID: 01HZ...)

---

agents project link-resource

Associates a registered resource with a project. Plans executed against the project will have access to all linked resources.

agents project link-resource --project <name> --resource <name> [options]

Options:

Flag	Description
--project <name>	Project name or ID (required)
--resource <name>	Resource name or ID (required)
--role <role>	Resource role within the project (e.g. primary, reference)

Example:

agents project link-resource \
  --project local/my-project \
  --resource local/my-repo
# Resource 'local/my-repo' linked to project 'local/my-project'

---

agents plan use

Creates a plan record from an action and transitions it through the initial state machine states (CREATED to READY). The plan is persisted to SQLite and assigned a ULID.

agents plan use --action <name> --project <name> [options]

Options:

Flag	Description
--action <name>	Action name or ID (required)
--project <name>	Project name or ID (required)
--automation-profile <profile>	Automation profile (default: manual). Built-in: manual, review, supervised, cautious, trusted, autonomous, ci, full-auto
--arg <key>=<value>	Action argument value (repeatable)

Example:

agents plan use \
  --action local/add-feature \
  --project local/my-project \
  --automation-profile trusted \
  --arg feature_name=dark-mode
# Plan created: 01HZABC123DEF456GHI789JKL0
# State: READY

---

agents plan execute

Invokes the actor-based LLM execution path for a plan. The strategy actor runs the Strategize phase (producing a decision tree), then the execute actor runs the Execute phase (producing a ChangeSet of file modifications written to the git worktree sandbox).

agents plan execute <plan_id> [options]

Arguments:

Argument	Description
<plan_id>	ULID of the plan to execute (required)

Options:

Flag	Description
--actor <name>	Override the default strategy/execute actor
--dry-run	Run the Strategize phase only; do not write files

Example:

agents plan execute 01HZABC123DEF456GHI789JKL0
# Strategize: 3 decisions recorded
# Execute: ChangeSet produced — 4 files modified
# State: EXECUTED

---

agents plan diff

Displays the pending changes stored in the sandbox for a plan. Shows a unified diff of all files in the ChangeSet against the current HEAD of the target repository.

agents plan diff <plan_id> [options]

Arguments:

Argument	Description
<plan_id>	ULID of the plan (required)

Options:

Flag	Description
--file <path>	Show diff for a single file only
--stat	Show diffstat summary instead of full diff

Example:

agents plan diff 01HZABC123DEF456GHI789JKL0
# diff --git a/src/feature.py b/src/feature.py
# --- a/src/feature.py
# +++ b/src/feature.py
# @@ -0,0 +1,42 @@
# +class DarkModeFeature:
# +    ...

---

agents plan apply

Merges sandbox changes into the target repository via git merge from the isolated worktree branch, then commits the result. Displays a spec-aligned Apply Summary and Sandbox Cleanup panel.

agents plan apply <plan_id> [options]

Arguments:

Argument	Description
<plan_id>	ULID of the plan (required)

Options:

Flag	Description
--message <msg>	Override the git commit message
--no-cleanup	Keep the sandbox worktree after apply (for debugging)

Example:

agents plan apply 01HZABC123DEF456GHI789JKL0
# Apply Summary
#   Plan ID:    01HZABC123DEF456GHI789JKL0
#   Artifacts:  4 files changed
#   Insertions: +142
#   Deletions:  -3
#   Project:    local/my-project
#   Timestamp:  2026-02-15 10:30:00
# Sandbox Cleanup
#   Worktree removed
#   Branch deleted
# OK  Changes applied

---

v3.1.0 Commands

agents actor add

Loads an actor YAML file, validates it, compiles it (for graph-type actors, builds the LangGraph StateGraph), and registers it in the actor registry (persisted to SQLite).

agents actor add --config <path> [options]

Options:

Flag	Description
--config <path>	Path to the actor YAML file (required)
--force	Overwrite an existing actor registration with the same name

Actor YAML structure (version 3):

version: "3"
name: local/my-actor
type: graph          # llm | tool | graph

entry_node: strategize
nodes:
  - name: strategize
    type: llm
    provider: openai
    model: gpt-4o
    skills:
      - local/file-ops
  - name: validate
    type: tool
    tool: local/validate-api-compat
edges:
  - from: strategize
    to: validate
  - from: validate
    to: END

Example:

agents actor add --config actor.yaml
# Actor 'local/my-actor' registered (type: graph, nodes: 2)

---

agents skill add

Registers a skill in the skill registry. Skills are collections of tools that actors can use during plan execution. Skills can be defined locally or sourced from an MCP server.

agents skill add [--config <path>] [--mcp <url>] [options]

Options:

Flag	Description
--config <path>	Path to a skill YAML file
--mcp <url>	Register an MCP server as a skill source
--name <name>	Skill name (required when using --mcp)
--force	Overwrite an existing skill registration

Example (local skill):

agents skill add --config skills/file-ops.yaml
# Skill 'local/file-ops' registered (4 tools)

Example (MCP server):

agents skill add --mcp http://localhost:3000 --name local/my-mcp-tools
# MCP skill 'local/my-mcp-tools' registered (12 tools discovered)

---

agents skill list

Lists all registered skills with their tool counts and sources.

agents skill list [options]

Options:

Flag	Description
--format <fmt>	Output format: table (default), json, yaml

---

agents skill show

Shows detailed information about a registered skill, including all tools it provides.

agents skill show <name>

---

agents skill remove

Removes a skill from the registry.

agents skill remove <name>

---

agents skill refresh

Re-fetches the tool list from all registered MCP server skills. Use this after an MCP server has been updated to add or remove tools.

agents skill refresh [--name <skill-name>]

Options:

Flag	Description
--name <name>	Refresh a specific MCP skill only (default: refresh all MCP skills)

---

agents tool add

Registers an individual tool in the tool registry. Tools can be Python callables, shell commands, or MCP tool references.

agents tool add --config <path> [options]

Options:

Flag	Description
--config <path>	Path to a tool YAML file (required)
--force	Overwrite an existing tool registration
--unsafe	Allow registration of tools marked as unsafe

---

agents tool list

Lists all registered tools.

agents tool list [options]

Options:

Flag	Description
--skill <name>	Filter by skill
--format <fmt>	Output format: table (default), json, yaml

---

agents tool show

Shows detailed information about a registered tool.

agents tool show <name>

---

agents tool remove

Removes a tool from the registry.

agents tool remove <name>

---

agents validation attach

Attaches a validation rule to a resource. Validation rules are run before plan apply to gate the merge. Rules are classified as required (blocking) or informational (non-blocking).

agents validation attach --resource <name> --validation <name> [options]

Options:

Flag	Description
--resource <name>	Resource name or ID (required)
--validation <name>	Validation rule name or ID (required)
--tier <tier>	required (default) or informational

Example:

agents validation attach \
  --resource local/my-repo \
  --validation local/run-tests \
  --tier required
# Validation 'local/run-tests' attached to 'local/my-repo' (tier: required)

---

agents validation detach

Removes a validation rule attachment from a resource.

agents validation detach --resource <name> --validation <name>

---

Related Documentation

• Git Worktree Sandbox — how the sandbox isolates plan changes and merges them on apply
• Actor System API — ActorLoader, ActorRegistry, compile_actor, and CompiledActor
• Skills API — skill schema, protocol, registry, and MCP adapter
• Tool API — tool runtime, lifecycle, and registry
• MCP Adapter API — Model Context Protocol adapter and client
• ADR-006 Plan Lifecycle
• ADR-010 Actor and Agent Architecture
• ADR-029 Model Context Protocol Adoption