Anuva CLI
The Anuva CLI is a narrow Bun/TypeScript executable owned by Product Main. It uses Commander.js for the command tree, the Linear TypeScript SDK for Linear, GitHub CLI for pull requests/checks/merge, and Google zx behind a typed process adapter.
The Anuva Development Process Policy
defines the packaged, versioned CLI with atomic upgrade and rollback. Machine
one currently runs accepted clean build 0.2.1-g2fecf51439fc with
0.2.1-g3dd30bca40f1 as its verified previous target. The original
checksum-manifested legacy-source artifact remains installed.
Installation and machine configuration
From anuva-main-video-creator, install the pinned dependencies and run the
repository-local executable:
Build a local Windows x64 artifact and run the complete source and packaged checks:
The ignored artifact directory contains anuva.exe and artifact.json with
semantic version, full source commit, dirty state, platform, architecture, byte
count, and SHA-256. A clean committed build reports:
The replacement installer writes a stable
%LOCALAPPDATA%\Anuva\bin\anuva.cmd and side-by-side versions under
%LOCALAPPDATA%\Anuva\cli\versions. It contains no Product Main path,
preserves the caller's working directory, arguments, and exit code, validates
the artifact before switching the atomic current pointer, retains previous,
and is idempotent for identical bytes. On the first packaged installation it
also validates and preserves the Phase 1 launcher under
cli\legacy-source, records its checksum in a closed manifest, and records
previous=legacy-source.
Do not run the live installer merely because an artifact exists. The Phase 2 plan requires a preview of the exact clean artifact, checksum, pointer change, toolchain actions, and rollback command followed by separate approval.
Copy config/development.example.yaml to
%APPDATA%\Anuva\development.yaml, then set the machine name, repository paths,
review URLs, Unity executable, and tunnel token-file path. The file is validated
before an operation runs. It must not contain API keys, token values, database
credentials, or other secrets. Store LINEAR_API_KEY in the Windows user
environment, reopen Codex so it inherits the variable, and authenticate GitHub
separately with gh auth login. See the
Linear API key setup
for persistent and current-process commands plus non-secret verification.
Machine two uses config/development.machine2.example.yaml, which already
fixes its machine identity, repository registry, ports, hostname suffixes,
tunnel name, and token filename. Follow the
Windows Development Machine Bootstrap;
do not copy another machine's raw config, plugin cache, CLI installation,
working tree, or credentials.
On a clean machine, preview and separately approve
scripts/install-anuva-source-launcher.ps1 before the first packaged
installation. It creates only the fixed source launcher that the existing
installer preserves as previous=legacy-source; it does not update PATH or
accept an arbitrary source path.
Product Main also owns config/codex/default.rules. bun run check:rules
validates its direct and wrapped command matrix without installing it.
scripts/install-codex-rules.ps1 is a separate fixed-purpose machine policy
transaction: it accepts only that tracked file, requires the dry-run's active
checksum for confirmation, and supports checksum-backed rollback and inverse
rollback. Restart Codex after each confirmed active-rule change.
Repository-aware operations accept only the fixed Product Main, Bento, CMS,
Python, and Unity keys. anuva-bento uses local docs port 4005, machine-one
preview https://bento1.girishd.com, and publisher folder anuva-bento;
arbitrary repository strings remain invalid.
Windows GitHub CLI credentials can be valid in the user keyring while unavailable
inside a managed sandbox. In that case, doctor reports that credentials are
unavailable in the current execution context instead of declaring the account
unauthenticated. Retry gh auth status with scoped sandbox escalation; if it
succeeds, run the GitHub-backed Anuva command in that approved context. Run
gh auth login only if the keyring-capable check also fails. See
GitHub CLI authentication.
Use --config <absolute-path> to validate or run against another configuration.
Runtime process state is stored under %LOCALAPPDATA%\Anuva\state; receipts and
redacted logs are stored under %LOCALAPPDATA%\Anuva\logs.
Command catalog
The implementation plan may refine option names, but it must preserve these named capabilities and must not add a generic command runner.
Diagnostics and context
anuva doctor [--json]
anuva cli status [--json]
anuva cli rollback --dry-run
anuva cli rollback --confirm
anuva toolchain doctor --json
anuva toolchain snapshot --json
anuva toolchain bootstrap --dry-run
anuva toolchain bootstrap --confirm
anuva skills validate --json
anuva skills cachebuster --label <label> --dry-run
anuva skills cachebuster --label <label> --confirm
anuva context show [--json]
cli rollback accepts no build or path input and can swap only the validated
current and previous targets. A target is either a contained packaged build
identifier or the one literal legacy-source; the latter resolves only to the
preserved fixed launcher and checksum manifest. toolchain bootstrap accepts
no tool, package, URL, command, or path input and maps the bundled manifest to
fixed adapters. skills validate uses bundled JavaScript YAML parsing and
performs no Python invocation or temporary dependency installation.
Linear
anuva linear issue get <issue-id> [--json]
anuva linear issue list-ready --repository <name|current> [--json]
anuva linear change create-implementation-issues <manifest> --dry-run
anuva linear change create-implementation-issues <manifest> --confirm
anuva linear change start <change-id> --dry-run
anuva linear change start <change-id> --confirm
anuva linear issue start <issue-id> --confirm
anuva linear issue submit <issue-id> --pr <url> --confirm
anuva linear issue complete <issue-id> --report <path> --confirm
anuva linear change complete <change-id> --review <path> --confirm
linear issue complete remains available for recovery compatibility after an
already-merged PR. Normal review workflows use pr merge --report, whose retry
path safely completes Linear after a partial failure.
Git and GitHub
anuva work start <issue-id> --dry-run
anuva work start <issue-id> --confirm
anuva work change start <change-id> --phase <planning|decision|completion> --confirm
anuva pr create <issue-id> --draft --dry-run
anuva pr create <issue-id> --draft --confirm
anuva pr ready <issue-id|pr-url> --confirm
anuva pr inspect <issue-id|pr-url> [--json]
anuva pr checks <issue-id|pr-url> [--json]
anuva pr merge <child-id> --report <absolute CompletionReport.md> --confirm
anuva pr change create <change-id> --phase <planning|decision|completion> --draft --confirm
anuva pr change ready <change-id> --phase <planning|decision|completion> --confirm
anuva pr change merge <change-id> --phase <planning|decision|completion> --confirm
Phase 4 adds no CLI command. Issue-free routine, material, and
development-process skills use bounded codex/ branches and scoped local Git
plus the connected GitHub capability, with gh only for connector gaps. Named
Anuva operations remain mandatory for Linear-backed work, documentation
processes, fixed machine operations, and every side effect already implemented
by the allowlisted CLI.
work start is child-specific: it creates a validated
codex/<issue-id>-<slug> branch and moves a Ready implementation child to In
Progress as one idempotent user-level operation. Standalone intake creates its
issue directly In Progress and reconciles the same branch form through
repository-change start.
Product Main uses distinct planning, mid-change decision, and completion branches and managed PR links. A decision phase requires the managed planning PR to be merged, does not require terminal children, records one post-planning gate such as proceed/revise/stop, and never starts children automatically. Completion requires all children to be terminal. All Product Main phase PR operations leave the parent In Progress.
Child pr merge validates the absolute report and clean worktree, guards the
merge with the inspected head commit, and verifies GitHub. After verification it
switches to the configured base branch, fast-forwards it, and deletes the
managed source branch locally and remotely before recording evidence and
completing Linear. Product Main pr change merge performs the same branch
cleanup while leaving the parent In Progress.
Branch cleanup is idempotent and also runs when the PR was already merged, so retrying either merge command repairs interrupted cleanup. A base branch that cannot fast-forward or a cleanup failure produces a partial result and preserves the source branch where possible; child Linear completion does not run until cleanup succeeds. Dry-run output includes the branch switch, base update, and deletions covered by the confirmation boundary.
Standalone repository changes
anuva repository-change start <intake-json> --dry-run
anuva repository-change start <intake-json> --confirm
anuva repository-change docs start <issue-id> --plan <absolute-plan> --dry-run
anuva repository-change docs start <issue-id> --plan <absolute-plan> --confirm
anuva repository-change docs pr create <issue-id> --plan <absolute-plan> --preview <url> --dry-run
anuva repository-change docs pr create <issue-id> --plan <absolute-plan> --preview <url> --confirm
anuva repository-change docs pr ready <issue-id> --dry-run
anuva repository-change docs pr ready <issue-id> --confirm
anuva repository-change complete <issue-id> --report <absolute-report> --dry-run
anuva repository-change complete <issue-id> --report <absolute-report> --confirm
For the explicitly selected standalone Linear path, the skill owns read-only
eligibility and documentation judgment. Its typed JSON schema accepts only
not-required and required; Escalate cannot reach a mutating command.
Intake requires a retry-stable idempotency key, complete
Scope/Acceptance/Docs/Verification inputs, evidence, and bounded Product Main
Markdown paths when required.
repository-change start resolves the current configured repository, creates or
reuses one versioned-marker issue directly in In Progress with exactly that
repository label, then reconciles codex/<issue-id>-<slug>. Marker collision or
contract drift fails closed.
The normal anuva pr create --draft and anuva pr ready commands deliver the
implementation PR for a child or marked standalone issue. Product Main parents
must use phase commands.
The docs commands require a marked standalone issue, a recorded Required
disposition, an approved absolute Implementation Plan, the deterministic
codex/<issue-id>-<slug>-product-main-docs branch, exact bounded docs paths, and
a strict configured Product Main preview. They create and link at most one draft
companion PR and leave the issue In Review.
repository-change complete validates the absolute report, clean worktrees,
PR identity, reviews, mergeability, and checks. It merges implementation before
the optional docs companion; verifies merges; fast-forwards configured bases;
deletes local and remote branches; records delivery evidence; and moves Linear
Done last. Identical retries inspect verified effects and resume after supported
partial failures.
Documentation
anuva docs preview --repository <name|current> --file <path>... [--json]
anuva docs verify --repository <name|current> --file <path>... [--json]
anuva docs ensure --repository <name|current> --dry-run
anuva docs ensure --repository <name|current> --confirm
anuva docs status [--all] [--json]
anuva docs validate-indexes --repository <name|current> [--json]
anuva docs wait --repository <name|current> --file <path>... --since <pre-edit-timestamp>
anuva docs links --repository <name|current> --file <path>... [--json]
anuva docs stop [--all] --dry-run
anuva docs stop [--all] --confirm
anuva docs publish [--clean] [--skip-linear-status] [--push] --dry-run
anuva docs publish [--clean] [--skip-linear-status] [--push] [--confirm]
The Phase 3 contract makes docs preview the lightweight process and URL
operation. It ignores docs-source, branch, and HEAD changes for restart
purposes. docs verify performs one strict build, meaningful structure
validation, and requested served-page comparisons without --since.
For normal documentation work, run docs preview before editing, then one
docs verify invocation for all changed pages and docs links for exact review
URLs. ensure, wait, and validate-indexes retain the Phase 2
generation/timestamp behavior solely for rollback compatibility.
Development environment
anuva dev start [--docs-only|--with-docs] [--with-tunnel] --dry-run
anuva dev start [--docs-only|--with-docs] [--with-tunnel] --confirm
anuva dev status [--json]
anuva dev logs <service>
anuva dev stop [--all] --dry-run
anuva dev stop [--all] --confirm
Output contract
Every JSON response uses a versioned envelope:
{
"schemaVersion": 1,
"ok": true,
"operation": "linear.issue.get",
"data": {},
"warnings": [],
"receipt": null
}
Use stable nonzero exit codes for invalid input, missing configuration, authentication, precondition failure, external command failure, partial failure, and user confirmation required. Human output may be friendly, but skills rely on the JSON contract.
Every execution-form mutation validates current state, acquires a scoped lock,
performs only its named changes, verifies the result, and writes a redacted
receipt. --confirm selects execution but does not replace explicit user approval
at the surrounding Codex workflow boundary. CLI-owned processes record an OS
executable/start identity; stop commands refuse stale or reused PIDs.
The implementation includes anuva docs publish. The legacy PowerShell publisher
remains during golden-output and two-machine parity validation and must not be
removed until the manual migration checks in the implementation plan have passed.
See the CLI Implementation Plan
for architecture, phases, tests, and the build-all-docs.ps1 port.