CLI reference
Doc type: Reference · Applies to: POSE 1.4.x
The pose CLI is a single native Go binary. Every command below executes
without Bash or Python fallbacks and works offline.
Scaffold
| Command | Purpose |
|---|---|
pose init [--wizard [--yes]] |
Ensure the minimal structure; the wizard detects stacks and seeds the validation matrix |
pose new-spec <slug> |
Create .pose/specs/<slug>/spec.md from the template |
pose new-roadmap <slug> |
Create a governed roadmap in .pose/roadmaps/ |
pose new-adr "<title>" |
Create a dated ADR |
pose new-knowledge <type> <slug> |
Create handoff/note/decision-log (--owner, --ttl-days, --restricted) |
Deterministic gates
| Command | Purpose |
|---|---|
pose check [--strict\|--tolerant] |
Structural integrity + matrix schema + task-map sync + spec graph + schema version |
pose validate [--strict\|--tolerant] [--stack s] [--module p] [--report] |
Run the validation matrix |
pose lint-spec <slug>\|--all [--ready-check] |
Section content, DoR entry gate, done-lifecycle gate |
pose followups [--open\|--all] [--json] |
Aggregate follow-ups + near-duplicate candidates |
pose knowledge-check [--max-overdue N] |
Knowledge schema + overdue backlog |
pose recurrence-check [--window-days N] [--threshold T] |
Recurring failing task slugs |
pose history-check |
All history JSONL must be git-tracked |
pose artifact-check --spec S [--from A --to B] |
Reconcile declared artifacts with an immutable Git change set |
pose surface-check [--spec S] [--results P] |
Prove composition/reachability with current typed validation evidence |
pose roadmap-check <slug> |
Evaluate member closeout, registered cut criteria and required delivery findings |
Component-aware and convergent review
| Command | Purpose |
|---|---|
pose review-plan <scope> [--json] [--explain] |
Resolve the deterministic component-aware plan, provenance, criteria, safe native-tool guidance and plan digest |
pose review bundle <scope> [--json] [--explain] [--seal] |
Prepare the semantic review subject or persist it as an immutable rvb- bundle after required evidence is current |
pose review auto-attest <bundle-id\|scope-ref> [--reviewer <id>] [--apply] |
Extract matching evidence from validation results, resolve tool dispositions and record attestation |
pose review attest <bundle-id> --reviewer ID --decision D --evidence REF [--plan-digest SHA] [--tool DISPOSITION] [--finding FINDING] [--apply] |
Preview or append a local rva- attestation bound to the exact sealed bundle |
pose review attest --envelope <project-relative-path> [--apply] |
Verify and preview/import a policy-trusted external attestation envelope |
pose review verify <scope\|bundle-id\|bundle-path> [--json] |
Verify bundle freshness, attestation completeness and closeout readiness |
pose review-check <scope> [--json] |
Enforce the current review plan and accepted attempt/attestation |
pose closeout-check <scope> [--json] |
Evaluate hierarchical spec, milestone or roadmap closure |
<scope> is spec:<slug>, milestone:<roadmap>/<id> or
roadmap:<slug>. Component-aware planning and sealed bundles are explicit
policy opt-ins; legacy policies and historical attempts remain readable. The
convergent path is:
pose review bundle spec:customer-export --explain
pose validate --strict
pose review bundle spec:customer-export --seal
pose review auto-attest spec:customer-export --reviewer agent:reviewer-a --apply
pose review verify spec:customer-export
pose review-check spec:customer-export
pose closeout-check spec:customer-export
The bundle digest includes governed semantic inputs, attributed patch/tree identity, consumed plan inputs and required evidence identities. Lifecycle bookkeeping, generated state and the attestation itself stay outside that digest, so approval does not invalidate its own subject. Semantic or source changes create a superseding bundle with a typed delta; derived closeout updates do not force a mechanical rereview. Plan resolution, bundle preview and verification never execute recommended tools or widen caller authority.
Discovery, metrics, artifacts
| Command | Purpose |
|---|---|
pose suggest [<type>] [--domain d] [--path p] [--json] |
Canonical trail: workflow + skill + rules |
pose stats [workflows\|tasks\|contexts] [--since-days N] |
Outcome aggregation from history |
pose usage [--since-days N] [--tool NAME] [--surface cli\|mcp] [--json] |
Automatic local tool calls, outcomes, finding lifecycle and latency by CLI/MCP surface |
pose index |
Regenerate all indexes (repo-map, spec-graph, roadmaps…) |
pose report --task "..." [--outcome ...] [--since ref] |
Versionable report + history JSONL |
pose usage needs no counters from agents. POSE records recognized terminal
CLI commands and project-backed MCP tool calls at their execution boundaries;
the query itself is excluded. Exact structured gates contribute their stable
findings, so the report can distinguish total observations from unique, new,
resolved and reopened findings. Generic failures remain conservative instead
of parsing arbitrary terminal output.
The journal is best-effort and local-only, outside the tracked worktree. Its
allowlisted event schema never persists command arguments, output, repository
paths/names, source content, project/user identity or raw finding IDs; scope
and finding identities are project-local HMAC fingerprints. Recording failure
never changes the wrapped command's output or exit code. Use
POSE_USAGE_DISABLED=1 to disable collection. These are POSE product-usage
signals, separate from DORA delivery metrics and unsuitable for individual
productivity scoring.
Set POSE_USAGE_DIR only when an operator needs an explicit absolute local
state directory (for example, a persistent container mount); the default Git
common-dir/user-cache resolution is preferred.
POSE does not infer the future human adjudication states valid,
wont-fix or false-positive; that evolution remains an owned follow-up and
will stay separate from automatic observation counts. See
Analytics and delivery metrics for interpretation and examples.
DORA and adoption metrics
| Command | Purpose |
|---|---|
pose record-deployment --application A --environment E --deployment-kind planned\|rework --status success\|failure --source manual\|ci\|webhook [--deployed-at RFC3339] [--lead-time-seconds N] [--change-ref R] |
Ingest one schema-v2 deployment event |
pose record-incident --application A --environment E --started-at RFC3339 --severity minor\|major\|critical --source manual\|ci\|webhook [--resolved-at RFC3339] [--caused-by-deployment] |
Ingest one schema-v2 incident event |
pose dora-metrics [--application A] [--environment E] [--window-days N] [--json] |
The current 5 DORA metrics for one production environment; E defaults to production |
pose adoption-metrics [--json] |
Activation, time-to-first-gate, retention, task success — derived from specs/history POSE already owns |
pose events-housekeeping <list-expired\|purge> [--older-than-days N] [--apply] |
Retention/deletion for stored deployment/incident events |
Deployment and incident events are explicit input only — POSE never infers
them from commits — and carry no identity field beyond application and
source; every metric is a team/application aggregate, never an
individual score. The five metrics are deployment frequency, lead time for
changes, change failure rate, failed deployment recovery time and deployment
rework rate. Recovery includes only resolved incidents explicitly marked
caused_by_deployment; rework requires every scoped deployment to declare
deployment_kind, otherwise that metric reports unavailable instead of
guessing that legacy events were planned. Schema-v1 JSONL remains readable.
See DORA metrics guide.
For a side-by-side model of usage, adoption and delivery signals, see
Analytics and delivery metrics.
Semantic governance assist
| Command | Purpose |
|---|---|
pose semantic-suggest (--for <spec-slug>\|--query "text") [--top N] [--provider lexical] [--json] |
Advisory suggestions: related follow-ups, recurrence patterns and knowledge, each cited with score/rationale/provider |
pose suggest-feedback --for <spec-slug> --ref <artifact-ref> --kind knowledge\|followup\|recurrence --decision accept\|reject [--score N] |
Record a minimized accept/reject decision (never the candidate's content) |
Suggestions are advisory only — they never gate a check or mutate a spec.
lexical (deterministic, offline token/sequence similarity) is the only
approved provider today; sensitivity-restricted knowledge is filtered
before any retrieval, never suggested.
Capability assessment
| Command | Purpose |
|---|---|
pose assess |
Validate .pose/capabilities/assessment.md: schema, typed evidence resolution, stable mechanism ids, staleness vs. policy |
pose assess init |
Scaffold the artifact with the method's 16 default mechanisms |
pose assess snapshot |
Append the current score vector to history.jsonl (append-only; no-op when unchanged) |
pose assess diff [--from <ts>] [--to <ts>] [--against <project-id>] [--json] |
Mechanical comparison between two snapshots (raised/lowered/added/retired), or a score matrix against another authorized root |
pose assess stale [--json] |
List mechanisms currently marked assessment-stale, with their pending trigger(s) |
pose assess request --mechanism <id> [--reason <text>] |
Manually mark one mechanism stale (the same path a UI-driven "flag for reassessment" action would call over MCP) |
Scores are human judgment (0-5; the target is not always 5) — the mechanism
validates structure and evidence, it never computes a score. Evidence uses
typed references (spec:/report:/adr:/knowledge:/doc:/commit:/
check:/url:); local types must resolve, the rest are syntactic
(offline contract). pose check --strict runs the same validation when the
artifact exists (opt-in by presence). Staleness thresholds live in
.pose/policy/capabilities.json (defaults: 30 days / 200 commits).
Reassessment triggers (spec pose-capability-assessment-triggers): a
post-event hook consumer marks a mechanism assessment-stale whenever a spec
closeout reaches components that materialize it — resolved via
components_hit when GraphForge is configured, or by matching the event's
touched files against a mechanism's declared paths: globs (a manual,
semicolon-separated fallback field on the mechanism) when it is not. A stale
mark never touches the score; it only records since/trigger/hits on
the mechanism and projects a synthetic, owned follow-up (origin
capability:<mechanism>) into pose followups --open, so the reassessment
demand is cobrável without a second store. pose assess snapshot clears
every pending mark on the mechanisms it scores, linking the clearance to the
new snapshot in history.jsonl. Without a component map and without any
paths: declared, the event logs a visible
capability_mapping_unavailable outcome instead of marking anything
silently. Anti-noise thresholds (min_hits, hit level, the follow-up's
default owner/review SLA) share the same .pose/policy/capabilities.json
policy file.
Docs governance
| Command | Purpose |
|---|---|
pose docs-init [--profile library\|service\|cli\|monorepo] |
Scaffold .pose/docs.json with a profile's recommended roots — a recommendation, never mandatory |
pose docs-check [--json] [--explain <rule>] |
Validate the manifest: declared docs exist, undeclared docs are flagged, frontmatter/links/typed references resolve, staleness, and a security scan |
pose docs-review resolve <doc> [--no-change --reason <text>] [--commit <sha>] |
Close a doc's pending review marks: updated (default, captures the current commit unless --commit is given) or no_change_needed (--reason required) |
pose docs-review request <doc> [--reason <text>] |
Manually mark one doc for review (the same path a UI-driven "flag for review" action would call over MCP) |
pose docs-review request --all-stale |
Bridge every doc docs-check reports stale into an active, owned review-pending demand, in one call |
Opt-in by presence of .pose/docs.json — a project without the manifest
stays valid everywhere, same mechanic as the capability assessment above.
The manifest declares roots (governed doc directories) and entries
(one per doc: path, doc_type — Diátaxis tutorial/howto/reference/
explanation, or a custom value — topics, owns, applies_to,
optional review_after). Each declared doc needs a YAML frontmatter block
with at least title and doc_type. Seven deterministic, offline rules —
missing, undeclared, missing_frontmatter, broken_link,
broken_reference, stale, security — each with a configurable
severity (error/warning/off) in the manifest's severities field;
pose docs-check --explain <rule> documents the rationale. Staleness
compares an entry's own review_after (an absolute date) or, when unset,
the manifest's default_review_days counted from the doc's last touching
commit. The security scan reuses the same deterministic, offline
unsafe-instruction/secret-shaped pattern scan skills already run — defense
in depth, not a substitute for the dedicated gitleaks gate. pose check
--strict incorporates docs-check when the manifest exists (opt-in by
presence, same mechanic as capabilities); errors block, warnings surface
without blocking. Tool MCP: pose_docs_state.
Review-pending triggers (spec pose-docs-assessment-followups, third
consumer of the same post-event hook registry as the capability
reassessment triggers above — reused unmodified): a docs-review
consumer, registered on spec_closeout, resolves which components/files a
closeout reached (components_hit when configured, matched against
owns: entries declared as component:<id>; otherwise the event's
touched files matched against each doc's owns: paths/globs — a
directory prefix like "site" covers every file under it) and marks
every doc whose declared area was reached as review-pending — never
editing the doc itself. Marks accumulate in an append-only log, never
inside the doc's own file, and project a synthetic, owned demand into
pose followups --open (origin docs:<doc-path>), reusing the owner
declared on the manifest entry when present. pose docs-review resolve
closes every mark currently pending on a doc at once, recording the
outcome; docs-check's own output (and pose_docs_state) additively
list what's still pending. Without a component map and without any
owns: declared, the event logs a visible signal instead of marking
anything silently — same degrade-by-absence contract as the capability
triggers, except here the path fallback is the mechanism's full-strength
path (owns: is expressed as paths by default), not a lesser one.
Anti-noise threshold (min_hits, hit level, the demand's default
owner/review SLA) is configurable, sharing the same policy shape as the
capability triggers in its own file (optional; absent means these same
conservative defaults).
Cross-repository portfolio
| Command | Purpose |
|---|---|
pose portfolio-projection [--projects-dir DIR] [--max-staleness-days N] [--json] |
Reconcile dependencies, readiness, ownership and criticality across authorized repositories |
Only repositories registered via HARNE8_PROJECTS_DIR (or explicit
POSE_PROJECT_ROOTS) — the same allowlist the MCP server already uses —
ever enter a projection; nothing is discovered by an open filesystem
walk. Add depends_on: xref:<project_id>/<spec-slug> to a spec to
declare a cross-repository dependency (additive to the existing
other-spec / milestone:... / roadmap:... forms). The projection is
persisted to .pose/reports/portfolio-projection.json, explains every
blocked, stale or unauthorized/unknown cross-reference explicitly, and
tombstones artifacts that disappeared since the last run rather than
silently dropping them. Repositories remain authoritative; the
projection is a reconciled read, never a write back to another
repository.
Harness evidence reconciliation
| Command | Purpose |
|---|---|
pose reconcile-evidence record --run-id ID --request-id ID --execution-id ID --plan-digest SHA --status success\|failure --source harness\|manual [--result-digest SHA] [--allow-supersede] |
Reconcile a Harness execution result into local evidence, identity-bound to the submitting Execution Identity |
pose reconcile-evidence list [--request-id ID] [--json] |
List recorded evidence |
pose reconcile-evidence housekeeping <list-expired\|purge> [--older-than-days N] [--apply] |
Retention for evidence records |
A second record for a request_id that already has evidence is rejected
unless --allow-supersede is passed — and even then the prior record is
never edited or removed, only superseded by a new, explicitly-linked one.
See architecture: Harne8 control-plane composition.
Import existing SDD specs
# Preview every spec-kit feature under the tree without writing files.
pose import spec-kit .specify/specs --dry-run
# Import an OpenSpec capability, specs tree, or change directory.
pose import openspec openspec/changes/add-2fa
The importer is native, deterministic, and offline. It accepts a single
spec.md, a feature/capability directory, or a supported specs tree. spec-kit
imports consume sibling plan.md and tasks.md when available; OpenSpec
change imports consume proposal.md, design.md, tasks.md, and capability
specs below specs/.
Every unit becomes .pose/specs/<slug>/spec.md. POSE validates the complete
batch before writing, never overwrites an existing destination, rejects
symlinks, and reports every source section that still needs human curation.
Use pose lint-spec <slug> --ready-check after reviewing that report. The
first version intentionally does not support force-overwrite, bidirectional
sync, custom spec-kit presets, or OpenSpec schemas outside the documented
behavioral/change layout.
Maintenance
| Command | Purpose |
|---|---|
pose update [--dry-run] |
Migrate the instance contract to the engine version |
pose doctor [--json] [--fix [--yes] [--only <check>]] |
Read-only diagnostics; --fix previews confined remediation, --fix --yes applies and rechecks it |
pose knowledge-housekeeping <op> [--apply] |
List/archive/purge expired knowledge |
pose reports-housekeeping <op> [--apply] |
Same for reports (never touches history/) |
pose hooks <install\|uninstall\|status> |
Git hooks: pre-commit check, post-merge reindex |
pose serve-mcp [--stdio] |
Start the MCP server (unified binary) |
pose version |
Binary version + instance schema version |
Every gate is offline by design — no network calls, stdlib only. A gate observed doing network I/O is a reportable bug (see SECURITY.md).
Release lifecycle
pose release plan --version vX.Y.Z previews a cut. pose release prepare
--version vX.Y.Z --apply freezes selected fragments, canonical notes and a
manifest. check, notes, record, status, open-next and backfill
reconcile the candidate through tagged, published and verified states. The
compatibility alias release-notes --version reads only the prepared snapshot;
use --preview explicitly for the pending queue.