---
title: CLI
description: Every command, subcommand and flag of ak-harness, walked from the program itself.
---

{/* Generated by `pnpm docs:generate`. Do not edit by hand: edit `src/cli.ts` and regenerate. */}

`ak-harness` is the harness; `ak-verify` is an alias of the same binary for the common verification protocol.
Every loop command takes `-f <path-to-loop.config.yaml>` and defaults to `./loop.config.yaml`.

## `ak-harness doctor`

Validate the contract without starting a run.

```bash
ak-harness doctor [options]
```

## `ak-harness plan`

Approve the frozen task contract and create a planned run.

```bash
ak-harness plan [options] <decision>
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | approval actor | `"human"` |
| `--allow-dirty` | allow a human-authorized dirty worktree |  |
| `--context-file &lt;path&gt;` | attach a context snapshot JSON file |  |

## `ak-harness context`

Resolve portable, provenance-bearing context snapshots.

```bash
ak-harness context [options] [command]
```

### `ak-harness context resolve`

Resolve a Doc Bridge snapshot from the local index.

```bash
ak-harness context resolve [options] <query>
```

| Flag | What it does | Default |
|---|---|---|
| `--provider &lt;provider&gt;` | context provider | `"doc-bridge"` |
| `--scope &lt;scope...&gt;` | optional search scopes |  |
| `--index &lt;path&gt;` | Doc Bridge index path | `".doc-bridge/index.json"` |

## `ak-harness discovery`

Assess a structured discovery result before implementation.

```bash
ak-harness discovery [options] [command]
```

### `ak-harness discovery assess`

Emit Ready or a human decision packet from a discovery JSON file.

```bash
ak-harness discovery assess [options] <input>
```

## `ak-harness wip`

Assess deterministic WIP admission before starting work.

```bash
ak-harness wip [options] [command]
```

### `ak-harness wip assess`

Emit an admission decision from WIP ledger JSON.

```bash
ak-harness wip assess [options] <input>
```

## `ak-harness experiment`

Select a runtime only from a controlled, comparable experiment.

```bash
ak-harness experiment [options] [command]
```

### `ak-harness experiment select`

Select the eligible runtime from experiment JSON.

```bash
ak-harness experiment select [options] <input>
```

## `ak-harness delivery`

Assess deterministic G2–G5 gates and prepare idempotent PR handoff.

```bash
ak-harness delivery [options] [command]
```

### `ak-harness delivery preflight`



```bash
ak-harness delivery preflight [options] <input>
```

### `ak-harness delivery pr`



```bash
ak-harness delivery pr [options] <input>
```

### `ak-harness delivery integration`



```bash
ak-harness delivery integration [options] <input>
```

### `ak-harness delivery production`



```bash
ak-harness delivery production [options] <input>
```

### `ak-harness delivery acceptance`



```bash
ak-harness delivery acceptance [options] <input>
```

### `ak-harness delivery cleanup`



```bash
ak-harness delivery cleanup [options] <input>
```

## `ak-harness pilot`

Freeze and assess a ten-issue pilot cohort.

```bash
ak-harness pilot [options] <input>
```

## `ak-harness cycle`

Run the five-step improvement cycle with explicit adjustment and bounded repetition.

```bash
ak-harness cycle [options] [command]
```

### `ak-harness cycle assess`

Assess run → verify → adjust → repeat from a cycle JSON file.

```bash
ak-harness cycle assess [options] <input>
```

## `ak-harness block`

Validate and assess a portable execution block manifest.

```bash
ak-harness block [options] [command]
```

### `ak-harness block validate`



```bash
ak-harness block validate [options] <input>
```

### `ak-harness block assess`



```bash
ak-harness block assess [options] <input>
```

| Flag | What it does | Default |
|---|---|---|
| `--completed &lt;ids...&gt;` | completed dependency IDs |  |

## `ak-harness preflight`

Plan safe, file-scoped validation before commit.

```bash
ak-harness preflight [options] [command]
```

### `ak-harness preflight files`



```bash
ak-harness preflight files [options] <input>
```

## `ak-harness snapshot`

Create or validate a deterministic status snapshot.

```bash
ak-harness snapshot [options] [command] <input>
```

### `ak-harness snapshot validate`



```bash
ak-harness snapshot validate [options] <input>
```

## `ak-harness learning`

Parse retrospectives into proposed learnings.

```bash
ak-harness learning [options] [command]
```

### `ak-harness learning parse`



```bash
ak-harness learning parse [options] <input>
```

| Flag | What it does | Default |
|---|---|---|
| `--source &lt;source&gt;` |  |  |

## `ak-harness coordination`

Manage idempotent issue/worktree claims and dispatch records.

```bash
ak-harness coordination [options] [command]
```

### `ak-harness coordination claim`



```bash
ak-harness coordination claim [options] <input>
```

## `ak-harness artifacts`

Inspect versioned, provenance-bound run artifacts.

```bash
ak-harness artifacts [options] [command]
```

### `ak-harness artifacts inspect`

Validate and print one artifact as JSON or Markdown.

```bash
ak-harness artifacts inspect [options] <path>
```

### `ak-harness artifacts list`

List artifacts for the latest or selected run.

```bash
ak-harness artifacts list [options] [run-id]
```

### `ak-harness artifacts schema`

Print the artifact schema version.

```bash
ak-harness artifacts schema [options]
```

## `ak-harness loop`

Keep-pushing SDLC loop: drain one person's Linear queue through Orca worktrees with role-based model routing.

```bash
ak-harness loop [options] [command]
```

| Flag | What it does | Default |
|---|---|---|
| `-f, --file &lt;path&gt;` | loop config path | `"loop.config.yaml"` |

### `ak-harness loop validate`

Validate loop.config.yaml and print the effective configuration.

```bash
ak-harness loop validate [options]
```

### `ak-harness loop doctor`

Check Orca, providers, usage, machine slots, routing, and the Linear queue without dispatching.

```bash
ak-harness loop doctor [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--no-probe` | skip provider probe commands |  |

### `ak-harness loop precheck`

Read-only Orca precheck: exit 0 when the stage (tick \| deliver) has work.

```bash
ak-harness loop precheck [options] <stage>
```

### `ak-harness loop deliver`

Drive dispatched workers to merge: PR detection, CI, review, fix rounds, squash-merge, Linear Done, cleanup.

```bash
ak-harness loop deliver [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--dry-run` | decide only; no terminal input, no review, no merge, no Linear write |  |
| `--issue &lt;identifier&gt;` | restrict to one issue |  |

### `ak-harness loop stage`

Run one stage (tick \| deliver \| retro \| observe \| release \| intake \| maintain) as an Orca precheck: prints the JSON report and exits 1 so Orca records the run without launching an agent — except `observe`, which exits 0 when a human has to look.

```bash
ak-harness loop stage [options] <stage>
```

### `ak-harness loop tick`

One keep-pushing tick: intake → admit → contract → dispatch workers into Orca worktrees.

```bash
ak-harness loop tick [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--dry-run` | plan only; no worktree, no Linear write, no contract cached |  |
| `--max &lt;n&gt;` | max dispatches this tick |  |
| `--issue &lt;identifier&gt;` | restrict to one issue |  |
| `--skip-contract` | do not call the orchestrator when no contract is cached |  |

### `ak-harness loop contract`

Freeze (or show) the orchestrator contract for one Linear issue.

```bash
ak-harness loop contract [options] <identifier>
```

| Flag | What it does | Default |
|---|---|---|
| `--refresh` | regenerate even when a cached contract exists |  |
| `--dry-run` | generate but do not cache |  |

### `ak-harness loop init`

Grill the essentials and write loop.config.yaml from a preset (web-app \| library \| monorepo \| data-pipeline \| mobile). Everything the preset already says is left unsaid.

```bash
ak-harness loop init [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--preset &lt;name&gt;` | skip the question and use this preset |  |
| `--repo &lt;owner/name&gt;` | GitHub repository |  |
| `--name &lt;name&gt;` | project name |  |
| `--team &lt;key&gt;` | Linear team key |  |
| `--workspace &lt;id&gt;` | Linear workspace id |  |
| `--person &lt;name&gt;` | whose queue this machine drains |  |
| `--global` | also write ~/.agentskit/harness.yaml when it does not exist |  |
| `--force` | replace an existing file |  |
| `--dry-run` | print what it would write |  |

### `ak-harness loop install`

Guided install: doctor + environment checks, optional dry-run tick, then create/update the Orca automations after confirmation (idempotent by name).

```bash
ak-harness loop install [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--yes` | accept every prompt (non-interactive) |  |
| `--force` | continue past failed checks |  |
| `--skip-rehearsal` | do not run the dry-run tick |  |
| `--skip-local-config` | do not offer to create loop.config.local.yaml |  |
| `--dry-run` | show checks and the exact orca argv; create nothing |  |
| `--provider &lt;agent&gt;` | Orca agent id that runs the automation prompt |  |
| `--plain` | legacy behaviour: no checks, no prompts, install immediately |  |

### `ak-harness loop uninstall`

Remove the loop automations from Orca.

```bash
ak-harness loop uninstall [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--dry-run` | print what would be removed |  |

### `ak-harness loop status`

Show the loop automations Orca knows about and their latest runs.

```bash
ak-harness loop status [options]
```

### `ak-harness loop resume`

Resume a paused issue (clears its failure counter and removes the pause label) or, with --stage, a paused tick/deliver stage.

```bash
ak-harness loop resume [options] [issue]
```

| Flag | What it does | Default |
|---|---|---|
| `--stage &lt;stage&gt;` | resume a paused stage (tick \| deliver) instead of an issue |  |

### `ak-harness loop paused`

List issues the loop has paused after repeated failures (local state, no network calls).

```bash
ak-harness loop paused [options]
```

### `ak-harness loop hook`

Status-only line for a SessionStart hook: never installs or changes anything; always exits 0 within a few seconds.

```bash
ak-harness loop hook [options]
```

### `ak-harness loop debrief`

Human-facing explanation of what the loop is working on right now (in-flight issues, holds, escalations, cooldowns). Read-only; Markdown by default.

```bash
ak-harness loop debrief [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--issue &lt;identifier&gt;` | restrict to one issue |  |
| `--since &lt;window&gt;` | how far back to look for escalations/events | `"24h"` |

### `ak-harness loop observe`

Read-only anomaly scan and operating metrics for the loop (queue, workers, delivery, machine, memory, cache, tokens).

```bash
ak-harness loop observe [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--since &lt;window&gt;` | window such as 24h, 7d or an ISO date | `"24h"` |
| `--precheck` | exit 0 when an action is required, 1 when healthy (for schedulers) |  |

### `ak-harness loop watch`

Watch delivery.json (+ optional live PR) for in-flight issues; prints DONE / FAILED / ACTION_REQUIRED / PROGRESS. Read-only.

```bash
ak-harness loop watch [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--issue &lt;identifier&gt;` | restrict to one issue |  |
| `--interval &lt;seconds&gt;` | poll interval | `30` |
| `--once` | single snapshot then exit |  |
| `--timeout &lt;seconds&gt;` | stop after N seconds (0 = until terminal) | `0` |
| `--no-live-pr` | do not call gh; filesystem state only |  |

### `ak-harness loop retro`

Digest of the loop over a window: escalations, dispatches, reviews, merges, cooldowns, Orca runs, and calibration suggestions. Markdown by default, --json for the report.

```bash
ak-harness loop retro [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--since &lt;window&gt;` | window such as 7d, 12h, 30m or an ISO date | `"7d"` |
| `--learnings` | print harness learning records (proposed) instead of the digest |  |
| `--no-orca` | skip the Orca run summary |  |
| `--target &lt;target&gt;` | only suggestions for one side: project \| harness |  |

### `ak-harness loop plan`

Requirements → PRD → technical design → issues. One question per round, two human gates, and the queue entry stays a human gesture.

```bash
ak-harness loop plan [options] [command]
```

### `ak-harness loop plan start`

Start a plan from a vague objective and ask the first question.

```bash
ak-harness loop plan start [options] <objective...>
```

### `ak-harness loop plan answer`

Answer the open question and ask the next one. The interview ends when the PRD has no gap left — the machine decides that, not the model.

```bash
ak-harness loop plan answer [options] <id> <answer...>
```

### `ak-harness loop plan show`

Show a plan (Markdown by default), or list every plan when no id is given.

```bash
ak-harness loop plan show [options] [id]
```

### `ak-harness loop plan approve`

Human gate: approve the PRD, which starts the architect.

```bash
ak-harness loop plan approve [options] <id>
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | who approves | `"human"` |

### `ak-harness loop plan architect`

Produce the technical design for the whole PRD and put it to a vote (2 of 3 by default).

```bash
ak-harness loop plan architect [options] <id>
```

### `ak-harness loop plan approve-design`

Human gate: approve the design after it reached consensus. Everything built afterwards inherits it.

```bash
ak-harness loop plan approve-design [options] <id>
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | who approves | `"human"` |

### `ak-harness loop plan decompose`

Break the approved design into issues. Without --create nothing is written to the tracker.

```bash
ak-harness loop plan decompose [options] <id>
```

| Flag | What it does | Default |
|---|---|---|
| `--create` | create the issues in the tracker, in the queue entry state |  |

### `ak-harness loop release`

Promote the integration branch to the release branch and run the project deploy — only for a batch a human approved.

```bash
ak-harness loop release [options] [command]
```

### `ak-harness loop release status`

What is merged on the integration branch and not yet released, and whether it is approved.

```bash
ak-harness loop release status [options]
```

### `ak-harness loop release approve`

Human gate: approve exactly the batch currently on the integration branch. Anything merged afterwards needs its own approval.

```bash
ak-harness loop release approve [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | who approves | `"human"` |

### `ak-harness loop release run`

Promote and deploy the approved batch (same work as `loop stage release`, but with a human-readable report).

```bash
ak-harness loop release run [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--dry-run` | show what would happen; touch nothing |  |

### `ak-harness loop learning`

Continuous-improvement learnings ledger and approved memory writes.

```bash
ak-harness loop learning [options] [command]
```

### `ak-harness loop learning list`

Show the learnings ledger under stateDir (proposed/promoted/rejected).

```bash
ak-harness loop learning list [options]
```

### `ak-harness loop learning promote`

Human-only: promote learning IDs into approved loop memory (token-reducing context for later tickets).

```bash
ak-harness loop learning promote [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--ids &lt;ids&gt;` | comma-separated learning ids |  |
| `--by &lt;actor&gt;` | must be human | `"human"` |
| `--revision &lt;rev&gt;` | sourceRevision stamped on memory records (default: unknown) |  |

### `ak-harness loop learning reject`

Revoke learnings — including any the loop promoted by itself as `loop-auto`. The record stays in the ledger, marked rejected, and stops reaching worker briefs.

```bash
ak-harness loop learning reject [options]
```

| Flag | What it does | Default |
|---|---|---|
| `--ids &lt;ids&gt;` | comma-separated learning ids |  |
| `--by &lt;actor&gt;` | who revokes | `"human"` |

### `ak-harness loop learning promoted`

List the learnings currently promoted, and which of them the loop promoted by itself.

```bash
ak-harness loop learning promoted [options]
```

## `ak-harness start`

Move a planned run into implementation.

```bash
ak-harness start [options]
```

## `ak-harness verify`

Execute every configured check and record evidence.

```bash
ak-harness verify [options]
```

## `ak-harness run`

Alias for verify, compatible with the common protocol.

```bash
ak-harness run [options]
```

## `ak-harness approve`

Record human approval or rejection. Use only &lt;decision&gt; to apply it to the latest pending run; run IDs remain an audit detail.

```bash
ak-harness approve [options] <run-id-or-decision> [decision-or-run-id]
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | approval actor | `"human"` |

## `ak-harness authorize`

Authorize or reject declared external tracking. Use only &lt;decision&gt; to apply it to the latest pending run; run IDs remain an audit detail.

```bash
ak-harness authorize [options] <run-id-or-decision> [decision-or-run-id]
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | approval actor | `"human"` |

## `ak-harness retry`

Create a new implementation attempt after a blocked or stale run.

```bash
ak-harness retry [options]
```

## `ak-harness cancel`

Cancel an active run.

```bash
ak-harness cancel [options] [run-id]
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | cancellation actor | `"human"` |
| `--reason &lt;reason&gt;` | cancellation reason | `"Run cancelled by a human."` |

## `ak-harness status`

Show the latest run after reconciling its audit evidence.

```bash
ak-harness status [options]
```

## `ak-harness audit`

Reconcile a run projection with its verified lifecycle decisions.

```bash
ak-harness audit [options] [run-id]
```

## `ak-harness events`

Inspect the lifecycle audit log.

```bash
ak-harness events [options] [command]
```

### `ak-harness events verify`

Verify the latest or selected event log hash chain.

```bash
ak-harness events verify [options] [run-id]
```

### `ak-harness events lock`

Inspect the latest or selected event-log lock.

```bash
ak-harness events lock [options] [run-id]
```

### `ak-harness events unlock`

Recover an old event-log lock after confirming its owner is dead.

```bash
ak-harness events unlock [options] [run-id]
```

| Flag | What it does | Default |
|---|---|---|
| `--by &lt;actor&gt;` | recovery actor | `"human"` |
| `--max-age-ms &lt;milliseconds&gt;` | minimum lock age | `300000` |

### `ak-harness events export`

Export a reconciled COMPLETE run as a signed evidence bundle.

```bash
ak-harness events export [options] [run-id]
```

| Flag | What it does | Default |
|---|---|---|
| `--output &lt;path&gt;` | bundle output path |  |
| `--private-key &lt;path&gt;` | Ed25519 private key path |  |
| `--key-id &lt;id&gt;` | stable signing key identity |  |

### `ak-harness events verify-bundle`

Verify an exported signed evidence bundle independently.

```bash
ak-harness events verify-bundle [options] <path>
```

| Flag | What it does | Default |
|---|---|---|
| `--trusted-key-store &lt;path&gt;` | JSON trust store with active or revoked public keys |  |

## `ak-harness benchmark`

Aggregate reproducible metrics from historical runs.

```bash
ak-harness benchmark [options] [command]
```

| Flag | What it does | Default |
|---|---|---|
| `--manifest &lt;path&gt;` | benchmark manifest for baseline comparison |  |

### `ak-harness benchmark baseline`

Record one controlled baseline observation in a benchmark manifest.

```bash
ak-harness benchmark baseline [options] <taskId>
```

| Flag | What it does | Default |
|---|---|---|
| `--manifest &lt;path&gt;` | benchmark manifest path |  |
| `--status &lt;status&gt;` | passed, failed, blocked, or not-run |  |
| `--source &lt;source&gt;` | baseline source or run reference |  |
| `--evidence-file &lt;path&gt;` | JSON file with criterion-level baseline evidence |  |
| `--recorded-at &lt;timestamp&gt;` | ISO-8601 timestamp |  |
| `--attempts &lt;count&gt;` | attempt count |  |
| `--duration-ms &lt;milliseconds&gt;` | duration in milliseconds |  |
| `--review-minutes &lt;minutes&gt;` | human review time in minutes |  |
| `--escaped-incomplete &lt;count&gt;` | incomplete deliveries discovered after handoff |  |

## `ak-harness clean`

Remove only configured task-owned temporary artifacts.

```bash
ak-harness clean [options]
```