# Running Workflows This guide walks through operating a workflow run day to day: starting or continuing one, checking on it, resuming it after it blocks, and abandoning one you no longer want. It assumes you already know what a workflow is; see [Workflow Schema](../reference/workflow-schema.md) for the exact frontmatter and body syntax, and [Architecture: The Workflow Engine](../architecture/workflow-engine.md) for what happens under the hood (frozen plans, dispatch, resume-without-replay). For task/schedule-driven workflow runs — akm tasks and the OS scheduler — see [Scheduling](scheduling.md). ## Start or continue a run `akm workflow run ` starts or continues a persisted run and executes it until completion, failure, verification rejection, interruption, or an explicit invocation limit. Run state is scoped to the current project directory (nearest `.akm/config.json`, git root, bundle root, or current directory), so the same workflow can run independently in separate projects. Every new run/start compiles source IR v1 and freezes the durable plan v4 family's current executable format (`irVersion: 5`) before publishing the run. Markdown `.md` and GitHub-shaped `.yml` refs use the same freeze path. ```sh akm workflow run workflows/ship-release --version 1.2.3 akm workflow run workflows/review --changed_files a.ts --changed_files b.ts akm workflow run --max-retries 2 --timeout 10m ``` Parameter flags must come after the target and exactly match declared `params` keys. Values are coerced through each parameter's JSON Schema: repeat an array flag, pass an object or whole array as JSON, and use a bare boolean flag for `true`. There are no hyphen/underscore aliases. Parameters are accepted only while creating a new run — a later invocation against an active run rejects parameter flags. `--max-steps ` leaves a partial run active after at most `n` steps. `--max-retries ` retries a failed step on the same run up to `n` additional times (0 through 100). `--timeout ` bounds the whole invocation and accepts `N`, `Nms`, `Ns`, or `Nm`; bare `N` is milliseconds. A timeout or signal abort releases the run's lock without advancing the active step, so the run remains resumable. Failed, gate-rejected, timed-out, and interrupted runs exit nonzero. The run freezes its plan, exact models, execution limits, parameter snapshot, and verifier selection at creation — edits to source or config do not alter an in-flight run. See [Architecture: Frozen plans](../architecture/workflow-engine.md#frozen-plans) for why. ## Check status `akm workflow status` shows the full run state — all step statuses, notes, and evidence — for a given run ID or workflow ref. ```sh akm workflow status akm workflow status workflows/ship-release # When given a ref, resolves to the most-recently-updated run in the current scope ``` Use this to inspect where a run is after a context window break, or to verify all steps completed cleanly before closing a PR. **`--units` — per-unit diagnostics.** For an orchestrated run, add `--units` to also list the run's journaled unit rows — each unit's id, status, `failure_reason`, and any result/error diagnostic text the row carries: ```sh akm workflow status --units ``` This is a **diagnostic** surface, deliberately kept out of the deterministic artifact graph. A step's promoted artifact (what `steps.x.output` resolves to, and what a gate judges) keeps only a failed unit's structured `failure_reason` — never the raw error text — so step evidence stays reproducible across resumes. When you need the human-facing *why* behind a failure, `--units` reads the unit journal directly and shows it without ever feeding that text back into an artifact or input hash. ## Child runs A step that composes another workflow (see [Workflow Schema: Child workflows](../reference/workflow-schema.md#child-workflows)) drives that child inline when the composing step runs. `akm workflow status` on a run that composes children renders a `children:` tree after its `steps:` block: ```sh akm workflow status ``` ``` steps: - build [work] (completed) - dispatch [dispatch] (completed) children: - ✓ 4f2b1a9c workflows/leaf [completed] (step "dispatch") ``` Each row shows the child's run id, its workflow ref, its status, and which of the parent's steps spawned it; a blocked child also shows its resume command. Nesting reflects composition depth — a child that itself composes a grandchild shows its own indented `children:` rows. **Recovering a blocked child.** A blocked child blocks the composing step (and the parent run) too — `akm` will not resume a child for you. Resume the **child** first, then resume and re-run the **parent**; re-driving the parent is what advances it, because that re-enters the composing step and drives the now-resumed child: ```sh akm workflow resume akm workflow resume akm workflow run ``` **Nested blocks (composition depth 2+).** The three-command sequence above clears a block exactly one level deep. When a grandchild blocks — a root workflow composes a child, and that child composes the grandchild that actually blocks — re-driving the root does **not** cascade down into re-driving the still-blocked grandchild: a composing step never re-drives a child whose own status is already `blocked`, so re-running the root just re-observes the child's block and re-blocks the root the same way, without ever reaching the grandchild. Resume **every** blocked run in the chain, deepest first, then re-run only the root: ```sh akm workflow resume akm workflow resume akm workflow resume akm workflow run ``` The status tree prints `resume`/`then` commands on each blocked node, but those two commands alone only ever name that node and the root — they do not enumerate an intermediate chain. Read the tree top to bottom and resume every `blocked` row you see (deepest first) before re-running the root. **Child runs are hidden by default.** `akm workflow list` excludes child runs so the list stays a view of the runs you started; pass `--children` to include them: ```sh akm workflow list # child runs excluded akm workflow list --children # child runs included ``` A child run id always works directly, listed or not — `akm workflow status `, `resume`, `abandon`, and `run` all operate on it exactly like any other run. ## List runs in scope `akm workflow list` shows workflow runs in the current scope. ```sh akm workflow list # All runs in this scope (any status) akm workflow list --active # Only status=active (executable) runs akm workflow list --ref workflows/ship-release # Runs for a specific workflow ``` `--active` filters to runs whose status is exactly `active` — currently executable work. A `blocked` run (parked awaiting a human `akm workflow resume`) or a `failed`/`completed` run is **not** active and is excluded, so a script that treats `--active` output as runnable never picks one up. Blocked runs remain listed by the unfiltered `akm workflow list` with their `blocked` status. **Example: see what is in flight** ```sh akm workflow list --active # → lists runs by workflow ref, status, currentStepId, and updatedAt ``` ## Resume a blocked or failed run ```sh akm workflow resume ``` Flips a `blocked` or `failed` run back to `active`. Completed runs cannot be resumed. Use `akm workflow list` to find runs by status. Once resumed, `akm workflow run ` continues it — units already journaled as completed are skipped, not re-run (see [Architecture: Resume skips completed units](../architecture/workflow-engine.md#resume-skips-completed-units)). A resume consumes the frozen plan and journaled attempts; it does not re-read configuration or the index, and reads the authored workflow only to warn once when it changed since the run was frozen (the run continues on the frozen plan; `akm workflow run --new` picks up the edit). A stored plan this akm cannot decode is abandoned with a message naming how to start a new run. ## Abandon a run ```sh akm workflow abandon ``` Marks a run failed so it stops counting as active. This only changes the run's status — `resume` can still reopen it later if you change your mind. ## Follow a run's events There is no `akm workflow watch` (0.9.0: dropped — a foreground polling daemon in a one-shot CLI). `akm log --run ` reads the same `workflow_*` / `workflow_unit_*` events from the general append-only events stream: `--since '@offset:'` gives a durable row-id cursor a cooperating process can poll from, in place of `watch --stream`'s in-process loop. ```sh akm workflow run & # engine in one shell akm log --run --since '@offset:0' # backlog so far akm log --run --since '@offset:' # poll for more, from the prior call's nextOffset ``` Event metadata is ids/status/enums only — never workflow-authored content — so following a run's events is safe to pipe into logs or dashboards. ## Security: workflow sources are executed code Workflow steps that include shell commands run with **the full filesystem and network access of the user invoking `akm workflow run`** — same as if the user had typed those commands in their shell. There is no sandbox and no separation between trusted and untrusted workflows. An `exec` unit's *environment* is narrowed to an allowlist by default ([Workflow Schema](../reference/workflow-schema.md#the-childs-environment-is-an-allowlist)), which bounds accidental exposure of unrelated credentials — but a command that runs at all can still read those credentials off disk, so it is a hygiene boundary, not a containment one. AKM directly orchestrates workflows as a defined execution surface — it does not blindly execute arbitrary indexed content — but that orchestration still runs the workflow's own declared shell commands with your full access once you choose to run it. This is by design: a workflow is a runbook authored by you or by a bundle maintainer you trust. The flexibility of "run any shell command, read any file, hit any network" is what makes workflows useful as automation. The consequence is that **you should treat workflow sources the same way you treat package dependencies**: - **Only add workflow sources you trust.** `akm bundle add github:/` followed by `akm workflow run workflows/` is functionally equivalent to piping a stranger's bash script into your shell. Read the workflow file first (`akm show workflows/`) before running it. - **Audit before run** for any workflow that touches secrets, deploys to production, or writes outside the project tree. Read the `env:` bindings a workflow declares, and read its `exec.pass_env` lines. The durable v4 family (`irVersion: 5`) rejects `inherit_env`. Authors must use exact named bindings and `pass_env` names. - **Pin known-good versions** when adding workflow sources from a registry or git remote (`akm bundle add github:owner/repo#v1.2.3`), and update deliberately rather than via `akm bundle update --all`. A trusted workflow source can become hostile if its upstream is compromised. - **Workflow steps cannot escape this trust model** by being labeled `dryRun` or `interactive` — those flags affect bookkeeping, not execution. `akm workflow status` is read-only; `akm workflow run` executes configured units with your process's access. If you operate a CI runner or shared host where untrusted workflows might be executed, scope the process: a dedicated user account with no secrets in its environment, ephemeral working directory, and a network/filesystem allowlist enforced outside akm. ## See also - [Workflow Schema](../reference/workflow-schema.md) — exact frontmatter, refs, gates, and outputs syntax - [Author's Guide: Writing Workflows](../guides/author-workflows.md) — writing and testing a workflow definition - [Architecture: The Workflow Engine](../architecture/workflow-engine.md) — persistence, dispatch, and resume internals - [Scheduling](scheduling.md) — running akm tasks (including workflow runs) through the OS scheduler - [CLI Reference](../reference/cli.md) — full flag documentation for all `workflow` subcommands