# CLI Reference CleverAgents ships two equivalent entry points: **`agents`** and **`cleveragents`**. Both accept the same commands, flags, and arguments. See [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) for the design rationale behind the CLI structure and output rendering framework. --- ## Synopsis ``` agents|cleveragents [--data-dir ] [--config-path ] [--format rich|color|table|plain|json|yaml] [--help|-h] [--version] [--install-completion [SHELL]] [--show-completion [SHELL]] [-v...] [...] ``` --- ## 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. ```bash agents diagnostics ``` ### `agents tui` Launches the full-screen interactive terminal UI. Requires the `cleveragents[tui]` extra (`pip install "cleveragents[tui]"`). ```bash agents tui ``` --- ## Action Commands Actions are reusable YAML-defined plan templates. | Command | Description | |---------|-------------| | `agents action create --config\|-c ` | 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 ` | Show full details of an action | | `agents action archive ` | 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 ```bash # 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 [--update]` | Register or update an actor from a YAML config file | | `agents actor remove ` | Remove a custom actor | | `agents actor list` | List all registered actors | | `agents actor show ` | Show full details of an actor | | `agents actor run [flags] ` | Run an actor with a prompt | | `agents actor set-default ` | Set the default actor for CLI commands | | `agents actor context list [REGEX]` | List saved actor contexts | | `agents actor context show ` | Show a saved actor context | | `agents actor context export --output\|-o ` | Export a context to a file | | `agents actor context import [--update] --input\|-i [NAME]` | Import a context from a file | | `agents actor context remove [--yes\|-y] (--all\|-a\|)` | Remove one or all saved contexts | | `agents actor context clear [--yes\|-y] (--all\|-a\|)` | 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 ```bash # 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 (`/`) are immutable. > Custom actors must be named `local/`. > 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] ...` | Instantiate a plan from an action and bind it to one or more projects | | `agents plan execute ` | Advance a plan through the Strategize and Execute phases | | `agents plan apply [--yes\|-y] ` | Apply the sandbox changeset to real project resources | | `agents plan status ` | 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] ` | Display the decision tree for a plan | | `agents plan explain [--show-context] [--show-reasoning] ` | Explain a specific decision in a plan | | `agents plan correct [flags] ` | Correct a decision and recompute affected subtrees | | `agents plan diff (--correction \|)` | Show the diff for a plan or correction attempt | | `agents plan cancel [--reason\|-r REASON] ` | Cancel a running plan | | `agents plan rollback [--yes\|-y] ` | Roll back a plan to a checkpoint | | `agents plan artifacts ` | List artifacts produced by a plan | | `agents plan prompt ` | Send guidance to a running plan | | `agents plan errors ` | 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 ```bash # 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] ` | Create a new project | | `agents project list [--namespace\|-n NS] [REGEX]` | List projects | | `agents project show ` | Show project details | | `agents project delete [--force\|-f] [--yes\|-y] ` | Delete a project | | `agents project link-resource [--read-only] ` | Link a resource to a project | | `agents project unlink-resource [--yes\|-y] ` | Unlink a resource from a project | | `agents project context set [flags] ` | Configure the ACMS context policy for a project | | `agents project context show [--view VIEW] ` | Show the context policy for a project | | `agents project context inspect [flags] ` | Inspect the assembled context for a project | | `agents project context simulate [flags] ` | 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 ```bash # 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-specific-flags...]` | Register a new resource | | `agents resource remove [--yes\|-y] ` | Remove a resource | | `agents resource list [--all] [--type\|-t TYPE]` | List registered resources | | `agents resource show ` | Show resource details | | `agents resource inspect [--tree] [--file PATH] ` | Inspect resource contents | | `agents resource tree [--depth\|-d N] [--type\|-t TYPE] ` | Show the resource DAG subtree | | `agents resource link-child ` | Add a child link in the resource DAG | | `agents resource unlink-child [--yes\|-y] ` | Remove a child link | | `agents resource stop ` | Stop a running resource (e.g. a container) | | `agents resource rebuild ` | Rebuild a resource (e.g. rebuild a devcontainer) | | `agents resource type add --config\|-c [--update]` | Register a custom resource type | | `agents resource type remove [--yes\|-y] ` | Remove a custom resource type | | `agents resource type list [REGEX]` | List resource types | | `agents resource type show ` | Show resource type details | ### Example ```bash # 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 [--update]` | Register or update a skill from a YAML config file | | `agents skill remove [--yes\|-y] ` | Remove a skill | | `agents skill list [--namespace\|-n NS] [--source SOURCE]` | List registered skills | | `agents skill show ` | Show skill details | | `agents skill tools ` | List the tools exposed by a skill | ### Example ```bash # 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 [--update]` | Register or update a tool from a YAML config file | | `agents tool remove [--yes\|-y] ` | Remove a tool | | `agents tool list [--namespace\|-n NS] [--source SOURCE] [--type tool\|validation] [REGEX]` | List registered tools | | `agents tool show ` | Show tool details | ### Example ```bash # 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 ` | Show session details and message history | | `agents session delete [--yes\|-y] ` | Delete a session | | `agents session export [--output\|-o FILE] [--format json\|md] ` | Export a session to JSON or Markdown | | `agents session import --input\|-i ` | Import a session from a JSON file | | `agents session tell --session [--actor ACTOR] [--stream] ` | Send a message to a session | ### Example ```bash # 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] ` | Add an invariant | | `agents invariant list [flags] [REGEX]` | List invariants | | `agents invariant remove [--yes\|-y] ` | 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 ```bash # 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 ` | Show a saved actor context | | `agents actor context add` | Add context entries | | `agents actor context export --output\|-o ` | Export a context to a file | | `agents actor context import [--update] --input\|-i [NAME]` | Import a context from a file | | `agents actor context remove [--yes\|-y] (--all\|-a\|)` | Remove one or all saved contexts | | `agents actor context clear [--yes\|-y] (--all\|-a\|)` | Clear context history | --- ## Server Commands Server mode connects the CLI to a remote CleverAgents server. | Command | Description | |---------|-------------| | `agents server connect --url --token ` | Configure a remote CleverAgents server connection | | `agents server status` | Show the current server connection status | ### Example ```bash # Connect to a remote server agents server connect --url https://my-server.example.com --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 [--update]` | Register an LSP server | | `agents lsp remove [--yes\|-y] ` | Remove an LSP server | | `agents lsp list [--namespace\|-n NS] [--language LANG]` | List registered LSP servers | | `agents lsp show ` | 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 [--update]` | Register or update an automation profile | | `agents automation-profile remove [--yes\|-y] ` | Remove a custom automation profile | | `agents automation-profile list [REGEX]` | List automation profiles | | `agents automation-profile show ` | 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 [--update]` | Register a validation | | `agents validation attach [--project PROJECT\|--plan PLAN_ID] [ARGS...]` | Attach a validation to a resource | | `agents validation detach [--yes\|-y] ` | Detach a validation | --- ## Config Commands | Command | Description | |---------|-------------| | `agents config set ` | Set a configuration key | | `agents config get ` | Get a configuration key | | `agents config list [--filter-values REGEX] [REGEX]` | List configuration keys | ### Example ```bash # 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.