---
title: Flows and Runs
description: Create flows from templates, execute them, inspect results, model what-if changes, and manage human-in-the-loop approvals.
---

Flows are the unit of work in AKOS: a directed graph of agent and tool nodes that executes a multi-step process. The CLI lets you scaffold flows from built-in templates, run them in several modes, inspect their output, and project the impact of model or configuration changes.

## Creating a flow

### Browse templates

```bash
akos flow new --list
```

Filter templates by persona:

```bash
akos flow new --list --persona developer
```

### Scaffold a flow into your workspace config

```bash
akos flow new <template-id>
```

For example:

```bash
akos flow new summarize-slack-dms
```

This merges the template's flow (and any required agents) into your `akos.config.yaml`. If a flow with the same ID already exists, the command exits with an error unless you pass `--replace`.

### flow new options

| Flag | Description |
|---|---|
| `--list` | List available templates and exit |
| `--persona <p>` | With `--list`, filter/order templates for a persona |
| `--target <path>` | Config file to merge into (default: `akos.config.yaml`) |
| `--flow-id <slug>` | Override the scaffolded flow ID |
| `--replace` | Replace an existing flow with the same ID |
| `--estimate` | Print a hint to run a cost estimate after scaffolding |
| `--visual` | Also write a visual layout document under `.agentskitos/flows/` |
| `--visual-out <path>` | Write the visual layout document to a custom path |

## Running a flow

```bash
akos run akos.config.yaml
```

By default, flows run in `dry_run` mode — the flow graph is traversed and logged but no LLM calls or external side effects are made. This is safe for testing your configuration.

### Run modes

| Mode | Description |
|---|---|
| `dry_run` | Traverse the flow without LLM calls or side effects (default) |
| `real` | Execute fully with live LLM calls and tool actions |
| `durable` | Like `real`, but checkpointed so interrupted runs can be resumed |

```bash
# Dry run (default)
akos run akos.config.yaml

# Live run
akos run akos.config.yaml --mode real

# Durable run (checkpointed)
akos run akos.config.yaml --mode durable --store ./run-checkpoints
```

### Selecting a specific flow

When your config has multiple flows, specify which one to run:

```bash
akos run akos.config.yaml --flow summarize-slack-dms
```

### Resuming an interrupted run

```bash
akos run akos.config.yaml \
  --mode durable \
  --store ./run-checkpoints \
  --resume <run-id>
```

`--resume` requires `--store`.

### Cost estimate

Print an estimated cost and exit without executing the flow:

```bash
akos run akos.config.yaml --estimate
```

### run options

| Flag | Description |
|---|---|
| `--flow <id>` | Flow ID to execute (required when config has multiple flows) |
| `--mode <mode>` | Run mode: `dry_run`, `real`, `durable` (default: `dry_run`) |
| `--workspace <id>` | Override workspace ID |
| `--store <dir>` | Checkpoint directory for durable mode |
| `--resume <runId>` | Resume an existing run (requires `--store`) |
| `--estimate` | Print cost estimate and exit |
| `--force` | Skip budget limit check |
| `--strict` | In `real` mode, error when LLM credentials are missing instead of falling back |
| `--quiet` | Suppress per-node event output |

## Listing past runs

```bash
akos runs list
```

Shows recent runs with their flow ID, status, cost, and token counts.

Add `--json` for structured output. Use `--limit <n>` to control how many results are returned.

## Fetching a single run

To fetch one run row by id via the sidecar:

```bash
akos runs get <run-id>
```

Add `--json` for the raw run row. The command returns `null` when no run matches the id.

## Explaining a run

After a coding agent run that captured artifact bundles, use `explain` to get a plain-English step-by-step walkthrough:

```bash
akos explain --artifact-dir ./run-artifacts
```

Filter to a specific run ID:

```bash
akos explain --artifact-dir ./run-artifacts --run-id <run-id>
```

Output as structured JSON:

```bash
akos explain --artifact-dir ./run-artifacts --json
```

The `--artifact-dir` should point to the directory passed to `--capture-run-artifacts` when the run was started.

## What-if analysis

Project how a change to token budget, latency, cost, or pass rate would affect your historical runs without re-running them.

Prepare a JSON file of past run snapshots:

```json
[
  { "id": "run-1", "costUsd": 0.005, "latencyMs": 900, "passed": true },
  { "id": "run-2", "costUsd": 0.007, "latencyMs": 1200, "passed": false }
]
```

Then project the impact:

```bash
# What if we switched to a model that costs 30% less?
akos whatif runs.json --cost 0.7

# What if tokens were reduced by 20% and latency improved by 10%?
akos whatif runs.json --tokens 0.8 --latency 0.9

# What if pass rate dropped by 5 percentage points?
akos whatif runs.json --pass -0.05
```

Options:

| Flag | Description |
|---|---|
| `--tokens <m>` | Token count multiplier (e.g. `0.7` = 30% fewer tokens) |
| `--latency <m>` | Latency multiplier |
| `--cost <m>` | Cost multiplier |
| `--pass <d>` | Pass-rate delta in the range `[-1, 1]` |
| `--json` | Emit JSON instead of the summary table |

## Human-in-the-loop (HITL) approvals

When a flow escalates a decision to a human reviewer, use `hitl` to list and act on pending escalations via the running workspace sidecar.

### List escalations

```bash
# All escalations
akos hitl list

# Filter by status
akos hitl list --status open
akos hitl list --status approved
akos hitl list --status rejected
```

### Approve an escalation

```bash
akos hitl approve <escalation-id>

# With a note and signer
akos hitl approve <escalation-id> \
  --note "Reviewed and looks correct" \
  --signer alice@example.com
```

### Reject an escalation

```bash
akos hitl reject <escalation-id> --note "Data quality issue — re-run after fix"
```

`--note` is required when rejecting.

### Reassign an escalation

```bash
akos hitl reassign <escalation-id> bob@example.com
```

### Submit a counter-proposal

```bash
akos hitl modify <escalation-id> "Use the revised budget figure of 42000"
```

All HITL commands require the workspace sidecar to be running (`akos serve`).

## Runs retention

To prune old run records:

```bash
akos runs retention prune
```

This command removes run records beyond the configured retention policy. Use `--dry-run` to preview what would be deleted.

## Related topics

- **[Workflows in the app](/docs/using-the-app/flows)** — visual editor, snapshots, import wizard.
- **[Activity](/docs/using-the-app/runs-and-observability)** — live run monitor and trace drill-down.
- **[Inbox](/docs/using-the-app/inbox)** — approve or reject paused human-gate steps.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — governed path from trigger to audit ledger.
- **[Triggers](/docs/cli/triggers)** — cron, webhook, and file-watch automation.