# CleverAgents CLI Reference

The `agents` CLI provides commands for managing actions, resources, projects, plans,
actors, skills, invariants, context, sessions, and more.

## Commands

### Action Commands

- `agents action create --config <yaml>` — Create an action from a YAML configuration
  file and persist it to SQLite. Defined in `cleveragents.cli.action.create_action`.

### Resource Commands

- `agents resource add git-checkout` — Register a git-checkout resource linking a
  local repository path to a project. Defined in `cleveragents.cli.resource.add_resource`.
- `agents resource add container-instance [--container-id <id>]` — Register a
  container-instance resource.
- `agents resource list` — List all registered resources.
- `agents resource stop` — Stop a running resource (supports `container-instance` and
  `devcontainer-instance` types).

### Project Commands

- `agents project create` — Create a new project record with namespace/name identity.
  Defined in `cleveragents.cli.project.create_project`.
- `agents project link-resource` — Link a registered resource to a project. Defined in
  `cleveragents.cli.project.link_resource`.

### Plan Commands

- `agents plan use` — Create a new plan record with state machine transitions and
  associate it with an action. Defined in `cleveragents.cli.plan.use_plan`.
- `agents plan execute <plan_id>` — Execute a plan via the actor-based LLM path,
  producing a ChangeSet from tool invocations. Defined in
  `cleveragents.cli.plan.execute_plan`.
- `agents plan diff <plan_id>` — Show pending changes in the git worktree sandbox
  before applying. Defined in `cleveragents.cli.plan.diff_plan`.
- `agents plan apply <plan_id>` — Apply sandbox changes to the target repository with
  a git commit. Defined in `cleveragents.cli.plan.apply_plan`.
- `agents plan list` — List all plans with status and timestamps.
- `agents plan tree <plan_id>` — Display the decision tree for a plan (full 26-char
  ULIDs for correction workflows).
- `agents plan correct <plan_id>` — Correct a decision in the plan decision tree.
- `agents plan rollback <plan_id>` — Roll back a plan to a previous checkpoint.
- `agents plan errors <plan_id>` — Show error details for a failed plan.

### Actor Commands

- `agents actor add --config <yaml>` — Load and register an actor from a YAML
  configuration file. Defined in `cleveragents.cli.actor.add_actor`.
- `agents actor list` — List all registered actors.
- `agents actor remove <name>` — Remove an actor from the registry.
- `agents actor set-default <name>` — Set the default actor for CLI commands.
- `agents actor run <name>` — Run an actor directly with a prompt.

### Skill Commands

- `agents skill list` — List all registered skills.
- `agents skill refresh` — Refresh skill tool bindings from MCP servers.

### Invariant Commands

- `agents invariant add` — Add an invariant to a project or plan.
- `agents invariant list` — List all invariants.

### Context Commands

- `agents context list` — List context fragments in the active tier service.
- `agents context add` — Add a context fragment.
- `agents context show` — Show details of a context fragment.
- `agents context clear` — Clear all context fragments.

### Session Commands

- `agents session create --actor <name>` — Create a new conversation session.
- `agents session list` — List all sessions.
- `agents session show --session-id <id>` — Show session details.
- `agents session export --session-id <id> --output <file>` — Export a session to JSON.
- `agents session import --input <file>` — Import a session from JSON.
- `agents session delete --session-id <id>` — Delete a session.

### Validation Commands

- `agents validation add` — Attach a validation to an action.
- `agents validation list` — List validations for an action.

### Tool Commands

- `agents tool add --config <yaml>` — Register a tool from YAML configuration.
- `agents tool list` — List all registered tools.

### Config Commands

- `agents config get <key>` — Get a configuration value.
- `agents config set <key> <value>` — Set a configuration value.

### Diagnostics Commands

- `agents diagnostics` — Check provider credentials and actor/provider selection.

### TUI Command

- `agents tui` — Launch the interactive Textual terminal UI.

### Server Commands

- `agents server connect --url <url> --token <token>` — Connect to a remote
  CleverAgents server.
- `agents server status` — Check server connection status.

## Global Options

- `--format <plain|json|yaml|rich|color>` — Output format (default: `rich`).
- `--version` — Show version and git commit.
- `--help` — Show help for any command.

## See Also

- Detailed CLI references: `docs/reference/action_cli.md`, `docs/reference/actor_cli.md`,
  `docs/reference/plan_cli.md`, `docs/reference/resource_cli.md`,
  `docs/reference/session_cli.md`, `docs/reference/skill_cli.md`
- Showcase examples: `docs/showcase/cli-tools/`