CLI reference

The valinor command-line interface exposes Valinor's checks and scaffolding. Invoke it as valinor <command> [path] (via npx valinor …, or directly if you've added it to a script). Each command takes an optional path that defaults to the conventional config file, emits a telemetry event on stderr (stdout stays reserved for the command's own output, so --json modes pipe cleanly), and fails closed — a non-zero exit on any drift, error, or unreadable input.

valinor --version (or -v) prints the installed package version and exits — the deterministic check the publish pipeline's post-publish smoke test asserts against to prove a freshly-published package actually resolves and runs.

Every command at a glance

This inventory is a projection of the source of truth — it is generated directly from the src/cli.ts command registry, so it lists every command Valinor ships with a one-line summary and can never silently fall behind the code. (The site-freshness gate fails the build if this table drifts from the registry.) Reach below for the editorialized, grouped reference with flags, defaults, and the when to reach for it of each command.

Adopting & updating

init <targetPath>

Adopt Valinor on a repository. Propagates the versioned canonical doctrine into the target's AGENTS.md ≡ CLAUDE.md and scaffolds the minimum to run the gates: governance.config.yml, a starter claims.yml, a starter README.md, .greptile/config.json (the canonical review-rubric rules), and .github/workflows/valinor-gates.yml.

Flags:

• --profile — your repo's profile (shapes the scaffolded config).
• --maturity — adoption maturity.
• --mode — advisory, new-code, or strict (controls whether gates block).
• --stack — your stack (e.g. nextjs); overrides the profile-aware default.
• --dry-run — print the plan and write nothing.

Safe to re-run: it re-inlines the current doctrine in place and leaves already-present scaffold files untouched, so pulling a doctrine update never clobbers your custom claims or rules. A re-run reports each byte-identical file as unchanged — the output tells you exactly what changed.

init-workspace [parentPath] and the workspace sweeps

Adopt Valinor on a non-git parent directory of related repos: init-workspace discovers the git checkouts beneath the parent, seeds the authoritative valinor-workspace.yml manifest, writes workspace-level AGENTS.md ≡ CLAUDE.md, and runs the standard init in every governed repo (the init flags pass through; add --max-depth <n> to search deeper and --rediscover to diff newly-cloned repos into an existing manifest — with --dry-run, a rediscovery reports what it would add and writes nothing).

The discovery boundary: the scan never enters dot-directories (.claude/, .worktrees/, …) or follows symlinked directories, and skips node_modules/vendor — a checkout under a dot-directory (e.g. an agent harness's worktree) is invisible to discovery by design; govern its primary checkout instead.

Afterwards, two sweeps aggregate the workspace — doctrine-check-all (every repo's doctrine block) and audit-all (every repo's stack, KLOC, and latest recorded audit grade). Both print one row per repo plus a rollup footer, continue past failures (--bail opts into fail-fast), exit non-zero when any repo fails or is not-initialized/no-grade, and emit pure JSON on stdout under --json. Run them from the workspace root or any directory beneath it — they walk up to the nearest valinor-workspace.yml.

audit-all starts all-red — that's expected. A freshly-inited workspace reports every repo no-grade: init-workspace scaffolds governance but records no audit grade. Each repo earns its row by running the audit flow once (valinor audit, then valinor audit-record after the graded run); the sweep turns green repo by repo.

onboard [path]

The interactive opt-in wizard — the human-facing counterpart to init's non-interactive scaffold. init writes every opt-in capability at its non-blocking default (the three process gates at warn — they report without blocking — and prints them as a summary); onboard lets you raise them to blocking. For your repo's profile (read from governance.config.yml, or prompted) it walks the single-scalar opt-in gates one at a time — research-ledger, plans, no-empty-catch — printing each one's tradeoff and asking Enforce? [y/N], then writes the dials you chose into governance.config.yml without disturbing its comments or structure (and idempotently — re-running with the same answers changes nothing). It only flips dials; if you have no governance.config.yml yet, run init first.

Run it in a terminal — when its input isn't a terminal (CI, a pipe, an agent session) it never prompts: it prints the profile-aware "Capabilities you can enable" summary plus a note to run interactively or edit the config by hand, writes nothing, and exits cleanly.

release <version | --patch | --minor | --major>

Cut a release as a single consistent transaction — the make-the-right-path-easy companion to the release-check gate. It performs the cut so the result passes release-check by construction, so you (or an agent) never hand-roll an inconsistent release. From an explicit <version> (validated semver, strictly higher than the current) or a bump flag computed from package.json, it bumps package.json (and package-lock.json), moves CHANGELOG.md's ## [Unreleased] content into a dated ## [x.y.z] section, and rolls RELEASES.md the same way — preserving every bullet and the Added/Changed/Fixed grouping — and leaves a fresh empty Unreleased in each. It rejects a non-monotonic or invalid version and fails closed on a malformed changelog (never a half-roll).

Flags:

• --patch / --minor / --major — compute the next version by a semantic bump instead of passing one explicitly.
• --dry-run — print the planned changes and write nothing.
• --tag — also create a local tag vx.y.z (never pushed; it prints the git push origin vx.y.z to run after merge). Without --tag it just prints the tag reminder.

Your changelog site stays editorially curated — release prints a reminder to curate the new version's section (it never auto-generates that prose), and the site-freshness rule keeps it honest.

Verifying your repo

These are the checks you'll run most — locally and in CI. Each scans your own repo from the working directory and fails closed.

GitHub configuration as code

These commands diff (or apply) your repository's GitHub settings against config committed in your repo. They call the GitHub API and read GITHUB_TOKEN from the environment.

The whole-repo audit

Beyond per-change gates, Valinor ships audit skills — graded, standing-repo sweeps of a whole concern (e.g. "has this repo adopted the doctrine?"). They're bundled inside the installed package, version-locked to your Valinor.

npx valinor audit                          # one-command launcher: prints the skills, inventory, and run steps
npx valinor audit-list                     # discover the available concern ids
npx valinor audit-show doctrine            # print that concern's audit skill, for your agent to run
npx valinor audit-report --format both     # render the shareable Codebase Audit Report (Markdown + HTML)

audit is the one-command launcher — run it at the start of a Claude Code session and it prints, in one shot, the applicable audit skill set, the deterministic inventory, and the orchestration steps to drive the run (it reads your repo and writes nothing; add --data-only for just the inventory, or --scope/--exclude to narrow it). audit-show is read-only — your coding agent reads the printed skill and runs the graded audit against your repo. Once the run is graded and verified, audit-report renders it into a self-contained, shareable Codebase Audit Report — a Markdown file and/or a self-contained HTML variant (--format md|html|both, --out <path>) carrying the header, the honesty disclosure, the grade with its published formula, and the findings grouped by concern and severity. (PDF export is a deferred follow-up.) Other audit commands (audit-data — the deterministic inventory of your repo's stack, in-scope files, and measured production/test KLOC split the audit folds in (the grade divides by production code only) — plus audit-verify, audit-record, audit-trend, and the gate-health and eval commands) support the inventory, score-over-time, and calibration machinery; run npx valinor with no arguments to see the full list.

Planning and execution procedures

Valinor also ships action skills — orchestrator-level procedures your coding agent reads and follows, in work-lifecycle order: how to roadmap the next work (generate the next-highest-value work from your repo's own structured signal when the backlog is thin — the step before research), how to plan a feature (turn settled research into an ordered, verifiable build), and how to execute an approved plan (choose how to run each phase — inline, a dispatched subagent, or a workflow pattern). Like the audit skills, they're bundled inside the installed package and version-locked to your Valinor.

npx valinor action-list                       # discover the available procedure ids
npx valinor action-show valinor-roadmapping   # print the roadmapping procedure (what to do next)
npx valinor action-show valinor-planning      # print the planning procedure, for your agent to follow
npx valinor action-show valinor-execution     # print the execution toolkit (the workflow-pattern library)

action-show is read-only — your agent reads the printed procedure and applies it; nothing is written to your repo.

Authentication and token tiers

Valinor's GitHub checks read GITHUB_TOKEN from the environment. What each token tier can verify:

The recommended setup is the Valinor GitHub App: install it on your org and have CI mint a short-lived installation token — no personal tokens to provision or rotate. If you gate an admin-only field your token can't read, repo-settings-check reports ⚠ UNVERIFIABLE (fail-closed) with the exact remedy; to deliberately stop gating a field, set verify: false on it in governance.config.yml.

For the exhaustive command list with every flag and default, contributors can consult the in-repo commands reference, which is kept in sync with the CLI source.