cleveragents-core/docs/milestones/v3.0.0/cli-reference.md

v3.0.0 — Action, Resource, Project & Plan CLI Reference

Complete command documentation for all CleverAgents v3.0.0 CLI commands.

---

Action Management (agents action)

Actions are reusable plan templates defined in YAML. They specify which actors handle each phase of the plan lifecycle and what arguments the plan accepts.

agents action create

agents action create --config ./my-action.yaml

Minimal action YAML:

name: local/code-coverage
description: Increase code coverage to the target percentage
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: |
  Line coverage reaches the target percentage for all modules under src/.
arguments:
  - name: target_coverage
    type: integer
    required: true

Full action YAML:

name: local/refactor
description: Refactor a module to follow SOLID principles
strategy_actor: openai/gpt-4
execution_actor: anthropic/claude-3
estimation_actor: openai/gpt-4
invariant_actor: anthropic/claude-3
automation_profile: trusted
definition_of_done: |
  All classes follow Single Responsibility Principle.
  No method exceeds 20 lines.
invariants:
  - "No reduction in test coverage"
  - "All public APIs remain backward compatible"
arguments:
  - name: module_path
    type: string
    required: true

agents action list / show / archive

agents action list                              # all actions
agents action list --namespace local            # filter by namespace
agents action list --state available            # filter by state
agents action show local/code-coverage          # show action details
agents action archive local/old-action          # soft-delete action

---

Resource Management (agents resource)

Resources are external entities (git repos, directories, mounts) that plans can read or modify.

agents resource add

agents resource add git-checkout local/my-repo --path /home/user/projects/my-repo
agents resource add fs-directory local/data  --path /data --read-only

Built-in resource types (v3.0.0): git-checkout, fs-directory, fs-mount

agents resource list / show / remove

agents resource list                            # all resources
agents resource show local/my-repo              # resource details
agents resource remove --yes local/my-repo      # remove resource

---

Project Management (agents project)

Projects group resources together for plan execution context.

agents project create / link-resource / list / show

agents project create local/my-project   --description "My application"
agents project link-resource local/my-project local/my-repo
agents project list
agents project show local/my-project

---

Plan Lifecycle (agents plan)

Plans are the central execution unit. Lifecycle: Strategize -> Execute -> Apply.

agents plan use — Create a plan

agents plan use local/code-coverage my-project --arg target_coverage=80
agents plan use local/lint proj-1 proj-2                        # multiple projects
agents plan use local/refactor my-project \                     # with automation profile & invariants
  --automation-profile trusted   --invariant "No new warnings"
agents plan use local/code-coverage my-project \                # with actor overrides
  --strategy-actor openai/gpt-4   --execution-actor anthropic/claude-3

agents plan execute / diff / apply — Run and merge changes

agents plan execute                       # Strategize -> Execute phases
agents plan diff 01HXYZ...                # preview proposed changes
agents plan apply --yes                   # merge changes (skip confirmation)

agents plan list / status / cancel — Manage plans

agents plan list --state complete         # filter plans
agents plan status 01HXYZ...              # plan details
agents plan cancel 01HXYZ... --reason "Requirements changed"

---

See Also

• CLI overview (v3.0.0) — Goals, architecture notes, feature table
• Deep Dive — Sandbox, persistence, domain model internals