cleveragents-core/docs/cli/README.md

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/