# 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) |

### 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 Columns

| 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         | ✓ if the action persists after use   |
| Created          | Creation timestamp                   |

## Show Action

```bash
agents action show <NAME>
```

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

### Output Fields

- **Namespaced Name**: Full identifier
- **Short Name**: Name portion only
- **Description**: Short description
- **State**: Current state
- **Strategy Actor**: Strategize phase actor
- **Execution Actor**: Execute phase actor
- **Reusable / Read Only**: Behavior flags
- **Definition of Done**: Full completion criteria (truncated at 120 chars in panel)
- **Arguments**: Typed argument definitions
- **Created**: Timestamp

## Archive Action

```bash
agents action archive <NAME>
```

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`