CLI Reference

Use this page when you need a quick map of the OAT CLI rather than the full command-by-command docs. It is intentionally shallow: each section points to the owning page that documents the detailed behavior.

The CLI is also a standalone value path. You can use oat init, oat sync, oat tools, docs commands, repo archive sync, and repo-analysis commands without adopting the full project workflow.

Contents

• CLI Bootstrap - Bootstrap a repo with oat init, guided setup, and initial provider adoption.
• Tool Packs - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
• Config and Local State - Config, backlog, local paths, diagnostics, and related utility commands.
• Remote Project Management - Explicit remote bindings, policy, host handoffs, and recovery.
• Workflow Gates - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
• Docs Tooling Commands - Markdown setup/adoption, framework scaffolding, manifests, and nav sync.
• Provider Sync - Sync behavior, provider capabilities, config, and drift management.
• Agentic Workflows - Tracked project execution, skills, ideas, and workflow routing.
• Workflow & Projects - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
• Repository PR Comment Analysis - Detailed oat repo pr-comments ... behavior.

Full CLI Reference Expansion Path

Keep this page as the command-family map. Fuller command coverage should live either in the owning section for a command family or in generated/semi-generated reference pages that link back here.

Each full command reference should include:

• exact arguments, flags, defaults, aliases, and mutually exclusive options
• output examples, including --json shapes where the CLI supports JSON
• exit behavior for success, validation errors, missing state, and non-interactive blockers
• side effects such as file writes, generated artifacts, config mutations, branch/commit behavior, and network calls
• non-interactive usage guidance, including required flags and scripting-safe forms
• source or test references for behavior that is easy to drift, marking unknown exit-code behavior as unknown instead of inventing a contract

The first practical expansion path is to keep improving the existing owners: Docs App Commands, Provider Interop Commands, Config and Local State, Tool Packs, Workflow & Projects, and Repository PR Comment Analysis.

Exact-path maintenance commits

oat internal commit-paths --identity <operation> --message <message> -- <files...> commits an explicit list of owned files with enabled Git hooks. Include tracked removals and both names of a rename. Directories, untracked missing paths, unmerged entries and paths outside the repository are rejected; the command does not discover ownership or expand directory/glob pathspecs. Unrelated staged entries and worktree bytes remain preserved, including partially staged files. On success, owned index/worktree bytes match the hook-final commit.

Choose a unique identity before the first attempt and retain the identity, message and literal path list for retries. With global --json, outcomes are committed, already-matching, nothing, blocked or failed. Success exits 0, blocked exits 1 and failed exits 2. A blocked result can name a verified commit whose owned-index publication still needs repair; do not claim settlement until a matching retry succeeds. Ignored receipts under the Git directory verify the exact identity, commit, tree and paths before reuse. Lock inspection/retry is bounded and never deletes another writer's lock.

If the command is unavailable, stop and update the CLI; there is no broad Git commit fallback. Synced project artifacts still use oat project push after successful scope resolution. During development, run the current source entry:

pnpm --silent run cli -- internal commit-paths --identity "$COMMIT_IDENTITY" --message "$COMMIT_MESSAGE" -- "${OWNED_FILES[@]}"

A dist invocation requires a fresh build after the latest CLI source changes.

For oat backlog archive --json, use the complete returned affectedPaths array as the archive-owned list, converting absolute paths to literal repository-relative files against the same repository root. Union per-item results, append an owned handoff's filesystem deletion, and format only existing supported text with the repository command before the helper commit. Include both old/new item paths and every ledger/index/reference output; never stage only the old missing name. A settled noop may return no paths and needs no commit. Pending Git retries include prior outputs only with HEAD ownership evidence, while no-Git retries report current-pass mutations. See Backlog Lifecycle.

Command Groups

Notable commands introduced in the current CLI surface:

• oat project new <slug> [--mode spec-driven|quick|import|lite|brief|goal] --scope shared|local|synced [--force] - create a project in an explicit scope. --mode selects the workflow mode and therefore which artifacts are scaffolded; it defaults to spec-driven. Use quick for a bounded feature with clear requirements, import to normalize an externally authored plan, lite for a single-sitting change that scaffolds only plan.md, state.md, and implementation.md, and brief for one delivery planned as a Project Brief, which scaffolds the plan-brief and implementation-brief templates plus references/research/, and goal for an outcome delivered in milestones, which scaffolds the same files with oat_plan_source: goal and the canonical | Milestone | Phases | table header. Start brief and goal projects with oat-project-brief or oat-project-goal, which run this command themselves. See Lifecycle for the per-lane flow. Without --scope, creation uses projects.defaultScope, which defaults to synced. Project slugs are unique across all scopes by default, including recorded or remotely published synced projects. --force deliberately permits a duplicate; use an explicit project path with project open or project pause whenever a slug is ambiguous across scopes.
• oat project scope [project] --format value|json - resolve a project's storage scope without inspecting its path manually.
• oat project push [project] [--message <message>] - commit pending synced artifacts, reconcile with the exact project ref on origin, publish it, and refresh an open PR's artifact-links block. Use --no-refresh-pr to skip the PR edit. With --json, success returns status (pushed or up-to-date), the full project-ref sha, the retained ref, and optional prRefresh; conflict and rejected outcomes return their corresponding status and exit nonzero.
• oat project pull [project] [--no-commit] - fetch and materialize or update a synced checkout. Resolve a rebase conflict and run pull --continue, or use pull --abort to return to the pre-pull state. Coordination children are pulled by default; --no-children limits the operation to the selected project. When pull adopts a remote project with no local discovery record, --no-commit leaves the new record uncommitted for the caller to persist. With --json, the receipt includes status, sha, and ref, plus conflicts when applicable and per-child results when coordination children were requested. A project whose authoritative ref is refs/oat/completed/<project> is terminal and cannot be pulled or opened. A same-SHA refs/oat/projects/<project> ref is only an inert alias; differing active and completed SHAs are reported as a terminal mismatch that must be repaired before lifecycle work continues.
• oat project links [project] --format markdown|json - render SHA-pinned links for the linkable artifacts on the project ref. On GitHub origins the artifacts become full-SHA blob links; other hosts degrade to the retained ref and short SHA without guessing a web URL. --durable-summary <path> accepts only a path contained in the repository, normalizes it repository-relative, and renders it as a code span rather than a guessed remote link. Completed projects resolve through refs/oat/completed/<project> while the rendered artifact URLs remain pinned to the verified full source SHA.
• oat project pause [project] - persist the pause state and clear the active project pointer. If synced publication is declined or fails after the pause commit is created, that clean commit is retained; address the publication failure and rerun pause to publish it.
• oat project prune [project] [--force] [--no-commit] - remove every checkout, the local and remote project refs, and the tracked record. When the project is omitted, the active project is used. This is the explicit destructive operation; --force may discard dirty or unpushed artifacts, while --no-commit leaves the parent-record deletion for a library caller to commit. If remote deletion succeeds but local checkout removal fails, the local ref, record, and checkouts are retained. Resolve the reported local obstruction and retry prune --force; do not run project push, which would republish the deleted remote ref. For a completed project, explicit prune deletes the completed ref and any same-SHA active alias but preserves durable local and S3 archive snapshots. A differing-SHA terminal mismatch blocks prune and retains both refs.
• oat project migrate <path> --to synced [--no-commit] - migrate an existing shared project to synced storage while preserving its artifacts and retargeting the active project pointer. --no-commit leaves the parent record and source-tree transition uncommitted for a library caller.
• oat project list --scope shared|local|synced - filter tracked projects by scope. Add --remote to discover project refs that do not yet have a local record or checkout, and --include-coordination to include coordination parents. A malformed discovery record with no materialized checkout appears as a recorded-invalid row. When the checkout is materialized, its existing row instead carries the restore hint and recordError parse diagnostic in --json output. Fully retired completed refs and same-SHA active aliases are omitted from active discovery. A differing-SHA active/completed pair appears as a terminal-invalid row with a recovery diagnosis. When reconciling a local synced record or checkout, only a verified missing refs/oat/completed/<project> result counts as absence. Transport, authentication, and other lookup failures fail the command closed; they are never converted into a recorded-absent row or pull guidance.
• oat tools guidance - print the managed OAT tools AGENTS.md block for the currently installed packs without installing, upgrading, or writing anything; --json returns status, sectionKey, target, packs, otherProjectSkills, and managedBlock. See Tool Packs.
• oat tools migrate --pack <pack> --from <scope> --to <scope> - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. --dry-run stops after the preview; there is no force flag. See Tool Packs.
• oat pjm doctor --json - read-only repository PJM diagnostics whose result carries an additive adoption object (state of declared | inferred-legacy | partial-initialization | none, repoRoot, and recovery). This, not oat tools has project-management, is the check that answers whether this repository adopted PJM.
• oat pjm remote ... --json - operate one explicit provider-neutral binding. The family includes intake, publish, refresh, reconcile, closeout, discussion, resolve, doctor, migrate, storage, and operation continue. An ok envelope exits 0, a system failed envelope exits 2, and every safely persisted nonterminal or blocked status exits 1. A pending envelope with externalAction is a durable host handoff, not remote success.
• oat config dump --json - merged config with source attribution
• oat project status --json - full parsed state for the active tracked project. Stable contract for skills: the JSON output is a typed read interface for OAT skills; the fields that OAT skills read from it are pinned by a contract test in the OAT source repository. Removing or renaming any of project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl} is a breaking change and fails that test.
• oat project status --field <path> - print one arbitrary dot-path field from the same status payload, e.g. project.workflowMode or project.timestamps.stateUpdated. Missing/null fields print null; object and array fields print compact JSON.
• oat project status --project-path <path> - read from a repo-relative or absolute project path instead of .oat/config.local.json's active project pointer. Combine it with --field or --shell when a skill has already resolved the target project path.
• oat project status --shell NAME=path ... - print shell-safe assignments for one or more fields from one status read, e.g. WORKFLOW_MODE='quick'. This is the preferred multi-field read API for skills. See Writing Skills → Reading project state for examples and the npx-backed oat shim contract.
• oat project promote <project-path> --to quick [--json] - promote an authored lite, brief, or settled goal project to quick mode. For a lite project, the command derives discovery.md from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as references/lite-plan.md; and scaffolds a fresh quick plan.md. For a brief project, it migrates each phase by state: accepted phases keep their completed execution records as quick tasks or get one synthesized Accepted via phase evidence task against the phase's **Head:**, active phases keep their completed records, and pending or provisional phases stay taskless and are listed in oat_promotion_pending_phases (quick plan readiness stays false until that list is empty); it renders the brief's sections into discovery.md, archives the original as references/brief-archive.md, and sets oat_promoted_from to the source mode (brief, or goal for a goal project). There is no reverse direction. A goal project promotes like a brief, but only at a settled delivery boundary: the active milestone is delivered, every oat_deliveries entry is at_endpoint or superseded, and no oat_goal_recovery is pending; otherwise it refuses with goal-milestone-active, goal-recovery-pending, or goal-delivery-unsettled (with a deliveries array naming the unsettled entries; an empty registry is also unsettled), and its archive appends the delivery history after the original brief. It refuses unsupported targets, projects that are neither lite, brief, nor goal, unreadable projects, an existing lite-plan reference, invalid authored sections, an existing brief archive (brief-archive-exists), an extracted journal phase (extracted-phases), a brief with no parseable phases (invalid-brief-plan), an accepted brief phase with no completed record and no **Head:** anchor (missing-phase-head), unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is { status: "promoted" | "refused", reason, files }, plus an optional phases array naming the refused phases when reason is missing-phase-head; reason is the stable categorical contract and refused results exit non-zero.
• oat template resolve <name> [--output <path>] [--json] - resolve a template in repository (<repo>/.oat/templates/), user (~/.oat/templates/), then bundled order and report name, found, tier (repository | user | bundle), and path. path is set only for the repository and user tiers; it is null for the bundled tier, so callers never depend on a package-manager path. <name> accepts plan or plan.md and rejects path separators and ... --output <path> copies the resolved content to that file, replacing an existing file, and does not create missing parent directories; JSON output adds the absolute output path. A template missing from every tier exits 1 with found: false. Lifecycle skills use --output to copy their artifact templates, so a user-scope-only install works without a repository .oat/templates/ directory.
• oat review latest --json - find the newest review artifact by oat_generated_at, scanning the active or specified project's reviews/ and reviews/archived/ directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (final > higher phase/task > lower phase/task). The JSON contract returns path, scope, generatedAt, kind (project or adhoc), archived, and actionable, with null values when no review exists. Archived project reviews remain discoverable as history but return actionable: false.
• oat project list --json - summary state for tracked projects under the configured projects root
• oat project closeout-check <project-path> [--autonomous] [--json] - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its oat_post_implement_sequence snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached status: complete. A snapshot is required when the effective layered workflow.postImplementSequence is configured, when the closeout is autonomous (--autonomous, or OAT_AUTONOMOUS=1 in the environment even without the flag), or when oat_workflow_mode is lite. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports status (complete, not_required, or incomplete), the missing invariant (snapshot_missing, snapshot_malformed, sequence_failed, pre_approval_step_pending, approval_pending, post_approval_step_pending, or sequence_not_complete), route (oat-project-implement when incomplete), nextOwner (the next stored step and its skill, or the approval), and the evaluated inputs. An incomplete or malformed result exits 1. For a goal project (oat_workflow_mode: goal) the goal boundary is checked first and read-only: it requires oat_goal_status: declared_met, a valid exhaustive oat_goal_outcome_audit, resolved extractions, a successful gh pr view observation of every terminal delivery member, and delivery coverage of every accepted phase (each in a terminal delivery's effective scope with a passed, fresh integrated review and its persisted exit_gate); refusals report goal_inputs_unreadable, goal_not_declared, goal_audit_invalid, goal_extraction_unresolved, goal_observation_failed, or goal_coverage_incomplete, and nextOwner is { kind: "goal", skill, reasons }, where each reason is { code, message, subject? } and skill is the owner of the first reason: for example not-declared and audit-invalid route to oat-project-goal, review-not-fresh to oat-project-review-provide, exit-carrier-not-fresh to oat-project-implement, delivery and endpoint reasons such as endpoint-unmet to oat-project-pr-progress, and phase-uncovered to oat-project-pr-final. A goal snapshot may record its pr step as satisfied by delivery coverage (satisfied_by: { pr: delivery-coverage }) only once pr is in the completed prefix.
• oat project delivery refresh --project <path> [--json] - goal only. Observes every registered delivery member with gh pr view <url> --json state,headRefOid,baseRefOid and persists, in state.md, only the observations (observed_head, observed_base, member status), the delivery status (open or at_endpoint), the first observed endpoint_attainment, and derived staleness (integrated_review.disposition: stale, the milestone exit carrier's freshness: stale with freshness_reason). It never rewrites a reviewed revision, a member base, or the first endpoint attainment, never writes oat_milestone_status or oat_goal_recovery, and never manufactures a passed review or a fresh carrier. oat-project-pr-progress and oat-project-goal run it before registration and re-alignment.
• oat project delivery check --project <path> --subject <mNN|dNN> [--json] - goal only, read-only. Reports whether a milestone (before registration, against the branch head) or a registered delivery (against its observed member revisions) is deliverable: a passed integrated review that is still fresh under the bookkeeping-successor rule and an allowed, fresh milestone exit carrier (reported as exit.source: milestone-carrier; the closeout boundary judges each delivery's persisted exit_gate instead). Evidence reviewed at R covers a later head only when every intervening commit changes permitted bookkeeping in this project's tracking files (state.md, plan.md, implementation.md, project-log.md, summary.md) and review artifacts (including those of deliveries sharing the same member pull request); any change to summary.md is bookkeeping because it is derived memory, never the authority for the brief's content; code changes, edits to approved brief content, and a substantive change followed by its revert fail. JSON output carries status (ok or undeliverable), the subject, its ordered scope, publishedHeads, review, exit, and deliverable; an undeliverable subject exits 1 with the full report. A stale review or exit result carries a reason that starts with a code, such as review-missing, review-scope-narrow, member-unobserved, base-changed, bound-revision-mismatch (a bound revision differs from its member's set-once reviewed_head), subject-changed, configuration-changed, or a bookkeeping-successor failure: missing-revision, missing-object, not-ancestor, inspection-failed, disallowed-path, or substantive-change.
• oat project complete-state <project-path> [--archived] [--autonomous] - apply the canonical completed-state mutation to a project's state.md; used by oat-project-complete during lifecycle closeout. It first evaluates the same closeout invariant as oat project closeout-check and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running oat-project-implement, which persists the snapshot (completion-and-closeout.md Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before. A goal project is also refused, without writing, by the goal boundary that closeout-check describes. When the project has an implementation.md, complete-state then runs the final journal evaluator (oat project journal check --at completion) on the same bytes immediately before its write, and refuses with the evaluator's reasons, writing nothing, when the journal does not hold its terminal shape; an override line covers only its eligible gap and never the closeout invariant. A project with a plan.md but no implementation.md is refused with journal-missing; only a plan-less project completes on the closeout invariant alone.
• oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit] [--new-generation <reason>] - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a project-recap run inside the project's explainers/ directory. Archive verifies the complete selected package and every immutable file byte, then atomically exports one self-contained .oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>.html page before deleting the active project. The full original package remains in the archived project. JSON projectRecapExport identifies runId, page.sourceRelativePath, page.originalSha256, page.exportedSha256, verifiedArtifactCount, and the flat exportRoot. No tracked sidecar is created. Matching dated pages are adopted on retry; conflicting destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. Summary and PR links point to the tracked page. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes refs/oat/completed/<project> authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With --json, the terminal receipt reports completedRef, verifiedSourceSha, whether activeAliasDisposition was retained or removed, whether recordRetired completed, and the parent lifecycleCommit. --no-commit is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves lifecycleCommit null. Never pass it through oat-project-complete, which requires that receipt. Retry identity: one read-only evaluator, shared by apply and --dry-run, resolves the archive before any write. An identical retry (the project's retained-artifact manifest matches exactly one same-scope archive) reuses that snapshot's local path, dated export identity (summary export file and S3 key) and receipt on any later date, and a source-absent retry resumes the single same-scope archive; changed content, several matching archives, or an unverifiable non-empty directory at the archive path refuse before export, copy, overwrite or S3 upload, with follow-up-project guidance. The dry-run reports the identity the apply would use. .oat-archive-source.json records manifestHash and generation beside the project name, scope, snapshot and synced source SHA. The exported summary rewrites oat-project:<project>#<entry-id> locators to oat-archive:<snapshot>#<entry-id> and turns relative project-log.md or oat-execution-learnings.md links into plain text; see Archive identity. --new-generation <reason> archives reopened work of a shared or local project as the next generation instead of refusing it: it requires a non-empty single-line reason and exactly one latest generation of the same project and scope as predecessor (otherwise it refuses), never overwrites that predecessor, and persists the new generation (<project>-gN locally, <YYYYMMDD>-<project>-gN as export identity; when the same project's archive from another scope already holds that path or identity, both carry the scope: <project>-gN-<scope> and <YYYYMMDD>-<project>-gN-<scope>) with its predecessor, reason and generationRequest id before any export, copy or S3 side effect, so a retry reuses it. Replaying the same predecessor and content resolves to the same generation; synced projects refuse the option. JSON adds generation and predecessorSnapshot, and --dry-run reports the proposed generation without writing it.
• oat repo archive sync [project-name] - hydrate archived project snapshots from the configured repo-scoped S3 archive into .oat/projects/archived/. A name resolves as an exact snapshot, then a full generation name such as demo-g2, then the project (or <project>-<scope> family), restoring its latest generation and then its latest date; see Project Artifacts for the <project>[-gN][-<scope>] naming contract. The old oat project archive sync path remains as a deprecated shim.
• oat project dispatch record --event-file <json-file-or-dash> - validate one generic dispatch record plus its namespaced OAT evidence event and print the result with status: validated-only. The command writes nothing; launches are recorded in the calling workflow's run record. Managed, effort-pinned Claude launches run it before launch: the input carries claudeLaunch with the real resolver result, generated definition, and proposed payload, plus recordBase and event. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into recordBase. One validation run reports every violation across claudeLaunch, recordBase, and event in a single error message, one stage path: message line each; the recordBase cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at .agents/skills/oat-dispatch-subagents/references/managed-claude-example.json. The command validates evidence only — it never launches a provider. A runtime-observation event may carry either a finished observation or the provider metadata envelope (provider, observedAt, entries) to normalize, but not both. entries may be raw provider output: they are projected through the owning parser's allowlist, are never echoed in the output, and both forms have their match derived from the record's configured invocation rather than trusted from the caller, with the observation's provider bound to the record's. With --json, the result adds runtimeIdentity with separate configured and observed objects plus a match of matching, mismatching, not-comparable, or null; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See Evidence Layers.
• oat project dispatch record --event-file <json-file-or-dash> --format line [--dispatch-stamp <line>] - print the one-line journal run record for the same validated, redacted record and event (projection run/v1), and write nothing; standard input still works. The line is run/v1 followed by named fields in a fixed order, joined by a space-padded ·: request, scope, action, role, configured target, model and effort, stamp (the formal Dispatch: stamp passed verbatim through --dispatch-stamp; a stamp without the canonical prefix is refused), launch (planned, accepted, or blocked-before-start), the raw child outcome, terminal (yes or no) and its class (completed, terminal-stop, blocked-before-start, live, or unrecognized), continuation references, and the optional observed identity with its match, which never replaces the configured fields. Inside a value, \\ is a literal backslash and \·, \~, \n, and \r escape the delimiter, a tilde, a newline, and a carriage return; a bare ~ is null. Terminality comes from one producer-to-outcome mapping: a successful completion (completed, DONE, DONE_WITH_CONCERNS), a terminal stop (BLOCKED, failed, cancelled, INVALID_RUN_ABORT) and blocked-before-start are terminal; planned, running, pending, and NEEDS_CONTEXT with its handle still open are not, and an outcome outside the mapping is unrecognized, never success. The owning skill writes one line per request id under ## Orchestration Runs and updates it in place. --json keeps status: validated-only, the record and runtimeIdentity, and adds runLine (version, line, fields, classification, terminal).
• oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json] - resolve a canonical role through the loaded, user ($HOME/.agents), and project (<repo>/.agents) tiers and print the canonical-role-resolution event that oat project dispatch record accepts unchanged: redacted canonicalPath and selectedPath in the form <loaded|user|project>/agents/<name>.md, the role's contentDigest, and candidateMisses. --skill-dir is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints missing evidence with its recovery commands. Read-only; the dependency is the workflows pack.
• oat project validate-plan --project-path <path> - validates oat_plan_parallel_groups metadata in plan.md; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a manual: instruction. Brief plans (oat_workflow_mode: brief) are validated with the brief profile: phases need non-empty **Intent:** and **Exit evidence:**, a **Provisional:** value of yes or no, unique IDs, and a concrete first phase; ### Task headings in a brief are reported as a warning, and taskless parallel groups are valid. Goal plans add the goal profile: oat_plan_source: goal, a valid ## Milestones table (goal-milestones-missing, goal-milestones-malformed, goal-duplicate-milestone, goal-milestone-empty, goal-milestone-unknown-phase, goal-phase-in-multiple-milestones, goal-phase-without-milestone), no parallel group spanning milestones (goal-group-crosses-milestone), canonical persisted phase IDs (goal-noncanonical-phase-id), and no change to a shipped milestone or a registered delivery's frozen scope (goal-shipped-milestone-changed, goal-delivered-scope-changed); phases the journal marks extracted need no milestone. See Implementation Execution.
• oat project journal check --at <implement-preflight|review|completion> [--project <path>] [--scope pNN[,pNN]] [--json] - read-only journal evaluator: it reads plan.md, implementation.md, and state.md and writes nothing. implement-preflight is implement's call before its Step 16: it validates the accepted task and phase evidence while the terminal headers and pointers Step 16 owns may still be unwritten. review requires an explicit --scope of phases the plan declares and ignores future phases; a live run line warns there instead of refusing. completion (oat-project-complete, before roll-up, seal, or any lifecycle write) also requires the terminal journal shape: journal oat_status: complete and a cleared oat_current_task_id, state.md oat_phase_status complete or pr_open and a cleared oat_current_task. Task modes read journal records through the shared heading-only reader (fenced and indented code excluded, a block ends at the next heading of equal or higher level): every plan task heading is unique and sits under its own phase (plan-task-duplicate, plan-task-misplaced, routed to the plan owner and never override-eligible), and every plan task has exactly one journal block in its phase with exactly one owned **Status:** completed and one owned **Commit:** SHA; tables and checklists are never completion evidence, and overview totals must match. Brief and goal read phase units: an accepted phase carries its **Head:**, execution records close as completed with a commit or as failed, cancelled, or no-change without one, an extracted goal phase and a phase the goal outcome audit defers or retires stay valid and incomplete. Everywhere: ## References is last, review receipts sit in their phase or ## Reviews and Gates, deferrals in ## Deferred Findings, dispatch payloads are refused unless marked quoted-evidence, every run line parses as run/v1 under ## Orchestration Runs, carries a valid request identifier, and is terminal at implement-preflight and completion, and no template placeholder survives, including one left in an inline-code slot such as - `{path}` - … unless the line is marked quoted-evidence. An override is one line under ## Deviations from Plan / Design: **Override:** <scope-disposition-approved|evidence-lost|operator-accepted-gap> · **Authorized by:** <decision id> · **Scope:** <pNN-tNN|pNN> · <reason>; it covers only a missing task block, an incomplete task, missing commit evidence, or (for scope-disposition-approved) an unaccepted phase within its scope, and a malformed or misplaced override is refused. Output is { status: ok | refused, reasons: [{ code, path, line, owner, message }], warnings, overrides }; a refusal exits 1. Delivery coverage and the post-implementation sequence stay with closeout-check.
• oat project log append|check|synthesize|rollup - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into summary.md plus the configured repository ledger. See Project Log.
• oat project log append --category <category> --source <id> [--origin <producer>] - record a learning on a judgment entry. The category is one of gotcha, efficiency, documentation-gap, candidate-skill-content, decision, or environment-limited; any other value, --category without --source, a --source containing whitespace, and these flags on a --structural entry are refused. The flags write a **Category:**, **Source:**, **Origin:**, **Recorded:** body head above the body; the heading grammar is unchanged and an entry without them is stored as before. Passing the source id as --idempotency-key makes a retry report already-appended and write nothing.
• oat project log check - JSON adds learnings: legacy when the project still has oat-execution-learnings.md, which summary and retro read after the log, and none otherwise, in every status.
• oat project log rollup [--json] - writes a bounded Workflow Observations digest, not a copy: judgment entries only (structural entries are counted, never rendered), newest first with decision and gotcha ahead, capped by workflow.projectLogDigest.maxEntries and .maxLines with an omitted-count trailer, one concise item per entry carrying the non-link locator oat-project:<slug>#<entry-id>, and live project paths labelled. summarySection is written, updated, or omitted (no judgment entry: an existing section is removed and none is created). entriesRolledUp counts every entry read. JSON adds digest with the bounds, rendered, omitted (overBound, structural, malformed), the over-bound omittedEntries tokens and byProducer counts. Ledger graduation still reads the complete judgment set.
• oat project set-mode — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the --json contract.
• oat gate review <prompt...> - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. --timeout-ms <milliseconds> overrides target, workflow.gateTimeouts, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews and artifact reviews default to 30 minutes, while task code reviews default to 15 minutes. With --json, the result envelope on exit is the canonical completion signal: status is ok | blocked | review_failed | artifact_missing | artifact_validation_failed | targeting_correlation_failed, alongside runId, generatedAt, and artifactPath when available. artifact_missing means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For targeting_correlation_failed, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For artifact_validation_failed, correct the artifact and rerun the gate until it revalidates as ok or blocked. Invoke oat-project-review-receive only when all three conditions hold: status is ok or blocked, receiveEligible is true, and handoff is non-null. review_failed may include structured refusal, noOutputProduced, and metadata-only activityEvidence; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary ok or blocked envelope with additive lateCompletion: true. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary ok or blocked envelope with additive postSelectionRecovery: true; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, review_failed names the failing sub-step in postSelection.step and its cause in postSelection.code. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain targeting_correlation_failed and receiveEligible: false. Orchestrators should read the structured result rather than poll the filesystem. See Workflow Gates.
• oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json - return the headless child route (inline, delegate-sync, or refuse) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
• oat gate exec <prompt...> / oat gate cross-provider-exec <prompt...> - run a generic target prompt. --timeout-ms uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
• oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default> - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
• oat gate target set <id> --timeout-ms <milliseconds> - persist a validated per-target gate budget.
• oat gate target list --json - inspect resolved gate targets without selecting or executing a reviewer. Each entry reports its config origin, whether it is explicitly configured and enabled, current availability, and normalized configured invocation values (unknown when omitted).
• oat gate cross-provider-exec <prompt...> - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
• oat instructions sync [--dry-run] [--strategy none|pointer|symlink|copy] - apply the effective CLAUDE.md strategy (--strategy, else instructions.claude.shims, else none). Under the default none it removes the CLAUDE.md shims OAT created — none at all while any CLAUDE.md has content of its own — keeps and reports every other CLAUDE.md, and warns about any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md that would make Claude Code ignore AGENTS.md. oat instructions validate checks the same strategy read-only. See Instruction Sync.

oat config surface flags

oat config set and oat config unset support the same mutually exclusive surface flags, which control the config file the write or removal lands in:

• --shared — write to or remove from .oat/config.json (committed team repo settings)
• --local — write to or remove from .oat/config.local.json (per-developer repo state, gitignored)
• --user — write to or remove from ~/.oat/config.json (user-level fallback, applies across all repos)

When no flag is passed, the CLI picks a sensible default per key type: structural keys (projects.root, documentation.*, etc.) go to shared, state keys (activeProject, etc.) go to local, workflow preferences (workflow.*) go to local. Pass at most one flag — the command rejects multiple surface flags.

Per-key restrictions apply identically to set and unset: structural keys can only be written at shared scope, most state keys can only be written at local scope (activeIdea is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy autoReviewAtCheckpoints remains shared-only; prefer workflow.autoReviewAtHillCheckpoints.

oat config unset <key> removes the key from the selected surface and prunes any parent object it empties, so the resolved value falls back through the remaining surfaces to the built-in default. Removing a key the surface does not hold is not an error: it reports an already-unset outcome and exits 0. With --json the envelope adds a removed boolean, which is the machine-readable way to tell a real removal from an already-unset no-op, since both exit 0. A stored value that fails validation is still removed, matching oat config set, which repairs the same file.

Remote settings under pjm.remote.* remain shared-only. Removing a mutable leaf preserves sibling settings and the required empty policy object, if necessary, so the remaining remote configuration stays readable. Explicit defaults are removed from disk rather than silently written back by normalization; effective values still use fail-closed defaults. Remote policy must pass strict validation before removal.

unset refuses six classes of key, each with exit code 1:

• Unknown keys, including keys OAT reads but does not expose in the oat config catalog (documentation.index). These are not removable by any oat config command.
• Lifecycle state (activeProject, lastPausedProject) — cleared with oat config set <key> '' instead.
• Pack intent (tools.*) — removed with oat tools remove --pack <pack> --scope project, which also removes the installed pack files. Clearing the intent alone would leave them behind.
• Aggregate read views (workflow.dispatchCeiling, workflow.dispatchCeiling.providers) — these are assembled for get from the leaf keys and are not stored as such. Unset workflow.dispatchCeiling.preset or workflow.dispatchCeiling.providers.<provider> instead.
• Read-only remote-policy structure (pjm.remote, pjm.remote.policy, pjm.remote.schemaVersion) — unset a documented mutable child key instead; removing the complete policy or its schema discriminator is not supported.
• Environment-shadowed keys with nothing stored on the target surface — when OAT_PROJECTS_ROOT, OAT_PROJECTS_DEFAULT_SCOPE, or OAT_WORKTREES_ROOT supplies the effective value and the surface holds nothing to remove, clear the environment variable in your shell. When the surface does hold a stored value, unset removes it (as set would rewrite it) and warns that the override still supplies the effective value.

workflow.* preference keys

The workflow.* namespace holds user-facing workflow preferences that let you answer repetitive confirmation prompts once and have OAT skills respect the answer automatically. Common keys:

• workflow.hillCheckpointDefault (every | final) — default HiLL checkpoint behavior in oat-project-implement
• workflow.archiveOnComplete (boolean) — skip the archive prompt in oat-project-complete
• workflow.createPrOnComplete (boolean) — skip the "Open a PR?" prompt in oat-project-complete
• workflow.autonomousComplete (boolean, default false) — standing opt-in for the non-interactive oat-project-complete-auto companion; when false it stops with "interactive completion required"
• workflow.postImplementSequence (legacy wait | summary | pr | docs-pr, or structured {preApproval, postApproval} arrays) — approval-aware post-implementation chaining
• workflow.reviewExecutionModel (subagent | inline | fresh-session) — default final-review execution model
• workflow.autoReviewAtHillCheckpoints (boolean) — auto-run the extra lifecycle review at HiLL checkpoints
• workflow.autoNarrowReReviewScope (boolean, default true) — automatically narrow re-reviews to the guarded range after the prior matching review's recorded head; set false to use the nominal full scope
• workflow.autoArtifactReview.plan (boolean, default true) — auto-run the bounded plan.md artifact-review loop before implementation handoff
• workflow.autoArtifactReview.analysis (boolean, default true) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
• workflow.gateTimeouts.code / workflow.gateTimeouts.artifact (integer milliseconds from 1,000–14,400,000) — review-type budget defaults below CLI and target overrides

These workflow keys resolve through config files and defaults (local > shared > user > default). Some config keys have explicit environment aliases, but workflow.autoArtifactReview.plan and workflow.autoArtifactReview.analysis do not. See Workflow preferences in the Configuration guide for full descriptions, surface guidance, and cross-repo foot-gun examples.