docs · cli

The zharness CLI.

A small Rust binary (about 574 KiB) that scaffolds, updates, and removes the managed markdown workflow doc set. It has no runtime dependencies and ships for macOS arm64 and Linux amd64/arm64.

Architecture (v0.24).

zharness has been an installer and updater only since v0.15, which removed the runtime command surface and the derived database layer. v0.24.0 rewrote it from Go to Rust (clap). The verbs, flags, exit codes, written bytes, and .zharness/base/manifest.json schema are unchanged, and a manifest written by Go v0.23.1 updates without a forced reinstall. Help text now uses clap's Commands:/Options: headings. State lives exclusively in git-committed markdown, and fail-closed safety guarantees live in repository pre-commit hooks.

The CLI registers exactly three verbs: install, update, and uninstall. The root takes --help and --version; every verb takes --root.

Flag
Type
Description
01
--root <dir>
string
Target repository root directory (default: git toplevel of the working directory).
02
-h, --help
boolean
Display command-line help for root or any verb.
03
-v, --version
boolean
Display the zharness binary version string.

Commands.

The three verbs manage the lifecycle of canonical workflow files in target repositories.

Command
Guarantees
Exit Codes
01
zharness install
Scaffolds the managed doc set (WORKFLOW.md, PROJECT.md, playbooks, AGENTS.md block, ignore entry). Records a sha256 manifest in .zharness/base/ and the repository in ~/.config/zharness/repos. Idempotent.
0 success, 1 error
02
zharness update
Overwrites playbooks and WORKFLOW.md; writes PROJECT.md only when absent; replaces the AGENTS.md block between its markers, refusing with a diff if the block was edited since the last write. Every refusal runs before the first write. Migrates a single 9-section active plan to 5 sections, ## Validation bytes unchanged.
0 success, 1 error, refusal, or drift (--check)
03
zharness uninstall
Removes managed files whose bytes match what zharness last wrote; locally modified ones are kept and listed. Removes the repository from the registry.
0 success, 1 error

Command flags reference.

Flags beyond --root and --help. install and uninstall take none.

Verb
Flag
Description
02.1
update
--force
Replace an AGENTS.md block edited since the last write (default: refuse and print the diff).
02.2
update
--check
Report drift from this binary without writing; exit 1 on drift. Takes no --force.
02.3
update
--all
With --check: every repository in ~/.config/zharness/repos.

Terminal usage.

Common invocation patterns for installation, drift checks, updates, and removal.

bash — zharness cli workflow 
# 1. Scaffold managed documentation into the repository
$zharness install
installed  docs/WORKFLOW.md
installed  docs/PROJECT.md
installed  docs/playbooks/brainstorm.md
…
installed  AGENTS.md (created)
updated    .gitignore (+.zharness/)
exit: 0

# 2. Report drift from this binary without writing
$zharness update --check
drift    /path/to/repo
  stale    docs/playbooks/work.md
exit: 1

# 3. Refresh the managed docs
$zharness update
refreshed      docs/WORKFLOW.md
refreshed      docs/playbooks/work.md
…
update complete.
exit: 0

# 4. Safe uninstallation
$zharness uninstall
uninstall complete — 11 managed file(s) removed, 1 kept:
  docs/playbooks/work.md — locally modified; delete manually if intended
exit: 0

State model & Fail-closed guards.

Committed markdown is the only source of truth. System state and safety guarantees are partitioned cleanly across tracked files and Git hooks.

docs/plans/active/*.mdInitiative plans containing requirements, phases, tasks, and append-only progress log.
docs/playbooks/*.mdCanonical stage execution procedures, managed and synchronized via zharness update.
docs/decisions/Immutable Architecture Decision Records (ADRs) numbered sequentially.
docs/memory/Cross-session durable facts and preferences tracked in plain markdown.
.zharness/base/sha256 manifest of what zharness last wrote; guards the AGENTS.md block and scopes uninstall.
scripts/install-git-hooks.shFail-closed pre-commit validation hook (proof re-execution + independent judge separation).