> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# archal scenario

> List local and hosted Archal scenarios from the CLI. Filter by clone or tag to find scored agent tests ready to run with archal run.

## Usage

```bash theme={null}
archal scenario <subcommand> [options]
```

## Subcommands

### `scenario list`

List local scenarios and hosted catalog scenarios.

```bash theme={null}
archal scenario list
archal scenario list --clone github
archal scenario list --tag financial-controls
archal scenario list --page 2 --limit 10
archal scenario list --json
```

| Flag              | Description                                                       | Default |
| ----------------- | ----------------------------------------------------------------- | ------- |
| `--clone <name>`  | Filter scenarios by required clone                                | all     |
| `--tag <tag>`     | Filter scenarios by catalog tag                                   | all     |
| `--source <kind>` | Filter by source: `local`, `workspace`, `sample`, `hosted`, `all` | `all`   |
| `--page <n>`      | Page number for text output                                       | `1`     |
| `--limit <n>`     | Scenarios per page for text output                                | `20`    |
| `--json`          | Output all matching rows as JSON                                  | `false` |

Shows each scenario's title, slug, description, source (local file, workspace,
sample, or hosted catalog), and required clones.

### `scenario push`

Save a local scenario to the active workspace so other projects in the same
workspace can reuse it. **Scenarios are not auto-saved on `archal run`** -
this command is the canonical way to share a scenario across projects.

```bash theme={null}
archal scenario push ./scenarios/close-stale-issues.md
archal scenario push ./scenarios/close-stale-issues.md --set-default
```

| Flag                     | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `--workspace <id>`       | Workspace id (defaults to the active workspace)               |
| `--title <title>`        | Override the scenario title stored in the workspace           |
| `--harness <path>`       | Default harness path to store with this scenario              |
| `--replace <id-or-slug>` | Update an existing workspace scenario instead of creating one |
| `--set-default`          | Make the pushed scenario the workspace default                |
| `--json`                 | Output the saved scenario as JSON                             |