facet adr
Inspect architecture decision proposals without writing files
Usage
facet adr [command]
Subcommands
From facet adr --help
One binary runs every registry operation, so CI, your shell and an agent session run the same logic. Each entry below is the command's own --help, generated from the binary rather than written by hand.
Run /facet:setup in your configured FACET agent session. It resolves the distribution binary and links it for your shell. The same facet command then serves your terminal, editor and Git hooks.
With the Claude plugin installed, facet is available inside every session. /facet:setup links it into a directory on your shell's PATH, so a terminal, an editor and a git hook find it too:
You do
facet setup link --candidatesYou see
The directories under your home that are already on your login shell's PATH and writable. Pass one to facet setup link --dir; the link points at a version-free pointer, so it survives updates. No shell startup file is edited.
Every command also takes --root <path>: the repository root. Without it, the git toplevel, else the current directory.
Inspect architecture decision proposals without writing files
Usage
facet adr [command]
Subcommands
From facet adr --help
Print a read-only status diff for an existing docs/adr Markdown file
Usage
facet adr propose-status <path> [flags]
| Flag | What it does |
|---|---|
--json | emit the read-only proposal and diff as JSON |
--reason string | reason for this proposal (required for a changed status) |
--status string | one of the four existing ADR statuses |
--superseded-by string | existing different docs/adr file for an abgelöst proposal; metadata only |
From facet adr propose-status --help
List the declared behaviour that is deliberately not backed by data yet
Usage
facet backing [flags]
| Flag | What it does |
|---|---|
--json | emit the list as JSON |
--registry string | only this registry (default: all declared in .facetrc.yaml) |
From facet backing --help
Report the shape of the registry: how finely the product has been documented
Usage
facet calibrate [flags]
| Flag | What it does |
|---|---|
--json | emit the calibration as JSON |
--registry string | measure only this registry (default: all declared in .facetrc.yaml) |
From facet calibrate --help
Show which project conventions document applies to each registry
Usage
facet conventions [flags]
| Flag | What it does |
|---|---|
--json | emit the resolution as JSON |
From facet conventions --help
Rank features and files by how often they have been fixed
Usage
facet defects [flags] facet defects [command]
| Flag | What it does |
|---|---|
--by-file | rank files instead of features |
--json | emit the ranking as JSON |
--registry string | only this registry (default: all declared in .facetrc.yaml) |
--top int | show only the first N entries (default: all) |
Subcommands
From facet defects --help
Fill the defect ledger from git history
Usage
facet defects backfill [flags]
| Flag | What it does |
|---|---|
--dry-run | report what would be written without writing it |
--json | emit the report as JSON |
--limit int | walk at most this many commits back from the starting revision |
--match string | regular expression a commit subject must match (default: (?i)^(fix|bugfix|hotfix)(\([^)]*\))?!?:) |
--registry string | only this registry (default: all declared in .facetrc.yaml) |
--rev string | revision to walk back from (default: HEAD) |
--since string | only commits authored after this date (git syntax, e.g. '90.days' or '2026-01-01') |
--until string | only commits authored before this date |
From facet defects backfill --help
List the documented behaviour that is a defect rather than a promise
Usage
facet deviations [flags]
| Flag | What it does |
|---|---|
--json | emit the list as JSON |
--registry string | only this registry (default: all declared in .facetrc.yaml) |
From facet deviations --help
Track whether generated documentation still matches its inputs
Usage
facet docs [command]
Subcommands
From facet docs --help
Report generated artifacts whose inputs have changed
Usage
facet docs check [flags]
| Flag | What it does |
|---|---|
--json | emit statuses as JSON |
--strict | exit non-zero when any artifact is not current |
From facet docs check --help
Record what produced a generated artifact
Usage
facet docs record [flags]
| Flag | What it does |
|---|---|
--artifact string | path to the generated file, relative to the repo root |
--feature string | feature id the artifact was generated from |
--generated-at string | ISO date of generation |
--model string | model that generated the artifact |
--pipeline string | generator pipeline name (default facet-knowledge) |
--prompt-version string | version of the generation prompt |
--slots strings | Knowledge slots the artifact consumed |
From facet docs record --help
Report anchored source that changed without its record following
Usage
facet drift [flags] facet drift [command]
| Flag | What it does |
|---|---|
--baseline string | compare against this revision (default: the accepted baseline, else HEAD) |
--json | emit drift as JSON |
--registry string | check only this registry (default: all declared in .facetrc.yaml) |
--repository string | compare only this declared source repository (workspace-relative) |
Subcommands
From facet drift --help
Record that the changes since the baseline have been reviewed
Usage
facet drift accept [path...] [flags]
| Flag | What it does |
|---|---|
--baseline string | start this acceptance at the confirmed reviewed revision, keeping other incoming paths unreviewed |
--outcome string | what the review concluded (default behavior-unchanged) |
--repository string | accept only this declared source repository; paths stay workspace-relative |
From facet drift accept --help
Forget this worktree's accepted baseline and compare against HEAD again
Usage
facet drift reset [flags]
| Flag | What it does |
|---|---|
--repository string | reset only this declared source repository |
From facet drift reset --help
List identifiers found in scenario text, grouped and gap-checked by band
Usage
facet errors [flags]
| Flag | What it does |
|---|---|
--json | emit the register as JSON |
--registry string | only this registry (default: all declared in .facetrc.yaml) |
From facet errors --help
Keep @facet: anchors in the working copy and out of every commit
Usage
facet filter [command]
Subcommands
From facet filter --help
Configure this clone so anchors you add stay out of every commit
Usage
facet filter install [flags]
| Flag | What it does |
|---|---|
--command string | the facet executable git should run (default: this binary's path) |
From facet filter install --help
Make 'git status' agree with 'git diff' after editing a private anchor
Usage
facet filter refresh [path...]
No flags of its own beyond --root.
From facet filter refresh --help
List the private anchors this clone keeps, and any that lost their place
Usage
facet filter status
No flags of its own beyond --root.
From facet filter status --help
Remove the filter from this clone; private anchors stay in the working copy and become committable
Usage
facet filter uninstall
No flags of its own beyond --root.
From facet filter uninstall --help
Print the record index agents are given
Usage
facet index [flags]
| Flag | What it does |
|---|---|
--bare | ids only, without the intent summaries |
--max-bytes int | budget for the rendered index (default 24576) |
From facet index --help
Check records against their schema and against the code they anchor
Usage
facet lint [flags]
| Flag | What it does |
|---|---|
--json | emit findings as JSON |
--registry string | check only this registry (default: all declared in .facetrc.yaml) |
--skip strings | checks to skip (schema, orphan-ids, orphan-records, variants, taxonomy, glossary, duplicate-glossary-term, glossary-near-miss, duplicate-glossary-category, undeclared-glossary-category, empty-glossary-category, sizing, registry-refs, flags, knowledge, backing, deviation, examples, broken-links, dependencies, superseded-by, proves, verification-targets, unclaimed-tests, sibling-suffix, created-at-history, no-scenarios, anchor-proves, anchor-roles, test-only-anchors, enum-divergence, unanchored-hotspots, undocumented-directories, error-codes, lost-anchors, plugin-lint) |
--staged | check only the index: report the errors it introduces compared with HEAD (what the commit gate runs) |
--today string | ISO date used for flag retirement checks (default: today, UTC) |
From facet lint --help
Serve FACET code intelligence over LSP on stdio
Usage
facet lsp
No flags of its own beyond --root.
From facet lsp --help
Serve the registry over MCP on stdio
Usage
facet mcp
No flags of its own beyond --root.
From facet mcp --help
Install, list, remove and pack Atlas plugins (ADR-0004)
Usage
facet plugin [command]
Subcommands
From facet plugin --help
Install a plugin package from a file, folder, https URL, or github:owner/repo@tag
Usage
facet plugin add <source> [flags]
| Flag | What it does |
|---|---|
--dev | link a working folder instead of copying it (ADR-0004 §8) |
--grant stringArray | grant a right without asking: tools=a,b / env=X,Y / ai=a,b / ai-env=X,Y |
--replace | replace an already-installed plugin of the same id |
--sha256 string | expected SHA256 of the package (required for an https:// source) |
From facet plugin add --help
List installed plugins
Usage
facet plugin list [flags]
| Flag | What it does |
|---|---|
--json | print as JSON |
From facet plugin list --help
Pack a plugin folder into a .facetplugin, writing SHA256SUMS from the actual files
Usage
facet plugin pack <dir> [flags]
| Flag | What it does |
|---|---|
-o, --out string | output path (default <id>-<version>.facetplugin) |
From facet plugin pack --help
Remove an installed plugin
Usage
facet plugin remove <id>
No flags of its own beyond --root.
From facet plugin remove --help
Re-install a plugin from the source it was installed from
Usage
facet plugin update <id> [flags]
| Flag | What it does |
|---|---|
--grant stringArray | grant a right without asking: tools=a,b / env=X,Y / ai=a,b / ai-env=X,Y |
From facet plugin update --help
Index the registry for retrieval, and search it
Usage
facet rag [command]
Subcommands
From facet rag --help
Embed the records and generated documents into a vector index
Usage
facet rag index [flags]
| Flag | What it does |
|---|---|
--embed-batch int | chunks per request (default 64) |
--embed-dimensions int | shorten vectors, where the provider supports it |
--embed-key-env string | environment variable holding the API key (never the key itself) |
--embed-model string | embedding model name |
--embed-provider string | "openai" for any OpenAI-compatible endpoint, or "local" (default: from .facetrc.yaml) |
--embed-url string | embeddings API root, without /embeddings |
--index-path string | where the index lives (default: docs/facets/generated.rag.bin) |
--json | report the build as JSON |
From facet rag index --help
Search the index and print the nearest chunks
Usage
facet rag query <question> [flags]
--embed-batch int | chunks per request (default 64) |
|---|---|
--embed-dimensions int | shorten vectors, where the provider supports it |
--embed-key-env string | environment variable holding the API key (never the key itself) |
--embed-model string | embedding model name |
--embed-provider string | "openai" for any OpenAI-compatible endpoint, or "local" (default: from .facetrc.yaml) |
--embed-url string | embeddings API root, without /embeddings |
--index-path string | where the index lives (default: docs/facets/generated.rag.bin) |
--json | emit hits as JSON |
--kind string | only "record" chunks or only "doc" chunks |
-n, --limit int | how many chunks to return (default 5) |
--min-score float | drop hits below this cosine similarity |
From facet rag query --help
Show which features each registry documents
Usage
facet registries [flags]
| Flag | What it does |
|---|---|
--gaps | show only ids that some registry is missing |
--json | emit the matrix as JSON |
From facet registries --help
Measure and wire up a project's FACET setup
Usage
facet setup [command]
Subcommands
From facet setup --help
Make facet reachable from your shell with a link to the current binary
Usage
facet setup link [flags]
| Flag | What it does |
|---|---|
--candidates | list user-writable directories on your login shell's PATH |
--dir string | directory to put the facet link in |
--force | link even when the directory is not on your login shell's PATH |
From facet setup link --help
Install a git pre-commit hook that runs 'facet lint --staged'
Usage
facet setup precommit [flags]
| Flag | What it does |
|---|---|
--remove | remove the hook, only if FACET wrote it |
--write | install the hook (default: dry run) |
From facet setup precommit --help
Report, check by check, how far this project's FACET setup goes
Usage
facet setup status [flags]
| Flag | What it does |
|---|---|
--evidence | print each row's evidence under it |
--json | emit the rows as a JSON array of {id, state, finding, evidence} |
--strict | exit 1 when any row is red |
From facet setup status --help
Freeze this repository's Atlas corpus into one JSON file
Usage
facet snapshot [flags]
| Flag | What it does |
|---|---|
--no-excerpts | drop the source line quoted under every anchor |
-o, --out string | file to write ('-' or empty for stdout) |
--registry string | registry to freeze, in a repository that declares several |
From facet snapshot --help
Report what a re-cut dropped: facets the parent carried and no child does
Usage
facet split --check <parent-id> <child-id> [<child-id> ...] [flags]
| Flag | What it does |
|---|---|
--check | report what the split dropped |
--from string | git revision, or a path, to read the parent record from (default HEAD) |
--json | machine-readable output |
--registry string | which registry, in a monorepo that declares several |
From facet split --help
Run declared test commands and report per-file verification results
Usage
facet test [flags]
| Flag | What it does |
|---|---|
--check | check discovery and baseline drift without executing tests |
--fail-unmeasured | exit 1 on incomplete feature or file evidence; preserve nonzero runner exits |
--json | emit reports as JSON; during execution runner output goes to stderr |
--list | list discovered files and check drift without executing tests |
--only string | show only facet or runner output (execution only) |
--registry string | select one declared registry |
--runner string | select one declared runner; absence across other runners is unmeasured |
--update-baseline | remove stale baseline entries; never add paths |
From facet test --help
Read this repository's FACET registry in a browser
Usage
facet ui [flags]
| Flag | What it does |
|---|---|
--companion-bin string | Claude Code executable for the companion (default: claude on PATH) |
--companion-model string | model the companion answers with (default: whatever Claude Code is set to) |
--no-open | do not open a browser, only print the address |
--port int | port to listen on; a taken port falls back to one the system picks (default 7317) |
--record string | open straight at this record id, e.g. tasks/create/quick-add |
--registry string | registry to read (default: the first declared in .facetrc.yaml) |
From facet ui --help
Read, write and check the project's wiki
Usage
facet wiki [command]
Subcommands
From facet wiki --help
Check the wiki, as CI would
Usage
facet wiki check [flags]
| Flag | What it does |
|---|---|
--json | emit findings as JSON |
--registry string | which registry's wiki (default: the first declared) |
--strict | treat every warning as an error |
From facet wiki check --help
Bring pages in from another system, on a branch, and report what was lost
Usage
facet wiki import <source> <ref> [flags]
| Flag | What it does |
|---|---|
--branch string | the branch to import onto (default: one named after the reference) |
--json | emit the report as JSON |
--no-commit | write the files on the branch but do not commit them |
--registry string | which registry's wiki (default: the first declared) |
From facet wiki import --help
List the wiki's pages
Usage
facet wiki list [flags]
| Flag | What it does |
|---|---|
--bereich string | only pages in this area |
--json | emit the listing as JSON |
--kategorie string | only pages of this category |
--registry string | which registry's wiki (default: the first declared) |
--tag string | only pages carrying this tag |
From facet wiki list --help
Push the wiki's pages out again, refusing what changed on the far side
Usage
facet wiki mirror --to=confluence --space=KEY [flags]
| Flag | What it does |
|---|---|
--json | emit the report as JSON |
--registry string | which registry's wiki (default: the first declared) |
--space string | the Confluence space key to push into (required) |
--to string | which system to push to (default confluence) |
From facet wiki mirror --help
Write a new page's header and scaffold
Usage
facet wiki new "Title" [flags]
| Flag | What it does |
|---|---|
--bereich string | the area — the folder directly under wiki/ (required) |
--gruppe string | an optional group folder under the area |
--kategorie string | the page's category, from those wiki.yaml declares |
--records string | comma-separated record ids this page is about |
--registry string | which registry's wiki (default: the first declared) |
--summary string | the one line shown under the title in listings |
--tags string | comma-separated tags |
From facet wiki new --help
Add or remove a page's tags, leaving everything else alone
Usage
facet wiki tag <path> [flags]
| Flag | What it does |
|---|---|
--add string | comma-separated tags to add |
--registry string | which registry's wiki (default: the first declared) |
--remove string | comma-separated tags to remove |
From facet wiki tag --help