CLI Overview

The ark binary has two visible top-level commands:

CommandWhat it does
ark initScaffold .ark/ and per-platform integrations from embedded templates.
ark loadRestore from .ark.db snapshot, or scaffold like init if no snapshot exists.
ark unloadSnapshot everything under .ark/ + managed blocks + Ark hooks into .ark.db.
ark removeWipe Ark fully: .ark/, platform dirs, managed blocks, .ark.db, hooks.
ark upgradeRefresh embedded templates to the current CLI version.
ark contextPrint a structured snapshot of git + .ark/ workflow state. Read-only.
ark archiveBulk-move every phase = Committed task into its committed_at month bucket. Manager-only.

Plus one hidden internal command:

CommandPurpose
ark agentTask lifecycle and spec management. Not semver-stable.

Stability policy

  • Visible commands (the six above) are semver-stable. Flags don't disappear within a major version; output formats (especially ark context --format json) follow additive-only schema versioning.
  • ark agent is internal. Its callers are the shipped slash commands and the workflow doc. The CLI surface is not covered by semver — the binary and its shipped templates version together.

End users should drive workflow through slash commands, not by calling ark agent directly. See ark agent for when you do need to reach for it (mostly: rare lifecycle operations the slash commands don't cover).

Project discovery

Most commands find the project root by walking ancestors looking for a .ark/ directory:

  • ark context, ark unload, ark remove, ark upgrade, ark load (without --force) — walk up from cwd.
  • ark init and ark load --force — operate on the explicit target (defaulting to cwd if --dir is omitted). They scaffold a project; they don't locate one.

Pass --dir <path> to override discovery. When provided, it always wins.

Conventions

  • Errors print to stderr with error: <message> and a chained caused by: for each source. Exit code 1 on any failure.
  • --help is supported on every level. ark --help lists top-level commands; ark <cmd> --help lists flags for that command. ark agent --help is the only way to see the hidden namespace.
  • JSON output. Only ark context --format json produces machine-readable output; the rest are human-targeted summaries via Display.