cleveragents-core/docs/api/cli-reference.md

CLI Reference

CleverAgents ships two equivalent entry points: agents and cleveragents. Both accept the same commands, flags, and arguments.

See ADR-021 for the design rationale behind the CLI structure and output rendering framework.

---

Synopsis

agents|cleveragents  [--data-dir <PATH>] [--config-path <PATH>]
                     [--format rich|color|table|plain|json|yaml]
                     [--help|-h] [--version]
                     [--install-completion [SHELL]] [--show-completion [SHELL]]
                     [-v...]
                     <COMMAND> [<ARGS>...]

---

Global Flags

These flags apply to every command and must appear before the subcommand name.

Flag	Short	Description
--data-dir PATH		Override the global data directory (database, caches, sessions, logs). Defaults to the platform data location.
--config-path PATH		Override the global configuration file path.
--format FORMAT		Output rendering format. One of rich (default), color, table, plain, json, yaml. Can also be set via core.format config key.
--help	-h	Print help for the current command and exit.
--version		Print the installed version and exit.
--install-completion [SHELL]		Install shell tab-completion for the given shell.
--show-completion [SHELL]		Print the completion script for the given shell.
-v		Increase log verbosity (repeatable). -v=ERROR, -vv=WARN, -vvv=INFO, -vvvv=DEBUG, -vvvvv=TRACE. Affects the current invocation only.

Output Formats

Format	Description	Best For
rich	Rich CLI elements with animated spinners, progress bars, and color	Interactive terminal use (default)
color	Plain scrolling text with ANSI color codes	Color-capable terminals
table	ASCII box-drawing tables and panels with color	Structured visual output
plain	Plain text, no color or non-ASCII characters	Piping, logs, non-terminal consumers
json	Structured JSON	Scripts, CI/CD pipelines
yaml	Structured YAML	Configuration, programmatic consumption

---

Environment Variables

Variable	Description
CLEVERAGENTS_DATA_DIR	Default data directory (overridden by --data-dir)
CLEVERAGENTS_CONFIG_PATH	Default config file path (overridden by --config-path)
CLEVERAGENTS_DEFAULT_PROVIDER	Pin the AI provider (openai, anthropic, google, …)
CLEVERAGENTS_DEFAULT_MODEL	Pin the model ID
OPENAI_API_KEY	OpenAI credentials
ANTHROPIC_API_KEY	Anthropic credentials
GOOGLE_API_KEY / GOOGLE_GENAI_API_KEY	Google credentials
AZURE_OPENAI_API_KEY	Azure OpenAI credentials
AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL
AZURE_OPENAI_DEPLOYMENT	Azure deployment name
OPENROUTER_API_KEY	OpenRouter credentials
GEMINI_API_KEY / GOOGLE_GEMINI_API_KEY	Gemini credentials
COHERE_API_KEY	Cohere credentials
GROQ_API_KEY	Groq credentials
TOGETHER_API_KEY	Together AI credentials
CLEVERAGENTS_TESTING_USE_MOCK_AI	Force mock provider in tests (true/false)
CLEVERAGENTS_LANGSMITH_ENABLED	Enable LangSmith tracing (true/false)
CLEVERAGENTS_LANGSMITH_PROJECT	LangSmith project name
CLEVERAGENTS_LANGSMITH_API_KEY	LangSmith API key
CLEVERAGENTS_LOG_LEVEL	Log level (DEBUG, INFO, WARN, ERROR)
CLEVERAGENTS_LOG_FORMAT	Log format (json, text)

---

Top-Level Commands

Command	Description
agents version	Print version and exit
agents info	Print system snapshot (mode, paths, runtime, projects)
agents diagnostics	Check credentials, provider selection, and actor configuration
agents init [--yes|-y]	Initialize a new CleverAgents workspace in the current directory
agents tui	Launch the interactive Textual TUI

agents diagnostics

Prints whether the provider registry can see your credentials, which actor/provider is selected, and any configuration warnings.

agents diagnostics

agents tui

Launches the full-screen interactive terminal UI. Requires the cleveragents[tui] extra (pip install "cleveragents[tui]").

agents tui

---

Action Commands

Actions are reusable YAML-defined plan templates.

Command	Description
agents action create --config|-c <FILE>	Register a new action from a YAML config file
agents action list [--namespace|-n NS] [--state|-s STATE] [REGEX]	List registered actions, optionally filtered
agents action show <ACTION_NAME>	Show full details of an action
agents action archive <ACTION_NAME>	Archive (soft-delete) an action

Flags

Flag	Short	Description
--config FILE	-c	Path to the action YAML configuration file
--namespace NS	-n	Filter by namespace
--state STATE	-s	Filter by state (active, archived)

Example

# Register an action from a YAML file
agents action create --config examples/actions/refactor.yaml

# List all active actions in the local namespace
agents action list --namespace local --state active

# Inspect a specific action
agents action show local/refactor

# Archive an action
agents action archive local/refactor

---

Actor Commands

Actors are YAML-configured execution units that encapsulate an LLM and a set of tools.

Command	Description
agents actor add --config|-c <FILE> [--update]	Register or update an actor from a YAML config file
agents actor remove <NAME>	Remove a custom actor
agents actor list	List all registered actors
agents actor show <NAME>	Show full details of an actor
agents actor run [flags] <NAME> <PROMPT>	Run an actor with a prompt
agents actor set-default <NAME>	Set the default actor for CLI commands
agents actor context list [REGEX]	List saved actor contexts
agents actor context show <NAME>	Show a saved actor context
agents actor context export --output|-o <FILE> <NAME>	Export a context to a file
agents actor context import [--update] --input|-i <FILE> [NAME]	Import a context from a file
agents actor context remove [--yes|-y] (--all|-a|<NAME>)	Remove one or all saved contexts
agents actor context clear [--yes|-y] (--all|-a|<NAME>)	Clear context history

agents actor run Flags

Flag	Short	Description
--output FILE	-o	Write output to a file
--unsafe	-u	Allow unsafe actor configurations
--context NAME		Load a named context
--context-dir PATH		Load context from a directory
--load-context NAME		Load a previously saved context
--temperature TEMP	-t	Override the LLM temperature
--skill SKILL		Attach a skill (repeatable)

Example

# Add a custom actor
agents actor add --config examples/actors/my-actor.yaml

# List all actors (built-in and custom)
agents actor list

# Show actor details
agents actor show openai/gpt-4o

# Run an actor with a prompt
agents actor run openai/gpt-4o "Summarize the current project status"

# Set a default actor so --actor is not required
agents actor set-default openai/gpt-4o

Note: Built-in actors (<provider>/<model>) are immutable. Custom actors must be named local/<id>. Use --unsafe when adding/updating configurations marked unsafe.

---

Plan Commands

Plans are instantiated from Actions and progress through four phases: Action → Strategize → Execute → Apply.

Command	Description
agents plan use [flags] <ACTION> <PROJECT>...	Instantiate a plan from an action and bind it to one or more projects
agents plan execute <PLAN_ID>	Advance a plan through the Strategize and Execute phases
agents plan apply [--yes|-y] <PLAN_ID>	Apply the sandbox changeset to real project resources
agents plan status <PLAN_ID>	Show the current phase, state, and progress of a plan
agents plan list [flags] [REGEX]	List plans, optionally filtered by phase, state, project, or action
agents plan tree [--show-superseded] <PLAN_ID>	Display the decision tree for a plan
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>	Explain a specific decision in a plan
agents plan correct [flags] <DECISION_ID>	Correct a decision and recompute affected subtrees
agents plan diff (--correction <ID>|<PLAN_ID>)	Show the diff for a plan or correction attempt
agents plan cancel [--reason|-r REASON] <PLAN_ID>	Cancel a running plan
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>	Roll back a plan to a checkpoint
agents plan artifacts <PLAN_ID>	List artifacts produced by a plan
agents plan prompt <PLAN_ID> <GUIDANCE>	Send guidance to a running plan
agents plan errors <PLAN_ID>	Show errors encountered during plan execution

agents plan use Flags

Flag	Short	Description
--automation-profile PROFILE		Automation profile to use (e.g. review, full-auto)
--invariant TEXT		Add a plan-scoped invariant (repeatable)
--strategy-actor ACTOR		Override the strategy actor
--execution-actor ACTOR		Override the execution actor
--estimation-actor ACTOR		Override the estimation actor
--invariant-actor ACTOR		Override the invariant reconciliation actor
--execution-environment RESOURCE		Specify the execution environment resource
--execution-env-priority PRIORITY		fallback or override
--arg name=value	-a	Pass a typed argument to the action (repeatable)

agents plan list Flags

Flag	Description
--phase PHASE	Filter by phase (action, strategize, execute, apply)
--state STATE	Filter by state (running, applied, errored, cancelled, …)
--project PROJECT	Filter by project name
--action ACTION	Filter by action name

agents plan correct Flags

Flag	Short	Description
--mode MODE		revert (undo the decision) or append (add guidance)
--guidance TEXT	-g	Natural-language correction guidance
--dry-run		Preview the correction without applying it
--yes	-y	Skip confirmation prompt

Example

# Instantiate a plan from the "refactor" action for the "my-project" project
agents plan use local/refactor my-project --arg target=src/

# Check plan status
agents plan status 01JXYZ...

# Execute the plan (Strategize + Execute phases)
agents plan execute 01JXYZ...

# Review the decision tree before applying
agents plan tree 01JXYZ...

# Apply the sandbox changes to real resources
agents plan apply 01JXYZ...

# Correct a specific decision
agents plan correct --mode revert --guidance "Use a different approach" 01JDEC...

# Show the diff for a plan
agents plan diff 01JXYZ...

---

Project Commands

Projects are named scopes linking resources, context policies, and invariants.

Command	Description
agents project create [flags] <NAME>	Create a new project
agents project list [--namespace|-n NS] [REGEX]	List projects
agents project show <PROJECT>	Show project details
agents project delete [--force|-f] [--yes|-y] <NAME>	Delete a project
agents project link-resource [--read-only] <PROJECT> <RESOURCE>	Link a resource to a project
agents project unlink-resource [--yes|-y] <PROJECT> <RESOURCE_NAME>	Unlink a resource from a project
agents project context set [flags] <PROJECT>	Configure the ACMS context policy for a project
agents project context show [--view VIEW] <PROJECT>	Show the context policy for a project
agents project context inspect [flags] <PROJECT>	Inspect the assembled context for a project
agents project context simulate [flags] <PROJECT>	Simulate context assembly for a project

agents project create Flags

Flag	Short	Description
--description DESC	-d	Human-readable project description
--resource RESOURCE		Link a resource at creation time (repeatable)
--invariant TEXT		Add a project-scoped invariant (repeatable)
--invariant-actor ACTOR		Override the invariant reconciliation actor

agents project context set Flags

Flag	Description
--view VIEW	Context view: strategize, execute, apply, default
--include-resource RESOURCE	Include a resource in context (repeatable)
--exclude-resource RESOURCE	Exclude a resource from context (repeatable)
--include-path GLOB	Include paths matching a glob (repeatable)
--exclude-path GLOB	Exclude paths matching a glob (repeatable)
--hot-max-tokens N	Maximum tokens in the hot context tier
--warm-max-decisions N	Maximum decisions in the warm tier
--cold-max-decisions N	Maximum decisions in the cold tier
--strategy STRATEGY	Context assembly strategy (repeatable)
--execution-environment RESOURCE	Preferred execution environment
--execution-env-priority PRIORITY	fallback or override
--clear	Reset the context policy to defaults

Example

# Create a project with a linked resource
agents project create my-project --description "Main application" \
  --resource local/my-repo

# Link an additional resource (read-only)
agents project link-resource my-project local/docs --read-only

# List all projects
agents project list

# Show project details
agents project show my-project

# Configure context policy for the strategize phase
agents project context set my-project --view strategize \
  --hot-max-tokens 8000 --strategy semantic

# Delete a project
agents project delete my-project --yes

---

Resource Commands

Resources are ULID-identified entities registered in the Resource Registry (git repos, filesystems, databases, containers, etc.).

Command	Description
agents resource add [flags] <TYPE> <NAME> [type-specific-flags...]	Register a new resource
agents resource remove [--yes|-y] <NAME>	Remove a resource
agents resource list [--all] [--type|-t TYPE]	List registered resources
agents resource show <RESOURCE>	Show resource details
agents resource inspect [--tree] [--file PATH] <RESOURCE>	Inspect resource contents
agents resource tree [--depth|-d N] [--type|-t TYPE] <RESOURCE>	Show the resource DAG subtree
agents resource link-child <PARENT> <CHILD>	Add a child link in the resource DAG
agents resource unlink-child [--yes|-y] <PARENT> <CHILD>	Remove a child link
agents resource stop <NAME>	Stop a running resource (e.g. a container)
agents resource rebuild <NAME>	Rebuild a resource (e.g. rebuild a devcontainer)
agents resource type add --config|-c <FILE> [--update]	Register a custom resource type
agents resource type remove [--yes|-y] <NAME>	Remove a custom resource type
agents resource type list [REGEX]	List resource types
agents resource type show <NAME>	Show resource type details

Example

# Register a git-checkout resource
agents resource add git-checkout local/my-repo --url https://github.com/org/repo.git

# List all resources
agents resource list

# Show resource details
agents resource show local/my-repo

# Inspect the resource tree
agents resource tree local/my-repo --depth 3

# Stop a running devcontainer
agents resource stop local/my-devcontainer

---

Skill Commands

Skills are composable, versioned capability bundles that expose tools to actors.

Command	Description
agents skill add --config|-c <FILE> [--update]	Register or update a skill from a YAML config file
agents skill remove [--yes|-y] <NAME>	Remove a skill
agents skill list [--namespace|-n NS] [--source SOURCE]	List registered skills
agents skill show <NAME>	Show skill details
agents skill tools <NAME>	List the tools exposed by a skill

Example

# Register a skill
agents skill add --config examples/skills/deploy.yaml

# List all skills
agents skill list

# Show skill details
agents skill show local/deploy-to-staging

# List tools in a skill
agents skill tools local/deploy-to-staging

---

Tool Commands

Tools are the atomic unit of execution — namespaced, independently registered callables.

Command	Description
agents tool add --config|-c <FILE> [--update]	Register or update a tool from a YAML config file
agents tool remove [--yes|-y] <NAME>	Remove a tool
agents tool list [--namespace|-n NS] [--source SOURCE] [--type tool|validation] [REGEX]	List registered tools
agents tool show <NAME>	Show tool details

Example

# Register a custom tool
agents tool add --config examples/tools/my-tool.yaml

# List all tools from MCP sources
agents tool list --source mcp

# List only validation tools
agents tool list --type validation

# Show tool details
agents tool show local/my-tool

---

Session Commands

Sessions are persistent conversation threads tied to an actor.

Command	Description
agents session create [--actor ACTOR]	Create a new conversation session
agents session list	List all sessions
agents session show <SESSION_ID>	Show session details and message history
agents session delete [--yes|-y] <SESSION_ID>	Delete a session
agents session export [--output|-o FILE] [--format json|md] <SESSION_ID>	Export a session to JSON or Markdown
agents session import --input|-i <FILE>	Import a session from a JSON file
agents session tell --session <SESSION_ID> [--actor ACTOR] [--stream] <PROMPT>	Send a message to a session

Example

# Create a session with a specific actor
agents session create --actor openai/gpt-4o

# List all sessions
agents session list

# Export as canonical JSON (importable)
agents session export --session-id abc123 --output session.json

# Export as Markdown transcript (human-readable, not importable)
agents session export --session-id abc123 --output session.md --format md

# Import a session
agents session import --input session.json

# Send a message to a session
agents session tell --session abc123 "What is the current plan status?"

---

Invariant Commands

Invariants are natural-language constraints on plan execution, scoped to global, project, action, or plan level.

Command	Description
agents invariant add [flags] <INVARIANT_TEXT>	Add an invariant
agents invariant list [flags] [REGEX]	List invariants
agents invariant remove [--yes|-y] <INVARIANT_ID>	Remove an invariant

agents invariant add Flags

Flag	Short	Description
--global		Add a global invariant
--project PROJECT	-p	Scope to a project
--plan PLAN_ID		Scope to a plan (repeatable)
--action ACTION		Scope to an action (repeatable)

agents invariant list Flags

Flag	Description
--global	Show global invariants
--project PROJECT	Filter by project
--plan PLAN_ID	Filter by plan
--action ACTION	Filter by action
--effective	Show the merged effective invariant set (plan > action > project > global)

Example

# Add a global invariant
agents invariant add --global "All output files must be UTF-8 encoded"

# Add a project-scoped invariant
agents invariant add --project my-project "Do not modify files in the vendor/ directory"

# List effective invariants for a plan
agents invariant list --plan 01JXYZ... --effective

# Remove an invariant
agents invariant remove 01JINV...

---

Context Commands

The agents context group manages actor-level context (distinct from project context policies managed under agents project context).

Command	Description
agents actor context list [REGEX]	List saved actor contexts
agents actor context show <NAME>	Show a saved actor context
agents actor context add	Add context entries
agents actor context export --output|-o <FILE> <NAME>	Export a context to a file
agents actor context import [--update] --input|-i <FILE> [NAME]	Import a context from a file
agents actor context remove [--yes|-y] (--all|-a|<NAME>)	Remove one or all saved contexts
agents actor context clear [--yes|-y] (--all|-a|<NAME>)	Clear context history

---

Server Commands

Server mode connects the CLI to a remote CleverAgents server.

Command	Description
agents server connect --url <URL> --token <TOKEN>	Configure a remote CleverAgents server connection
agents server status	Show the current server connection status

Example

# Connect to a remote server
agents server connect --url https://my-server.example.com --token <TOKEN>

# Check connection status
agents server status

---

LSP Commands

LSP servers provide language intelligence (diagnostics, completions, type info) to actors.

Command	Description
agents lsp add --config|-c <FILE> [--update]	Register an LSP server
agents lsp remove [--yes|-y] <NAME>	Remove an LSP server
agents lsp list [--namespace|-n NS] [--language LANG]	List registered LSP servers
agents lsp show <NAME>	Show LSP server details
agents lsp serve [--log-level LEVEL]	Start the CleverAgents LSP server (for IDE integration)

---

Automation Profile Commands

Automation profiles define confidence thresholds that gate which plan operations proceed automatically versus requiring human approval.

Command	Description
agents automation-profile add --config|-c <FILE> [--update]	Register or update an automation profile
agents automation-profile remove [--yes|-y] <NAME>	Remove a custom automation profile
agents automation-profile list [REGEX]	List automation profiles
agents automation-profile show <NAME>	Show automation profile details

Built-in profiles (immutable): manual, review, semi-auto, full-auto (and four intermediate levels).

---

Validation Commands

Validations are tool subtypes with pass/fail semantics, always attached to a resource.

Command	Description
agents validation add --config|-c <FILE> [--update]	Register a validation
agents validation attach [--project PROJECT|--plan PLAN_ID] <RESOURCE> <VALIDATION> [ARGS...]	Attach a validation to a resource
agents validation detach [--yes|-y] <ATTACHMENT_ID>	Detach a validation

---

Config Commands

Command	Description
agents config set <key> <value>	Set a configuration key
agents config get <key>	Get a configuration key
agents config list [--filter-values REGEX] [REGEX]	List configuration keys

Example

# Set the default output format
agents config set core.format json

# Pin the default provider
agents config set actor.default.provider openai

# List all config keys
agents config list

---

Naming Convention

All entities use the namespaced name format:

[[server:]namespace/]name

• Built-in actors use provider prefixes: openai/gpt-4o, anthropic/claude-4-sonnet
• Custom entities use local/ prefix: local/my-actor, local/my-skill
• Server-scoped entities: myserver:myns/my-entity
• Built-in resource types are unnamespaced: git-checkout, fs-mount

Plans and resources are identified by ULID (Universally Unique Lexicographically Sortable Identifier) when precision is needed, especially in hierarchies.