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: in practice your agent runs almost all of these - the reference exists so you can read what it ran. You type init once to bootstrap, the agent starts console when you want to look around, and the rest belong to the skills and CI.
Agents discover this surface at runtime: alloy help --json emits every command - name, description, usage, options - as a stable, additive-only JSON contract, and the alloy front-door skill routes off it rather than off a memorized list. Bare alloy prints the same surface as prose.
alloy init [dir]
Create this repo's knowledge base in one command, with nothing to choose - the bootstrap you type by hand. Writes the .alloy/ frame (a self: true source, ecosystems.yaml, an empty rulepacks/, the corpus manifest, and a .alloy-output/ gitignore), installs the four authoring skills into each harness, and registers the MCP server. Consumes nothing external; every step skips if already done.
| Flag | Effect |
|---|---|
--ide <ides> | Harness(es) to vend into, comma-separated: claude-code, cursor (both default), codex, opencode |
--no-skills | Do not install the authoring skills |
--mcp / --no-mcp | Force or skip MCP registration (default: register only when an @engineering11 registry resolves) |
--ci | Also scaffold the CI workflows under .github/workflows/ |
--name <name> | Source name (default: kebab-cased basename of the target dir) |
--ci also runs standalone on an existing knowledge base.
alloy add <locator>
Declare, fetch and pin another knowledge base as a dependency - one command, like npm install. <locator> is a package (@engineering11/alloy, @acme/standards@^2.0.0) or a git URL. The intent lands in the manifest dependencies: block; the exact resolution (version or commit) lands in .alloy/corpus.lock. Both are committed. If the added knowledge base declares its own dependencies, each is offered (default yes), never pulled in silently. See Add shared knowledge.
| Flag | Effect |
|---|---|
--name <name> | Local name to qualify keys with (default: derived from the locator) |
--ref <ref> | Branch, tag or commit for a git locator (default: main) |
--subtree <path> | Where the knowledge base lives in the repo (default: .alloy/corpus) |
--view <name> | A view the dependency declares (default: its default view) |
--save-dev | Also add the package to devDependencies (package locators only; edits package.json, never installs) |
--yes | Accept every offered sub-dependency without prompting |
--force | Refetch into the cache even over a healthy copy |
alloy remove <name>
Remove a dependency from the manifest and the lock. The machine cache is left untouched.
alloy sync
Restore this knowledge base's committed lock into the machine cache - the command a fresh clone or CI runs. Every declared dependency is fetched at its exact pin; a manifest entry with no pin is resolved and locked; a lock entry the manifest dropped is removed. Plain sync never re-resolves an existing pin, so CI is reproducible.
| Flag | Effect |
|---|---|
--force | Refetch into the cache even over a healthy copy |
--update [names...] | Re-resolve the named dependencies (default: all) from manifest intent, rewrite the lock, and print old → new |
--update is the deliberate act that moves a dependency forward: a package range re-resolves via the registry, a git ref via ls-remote. It exits 1 listing any dependency it could not fetch.
alloy migrate
Move a knowledge base from the older single-pin corpus.lock to the explicit form: a manifest dependencies: block, a lockVersion 2 lock with the exact version, and every unqualified builds_on edge rewritten to <dependency>/<key>. Idempotent.
| Flag | Effect |
|---|---|
--dry-run | Print the changes and write nothing |
alloy query <key>
Resolve a query key exactly as the MCP server and the knowledge skill do: within the scope of the open roots, own-first, then the single other knowledge base that declares the category, else a loud ambiguity. Prints the document, a Cite as line, and the [scope] line. A key in an undeclared knowledge base is out of scope, naming what is in scope and the alloy add fix.
| Flag | Effect |
|---|---|
--root <dir> | An open root to compose scope from (repeatable) |
--corpus <name> | Resolve the key within one named knowledge base in scope |
--json | Emit the resolution as JSON |
alloy mcp register and alloy mcp remove
Register or remove the alloy-corpus MCP server in each harness's config file (claude-code, cursor, codex, opencode). remove leaves sibling servers in place. Both take an optional [dir].
alloy skills install [dir]
Vendor the four authoring skills (alloy, alloy-survey, alloy-corpus, alloy-campaign) into a repo so an agent can drive the corpus loop there. No-clobber by default - a re-install never discards local tweaks. Idempotent on an unmodified tree.
| Flag | Effect |
|---|---|
--ide <ides> | Target harness(es), comma-separated: claude-code → .claude/skills/, cursor/codex → .agents/skills/, opencode → .opencode/skills/ |
--force | Overwrite skills that already exist in the target |
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 install-draft
Weave a checked survey draft into this repo's knowledge base, replacing the init placeholder. Deterministic (no agent, no network): gates on a green draft, then splices source-entry.yaml into alloy.config.yaml, rule packs into .alloy/rulepacks/, categories into the manifest, and any inventory units.yaml into .alloy/units.yaml. The commit stays yours.
| Flag | Effect |
|---|---|
--draft <dir> | Draft directory to install (default: the sole .alloy-output/survey/<name>/draft) |
--force | Overwrite an already-installed source (default refuses a non-placeholder) |
alloy source add <repo>
Add a second, tracked { repo, ref } source to this repo's knowledge base: registers it in .alloy/alloy.config.yaml and the corpus manifest, lists it in the default view, then surveys it so an agent can draft its config. A knowledge base is plural from the start; this refuses a duplicate source name.
| Flag | Effect |
|---|---|
--ref <ref> | Branch, tag, or commit SHA of the source (required) |
--name <name> | Source name (default: basename of the repo, .git stripped) |
alloy discover [source]
Enumerate the documentable units each configured source declares, grouped by kind, with the count of unmatched candidates. Pass a source name to discover only that source.
| Flag | Effect |
|---|---|
--json | Emit the source inventory as JSON to stdout |
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 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.
| Flag | Effect |
|---|---|
--root <dir> | An open root whose scope line is printed beside the result (repeatable) |
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 |
--root <dir> | An open root to compose the knowledge scope from (repeatable) |
--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 latest
Print the latest published stable corpus version. Enumerates the published corpus-v* git tags first, falling back to the npm packument, then to the highest complete cached version when both remotes are unreachable (with a staleness warning on stderr). Plain output is the bare version for scripts.
| Flag | Effect |
|---|---|
--json | Emit { version, latestSource } as JSON |
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 (default 4747) |
--root <dir> | An open root the console composes its scope from (repeatable) |
CI-run commands
You will rarely type these; the CI workflows (alloy init --ci) run them for you.
alloy propose [target]- plan the batched propose run (the drift ladder's propose step). Flags:--json,--limit <n>,--drift-only. Writes nothing; it is a plan, not an action.alloy drift-report <detection-json>- render analloy status --jsoncapture 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).