# CLI reference

This page is generated from the command surface the release ships. `ariadnev` and `av` are interchangeable everywhere.

## Commands in this release

- [`ariadnev`](#ariadnev)
- [`ariadnev adapters`](#ariadnev-adapters)
- [`ariadnev adapters regenerate`](#ariadnev-adapters-regenerate)
- [`ariadnev add-skill`](#ariadnev-add-skill)
- [`ariadnev audit`](#ariadnev-audit)
- [`ariadnev backups`](#ariadnev-backups)
- [`ariadnev config`](#ariadnev-config)
- [`ariadnev config prefs`](#ariadnev-config-prefs)
- [`ariadnev contract`](#ariadnev-contract)
- [`ariadnev doctor`](#ariadnev-doctor)
- [`ariadnev eval`](#ariadnev-eval)
- [`ariadnev install`](#ariadnev-install)
- [`ariadnev journal`](#ariadnev-journal)
- [`ariadnev journal create`](#ariadnev-journal-create)
- [`ariadnev journal list`](#ariadnev-journal-list)
- [`ariadnev journal show`](#ariadnev-journal-show)
- [`ariadnev journal validate`](#ariadnev-journal-validate)
- [`ariadnev kit`](#ariadnev-kit)
- [`ariadnev kit install-path`](#ariadnev-kit-install-path)
- [`ariadnev kit refresh`](#ariadnev-kit-refresh)
- [`ariadnev list`](#ariadnev-list)
- [`ariadnev mcp`](#ariadnev-mcp)
- [`ariadnev mcp add`](#ariadnev-mcp-add)
- [`ariadnev mcp list`](#ariadnev-mcp-list)
- [`ariadnev mcp remove`](#ariadnev-mcp-remove)
- [`ariadnev mcp show`](#ariadnev-mcp-show)
- [`ariadnev mcp verify`](#ariadnev-mcp-verify)
- [`ariadnev migrate`](#ariadnev-migrate)
- [`ariadnev plan`](#ariadnev-plan)
- [`ariadnev plan archive`](#ariadnev-plan-archive)
- [`ariadnev plan check`](#ariadnev-plan-check)
- [`ariadnev plan cleanup`](#ariadnev-plan-cleanup)
- [`ariadnev plan close`](#ariadnev-plan-close)
- [`ariadnev plan list`](#ariadnev-plan-list)
- [`ariadnev plan phase`](#ariadnev-plan-phase)
- [`ariadnev plan reindex`](#ariadnev-plan-reindex)
- [`ariadnev plan resolve`](#ariadnev-plan-resolve)
- [`ariadnev plan search`](#ariadnev-plan-search)
- [`ariadnev plan show`](#ariadnev-plan-show)
- [`ariadnev plan status`](#ariadnev-plan-status)
- [`ariadnev plan uncheck`](#ariadnev-plan-uncheck)
- [`ariadnev plan update`](#ariadnev-plan-update)
- [`ariadnev plan use`](#ariadnev-plan-use)
- [`ariadnev query`](#ariadnev-query)
- [`ariadnev run`](#ariadnev-run)
- [`ariadnev run cancel`](#ariadnev-run-cancel)
- [`ariadnev run resume`](#ariadnev-run-resume)
- [`ariadnev run status`](#ariadnev-run-status)
- [`ariadnev skill`](#ariadnev-skill)
- [`ariadnev telemetry`](#ariadnev-telemetry)
- [`ariadnev uninstall`](#ariadnev-uninstall)
- [`ariadnev update`](#ariadnev-update)
- [`ariadnev validate`](#ariadnev-validate)

## `ariadnev`

Install a curated, quality-gated workflow kit across coding-agent targets.

### Options

| Options |  |
| --- | --- |
| `--cwd <dir>` | override project root |
| `--dry-run` | plan only, write nothing |
| `--home <dir>` | override home root |
| `--yes` | skip interactive prompts |
| `-V, --version` | output the version number |

## `ariadnev adapters`

Adapter artifacts projected from the install receipt, for tools that read that format

### Options

This command takes no options.

## `ariadnev adapters regenerate`

Rebuild the artifacts from the receipt (deterministic — a repair, not a reconcile)

### Options

| Options |  |
| --- | --- |
| `--global` | use the \~/ scope |
| `--json` | emit the machine envelope |

## `ariadnev add-skill`

Scaffold a new canonical skill in the kit

### Arguments

- `name` (required)

### Options

| Options |  |
| --- | --- |
| `--description <text>` | skill description |

## `ariadnev audit`

Compare installed files against the receipt, or scan the scripts the kit ships

### Arguments

- `target` — kit (default) \| scripts

### Options

| Options |  |
| --- | --- |
| `--global` | audit the \~/ scope |
| `--json` | emit JSON instead of the text report |
| `--strict` | count untracked files and flagged scripts as failures |

## `ariadnev backups`

List or restore ariadnev-managed backups

### Arguments

- `action` (required) — list \| restore \<timestamp\>
- `timestamp` — backup timestamp (for restore)

### Options

| Options |  |
| --- | --- |
| `--file <rel>` | restore only the file matching this name |
| `--global` | use \~/ scope |

## `ariadnev config`

Inspect ariadnev's own configuration

### Options

This command takes no options.

## `ariadnev config prefs`

Show the settings in effect after both config layers are applied

### Arguments

- `action` (required) — resolve

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope instead of the text report |

## `ariadnev contract`

Print the provider×artifact capability contract (--json for machines)

### Options

| Options |  |
| --- | --- |
| `--json` | emit JSON instead of the Markdown matrix |

## `ariadnev doctor`

Health-check the installed kit against its receipt

### Options

| Options |  |
| --- | --- |
| `--fix` | re-merge hook bindings that drifted out of settings.json (backs up first) |
| `--global` | check \~/ scope |

## `ariadnev eval`

Score kit quality — tier-1 static; tier-2 behavioral suite; optional tier-3 LLM judge

### Options

| Options |  |
| --- | --- |
| `--concurrency <count>` | maximum parallel isolated runs |
| `--deep-repeats <count>` | repeats for every golden task |
| `--model <name>` | pinned model identity |
| `--runner <json-argv>` | strict JSON argv array; prompt is sent on stdin |
| `--runtime-provider <name>` | pinned runtime provider identity |
| `--runtime-version <version>` | pinned runtime version identity |
| `--skill <name>` | only evaluate one skill (bare or av: prefixed) |
| `--skill-repeats <count>` | repeats for every skill routing cell |
| `--suite` | run the tier-2 behavioral scenario suite |
| `--timeout-ms <milliseconds>` | per-run timeout |
| `--variant <name>` | benchmark variant: ariadnev or reference |

## `ariadnev install`

Install the kit to one or more providers

### Options

| Options |  |
| --- | --- |
| `--global` | install to \~/ instead of ./ |
| `--provider <list>` | comma-separated provider ids |

## `ariadnev journal`

The technical journal: one dated entry per notable event

### Options

This command takes no options.

## `ariadnev journal create`

Write a dated entry

### Arguments

- `title` (required)

### Options

| Options |  |
| --- | --- |
| `--body <text>` | the entry body |
| `--component <name>` | what it is about |
| `--json` | emit the machine envelope |
| `--status <status>` | Resolved \| Ongoing \| Blocked \| Abandoned |

## `ariadnev journal list`

List entries, newest first

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--limit <count>` | how many to show |

## `ariadnev journal show`

Print one entry, by file name or a fragment of it

### Arguments

- `term` (required)

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev journal validate`

Check every entry has a title, a date, a status, and a body

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev kit`

Where the kit installs from and to

### Options

This command takes no options.

## `ariadnev kit install-path`

Show where each artifact kind would be written for a provider

### Arguments

- `provider` (required) — provider id

### Options

| Options |  |
| --- | --- |
| `--global` | resolve against the \~/ scope |
| `--json` | emit the machine envelope |

## `ariadnev kit refresh`

Discard the extracted kit cache and extract it again

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev list`

Show kit contents and per-provider install state

### Options

| Options |  |
| --- | --- |
| `--global` | check \~/ scope |

## `ariadnev mcp`

MCP servers this project and this user have configured

### Options

This command takes no options.

## `ariadnev mcp add`

Add a stdio server to this project (or to your own config with --global)

### Arguments

- `args` (variadic) — arguments passed to it
- `command` (required) — executable to run
- `name` (required)

### Options

| Options |  |
| --- | --- |
| `--global` | write to your own config instead of the project's |
| `--json` | emit the machine envelope |

## `ariadnev mcp list`

List configured servers across both scopes

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev mcp remove`

Remove a server from this project (or from your own config with --global)

### Arguments

- `name` (required)

### Options

| Options |  |
| --- | --- |
| `--global` | remove from your own config instead of the project's |
| `--json` | emit the machine envelope |

## `ariadnev mcp show`

Show one server's definition (env variable names only, never values)

### Arguments

- `name` (required)

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev mcp verify`

Start each server and check it completes the MCP initialize handshake

### Arguments

- `name` — verify one server instead of all of them

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev migrate`

Relocate installed files when provider path conventions change

### Options

| Options |  |
| --- | --- |
| `--global` | operate on \~/ instead of ./ |
| `--provider <id>` | limit to one provider |

## `ariadnev plan`

The plan this branch is working from

### Options

This command takes no options.

## `ariadnev plan archive`

Move a finished plan under the archive dir

### Options

| Options |  |
| --- | --- |
| `--force` | archive it even though it is not finished |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan check`

Mark a phase completed

### Arguments

- `phase` (required) — phase number

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan cleanup`

List finished plans still in the plans root; --archive moves them

### Options

| Options |  |
| --- | --- |
| `--archive` | move them instead of just listing |
| `--json` | emit the machine envelope |

## `ariadnev plan close`

Mark the plan completed

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan list`

List plan directories with their status and phase progress

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev plan phase`

Print one phase file in full

### Arguments

- `phase` (required) — phase number

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan reindex`

Re-read every plan and report what is malformed (there is no index to rebuild)

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev plan resolve`

Print the directory of the plan this branch points at

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev plan search`

Search every plan's files

### Arguments

- `query` (required)

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev plan show`

Show the plan this branch points at, with its phases

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev plan status`

Show or set the plan's own status

### Arguments

- `status` — pending \| in-progress \| completed \| cancelled; omit to read it

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan uncheck`

Put a phase back to pending

### Arguments

- `phase` (required) — phase number

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan update`

Set a phase's status, in the phase file and the index table

### Arguments

- `phase` (required) — phase number
- `status` (required) — pending \| in-progress \| completed \| cancelled

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |
| `--plan <name>` | act on this plan instead of the branch's |

## `ariadnev plan use`

Point this branch at a plan directory under the plans dir

### Arguments

- `name` (required) — plan directory name

### Options

| Options |  |
| --- | --- |
| `--json` | emit the machine envelope |

## `ariadnev query`

Show recorded ariadnev history (installs \| doctor \| history)

### Arguments

- `view` — installs \| doctor \| history

### Options

This command takes no options.

## `ariadnev run`

Validate or execute a versioned graph workflow

### Arguments

- `workflow` — canonical workflow ID

### Options

| Options |  |
| --- | --- |
| `--initial-state <json>` | initial graph state as a strict JSON object |
| `--instruction <text>` | workflow instruction |
| `--json` | emit a stable versioned JSON envelope |
| `--model <model>` | runtime model identity (stored outside Graph IR) |
| `--run-id <id>` | stable run ID (generated when omitted) |
| `--runtime <provider>` | explicit runtime: codex or claude-code |
| `--runtime-version <version>` | required runtime version (resume must match the original) |
| `--validate` | compile and lint without probing or executing |

## `ariadnev run cancel`

Request cooperative cancellation for an active run

### Arguments

- `run-id` (required) — existing run ID

### Options

| Options |  |
| --- | --- |
| `--json` | emit a stable versioned JSON envelope |

## `ariadnev run resume`

Resume a durable run with the original graph and runtime identity

### Arguments

- `run-id` (required) — existing run ID

### Options

| Options |  |
| --- | --- |
| `--instruction <text>` | workflow instruction |
| `--json` | emit a stable versioned JSON envelope |
| `--model <model>` | runtime model identity (stored outside Graph IR) |
| `--runtime <provider>` | explicit runtime: codex or claude-code |
| `--runtime-version <version>` | required runtime version (resume must match the original) |

## `ariadnev run status`

Read durable status without invoking a provider

### Arguments

- `run-id` (required) — existing run ID

### Options

| Options |  |
| --- | --- |
| `--json` | emit a stable versioned JSON envelope |

## `ariadnev skill`

Manage the Python environment a skill's scripts need, and run those scripts

### Arguments

- `action` (required) — install \| verify \| repair \| upgrade \| remove \| run
- `args` (variadic) — for run: script path, then its own arguments
- `name` — skill name (omit for verify/upgrade across every skill)

### Options

| Options |  |
| --- | --- |
| `--deep` | verify RECORD's files and import the packages in a child process |
| `--json` | emit JSON instead of the text report |

## `ariadnev telemetry`

Anonymous telemetry status (stateless, off unless configured; opt out with ARIADNEV\_TELEMETRY\_DISABLED=1)

### Arguments

- `action` — status

### Options

This command takes no options.

## `ariadnev uninstall`

Remove a previously installed kit (receipt-based, preserves user-modified files)

### Options

| Options |  |
| --- | --- |
| `--global` | uninstall from \~/ instead of ./ |
| `--provider <list>` | comma-separated provider ids (default: every provider in the receipt) |

## `ariadnev update`

Self-update to the latest ariadnev release (--check to only report)

### Options

| Options |  |
| --- | --- |
| `--check` | only report whether an update exists; don't install |
| `--global` | check \~/ scope |

## `ariadnev validate`

Lint the kit source (frontmatter, sizes, references, cross-skill routing) without installing

### Options

| Options |  |
| --- | --- |
| `--check` | also fail if the README provider matrix is out of sync (CI gate) |