CLI reference

Every command the alloy CLI exposes, with its real flags. Run as npx @engineering11/alloy-cli <cmd> (aliased to alloy here). Invoke from anywhere inside a repo with a .alloy/ root; the CLI walks up to it.

A quick orientation before the detail: you run a handful of these directly (init, survey, status, console, corpus pin/sync); the rest are run by the skills and CI on your behalf during the loop.

alloy init [dir]

Scaffold a repo-housed spoke corpus frame under .alloy/. Refuses to overwrite an existing .alloy/.

Flag	Effect
--spoke	Scaffold the spoke layout (the frame under .alloy/)
--ci	Scaffold the spoke CI workflows under .github/workflows/
--name <name>	Source name (default: kebab-cased basename of the target dir)

Composable as alloy init --spoke --ci. --ci also runs standalone on an existing spoke.

alloy survey <path-or-repo>

Onboard a repo Alloy has never seen: sniff its ecosystem markers and write a survey brief for the drafting agent. Commits nothing; all output lands under the gitignored .alloy-output/.

Flag	Effect
--name <name>	Source name (default: basename of the path/repo, .git stripped)
--ref <ref>	Branch, tag, or commit SHA (required for a git URL target)
--output-dir <dir>	Override the default .alloy-output/survey output directory
--check	Validate and dry-run the agent's draft instead of writing a brief
--draft <dir>	Draft directory to check (default: .alloy-output/survey/<name>/draft)
--json	Emit { sniff, briefPath } (or the draft-check report with --check) as JSON

A local directory is used directly (dev mode); anything else is treated as a git URL and requires --ref.

alloy discover [source]

Enumerate the documentable units each configured source declares, grouped by kind, with the count of unmatched candidates.

Flag	Effect
--json	Emit the source inventory as JSON to stdout

Pass a source name to discover only that source.

alloy generate <target>

Assemble the deterministic context bundle for one unit - step one of authoring. <target> is <kind>/<name> (optionally <source>:<kind>/<name>).

Flag	Effect
--output-dir <path>	Override the default output directory
--stdout	Output to stdout instead of a file

alloy regenerate <target>

The same bundle as generate, but for docs that already exist - the refresh entry point after drift. Lists the existing docs it expects you to refresh.

Flag	Effect
--output-dir <path>	Override the default output directory

There is no author command. Authoring is the agent step between generate/regenerate and validate.

alloy validate [path]

Run the eight-validator quality gate. Takes no flags - just an optional path (a corpus directory or a single .md file; defaults to the resolved corpus root). Exit 1 on any error; a failing doc cannot merge.

alloy stamp <target>

The only writer of provenance (last_verified, source, source_ref, source_hash, source_contract). Runs the gate first and refuses to stamp if it fails. <target> is <kind>/<name> for a generated unit - the same target generate takes - or a path to a curated .md doc.

Flag	Effect
--bundle-dir <path>	Override the bundle directory (default: .alloy-output/<category>/<name>)

alloy status [path]

The whole health report: drift, coverage reconciliation, extraction-coverage accounting, staleness, gap analysis, and curated governance. Findings exit 0 - it reports, it never reds a build.

Flag	Effect
--stale-days <number>	Days before a document is considered stale (default 30)
--json	Emit the stable machine contract to stdout (no other output)
--gate	Exit 1 when a coverage.strict source has UNKNOWN elements

--gate is how an invocation opts into enforcement; without it, status never exits non-zero on a finding.

alloy finalize <source> [category]

Deterministically regenerate a category's navigational map from router frontmatter (owns, load_when), splicing between the map fence markers. LLM-free and byte-stable. Pass a category to finalize only it.

Flag	Effect
--check	Report map drift and exit 1 without writing (the map-integrity gate)

alloy new curated <category>/<slug>

Scaffold a governed shared/ document that passes the gate as generated. <category> is a shared category dir or manifest key.

Flag	Effect
--corpus <dir>	Corpus root directory (default: the resolved alloy root)
--owner <email>	Document owner (default: git config user.email)
--review-after <date>	Review-due date, YYYY-MM-DD (default: today + 180 days; exclusive with --referent)
--referent <source:path>	Code referent, repeatable. Scaffolds without review_after - freshness comes from alloy stamp
--title <title>	Document title (default: title-cased slug)

alloy corpus pin <version> and alloy corpus sync

Manage the committed corpus pin (.alloy/corpus.lock) and the machine-global corpus cache - the consumer path for a repo that consumes a central corpus.

Command	Flag	Effect
corpus pin <version>	--view <name>	View to record in the lock (fresh locks default to default)
corpus sync	--force	Re-fetch over an existing (e.g. corrupt) cached version

The version is an exact pin (1.0.0), a range (^1.0.0, 1.x), or latest/*.

alloy console [path]

Serve the read-only web console over the working-tree corpus. See The console.

Flag	Effect
--port <number>	Port to serve on

CI-run commands

You will rarely type these; the spoke CI workflows (alloy init --ci) run them for you.

• alloy propose [target] - plan the batched propose run (the drift ladder's propose rung). Flags: --json, --limit <n>, --drift-only. Writes nothing; it is a plan, not an action.
• alloy drift-report <detection-json> - render an alloy status --json capture into a single pinned drift-report issue. Flags: --dry-run, --trigger <name>, --detect-outcome <success|failure>.
• alloy check-consumers <paths...> - validate every query key and citation in consumer markdown against the corpus. Flags: --corpus <dir>, --view <name>, --ignore <token> (repeatable).