cleveragents-core/docs/reference/action_cli.md

Action CLI Reference

The agents action command group manages actions (reusable plan templates) in the CleverAgents v3 plan lifecycle.

Config-Only Create

Actions are created exclusively via a YAML configuration file:

agents action create --config ./actions/code-coverage.yaml

Legacy inline flags (--name, --strategy-actor, --execution-actor, --definition-of-done, --arg) are not supported and will be rejected with an error.

YAML Configuration File

The configuration file is validated against ActionConfigSchema and must include the following required fields:

name: local/code-coverage
description: Increase code coverage
strategy_actor: openai/gpt-4
execution_actor: openai/gpt-4
definition_of_done: |
  Line coverage reaches the target percentage
  for all modules under src/.

Optional fields include: long_description, reusable, read_only, arguments, invariants, automation_profile, state, tags, estimation_actor, review_actor, apply_actor, invariant_actor.

See docs/reference/action_model.md for the full schema reference.

Error Handling

Error	Cause
Config file error	File not found or not readable
Schema validation error	YAML does not match ActionConfigSchema
Config validation error	YAML parses but has invalid content
Validation Error	Business rule violation from lifecycle service
Error	General service or infrastructure error

List Actions

agents action list [OPTIONS] [REGEX]

Options

Flag	Short	Description
--namespace	-n	Filter by namespace
--state	-s	Filter by state (available, archived)
--format	-f	Output format: json, yaml, plain, table, rich (default: rich)

Positional Arguments

Argument	Description
REGEX	Optional regex pattern to filter action names

Examples

# List all actions
agents action list

# Filter by namespace
agents action list --namespace local

# Filter by state
agents action list --state available

# Filter by name pattern
agents action list "code-.*"

# Combine filters
agents action list --namespace local --state available "lint"

# Output as JSON
agents action list --format json

# Output as YAML
agents action list --format yaml

# Output as plain text
agents action list --format plain

# Output as ASCII table
agents action list --format table

Output Columns (rich / table)

Column	Description
Namespaced Name	Full namespace/name identifier
Short Name	Just the name portion
State	available or archived
Strategy Actor	Actor for the Strategize phase
Execution Actor	Actor for the Execute phase
Definition of Done	Truncated summary (first 40 chars)
Reusable	check if the action persists after use
Created	Creation timestamp

JSON/YAML Output Keys

Key	Description
namespaced_name	Full namespaced identifier
short_name	Name portion only
state	Current state value
description	Short description
definition_of_done	Completion criteria
strategy_actor	Strategize phase actor
execution_actor	Execute phase actor
automation_profile	Default profile (or null)
arguments	List of argument definitions
invariants	List of invariant constraint strings

Show Action

agents action show <NAME> [OPTIONS]

Options

Flag	Short	Description
--format	-f	Output format (default: rich)

Displays full details for a single action identified by its namespaced name (e.g., local/code-coverage).

Examples

# Rich panel (default)
agents action show local/code-coverage

# JSON output
agents action show local/code-coverage --format json

# YAML output
agents action show local/code-coverage --format yaml

Archive Action

agents action archive <NAME> [OPTIONS]

Options

Flag	Short	Description
--format	-f	Output format (default: rich)

Soft-deletes an action by transitioning it to archived state. Archived actions cannot be used for new plans but are preserved for history.

Removed Commands

action available

The available subcommand has been removed. Actions are created directly in available state (there is no draft state). To restore an archived action, recreate it from a YAML config file.

Source Location

• CLI commands: src/cleveragents/cli/commands/action.py
• Config schema: src/cleveragents/action/schema.py
• Domain model: src/cleveragents/domain/models/core/action.py
• Formatting helpers: src/cleveragents/cli/formatting.py