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:

```bash
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:

```yaml
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

```bash
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

```bash
# 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

```bash
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

```bash
# 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

```bash
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`