# Action CLI Reference

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

## Commands

| Command                  | Description                              |
|--------------------------|------------------------------------------|
| `agents action create`   | Create action from YAML config file      |
| `agents action list`     | List actions with optional filters       |
| `agents action show`     | Show full action details                 |
| `agents action archive`  | Soft-delete (transition to `archived`)   |

## `agents action create`

Create a new action from a YAML configuration file.

### Synopsis

```bash
agents action create --config <FILE>
```

Actions are created **exclusively** via YAML configuration files. Legacy
inline flags (`--name`, `--strategy-actor`, etc.) are not supported.

### YAML Configuration File

```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/.
estimation_actor: openai/gpt-4        # optional
invariant_actor: anthropic/claude-3    # optional
automation_profile: trusted            # optional
invariants:                            # optional
  - "No reduction in existing coverage"
  - "All new code must have tests"
inputs_schema:                         # optional JSON Schema
  type: object
  properties:
    target_coverage:
      type: integer
      minimum: 0
      maximum: 100
arguments:                             # optional
  - name: target_coverage
    type: integer
    required: true
    description: Target coverage percentage
```

## `agents action list`

List all actions with optional filtering.

### Synopsis

```bash
agents action list [REGEX] [OPTIONS]
```

### Options

| Flag                | Description                              |
|---------------------|------------------------------------------|
| `--namespace`, `-n` | Filter by namespace                      |
| `--state`, `-s`     | Filter by state (`available`, `archived`)|
| `--format`, `-f`    | Output format                            |

### Examples

```bash
agents action list
agents action list --namespace local
agents action list --state available
agents action list "code-.*"
agents action list --format json
```

## `agents action show`

Show details for an action including all extended fields.

### Synopsis

```bash
agents action show <NAMESPACED_NAME> [--format FORMAT]
```

### Output Fields

The show command displays all action fields:

- **Namespaced Name**: Full `namespace/name` identifier
- **Short Name**: Name portion only
- **Description**: Action description
- **State**: `available` or `archived`
- **Strategy Actor**: Actor for Strategize phase
- **Execution Actor**: Actor for Execute phase
- **Estimation Actor**: Optional estimation actor (shown when set)
- **Invariant Actor**: Optional invariant reconciliation actor (shown when set)
- **Reusable**: Whether action stays available after use
- **Read Only**: Whether action only reads
- **Definition of Done**: Completion criteria
- **Arguments**: Typed argument definitions
- **Invariants**: Constraint list (shown when present)
- **Inputs Schema**: JSON Schema dict (shown when present)
- **Automation Profile**: Default profile name (shown when set)
- **Created**: Creation timestamp

### Examples

```bash
agents action show local/code-coverage
agents action show local/code-coverage --format json
agents action show local/code-coverage --format yaml
```

## `agents action archive`

Archive an action (soft delete). Archived actions cannot be used but are
preserved for history.

### Synopsis

```bash
agents action archive <NAMESPACED_NAME> [--format FORMAT]
```

### Examples

```bash
agents action archive local/old-action
agents action archive local/old-action --format json
```