Facet
DeutschInstall

Every facet command, as the binary describes itself.

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.

Getting the binary

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 --candidates

You 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.

All commands

Every command also takes --root <path>: the repository root. Without it, the git toplevel, else the current directory.

facet adr

Inspect architecture decision proposals without writing files

Usage

facet adr [command]

Subcommands

From facet adr --help

facet adr propose-status

Print a read-only status diff for an existing docs/adr Markdown file

Usage

facet adr propose-status <path> [flags]
Flags of facet adr propose-status
FlagWhat it does
--jsonemit the read-only proposal and diff as JSON
--reason stringreason for this proposal (required for a changed status)
--status stringone of the four existing ADR statuses
--superseded-by stringexisting different docs/adr file for an abgelöst proposal; metadata only

From facet adr propose-status --help

facet backing

List the declared behaviour that is deliberately not backed by data yet

Usage

facet backing [flags]
Flags of facet backing
FlagWhat it does
--jsonemit the list as JSON
--registry stringonly this registry (default: all declared in .facetrc.yaml)

From facet backing --help

facet calibrate

Report the shape of the registry: how finely the product has been documented

Usage

facet calibrate [flags]
Flags of facet calibrate
FlagWhat it does
--jsonemit the calibration as JSON
--registry stringmeasure only this registry (default: all declared in .facetrc.yaml)

From facet calibrate --help

facet conventions

Show which project conventions document applies to each registry

Usage

facet conventions [flags]
Flags of facet conventions
FlagWhat it does
--jsonemit the resolution as JSON

From facet conventions --help

facet defects

Rank features and files by how often they have been fixed

Usage

facet defects [flags]
facet defects [command]
Flags of facet defects
FlagWhat it does
--by-filerank files instead of features
--jsonemit the ranking as JSON
--registry stringonly this registry (default: all declared in .facetrc.yaml)
--top intshow only the first N entries (default: all)

Subcommands

From facet defects --help

facet defects backfill

Fill the defect ledger from git history

Usage

facet defects backfill [flags]
Flags of facet defects backfill
FlagWhat it does
--dry-runreport what would be written without writing it
--jsonemit the report as JSON
--limit intwalk at most this many commits back from the starting revision
--match stringregular expression a commit subject must match (default: (?i)^(fix|bugfix|hotfix)(\([^)]*\))?!?:)
--registry stringonly this registry (default: all declared in .facetrc.yaml)
--rev stringrevision to walk back from (default: HEAD)
--since stringonly commits authored after this date (git syntax, e.g. '90.days' or '2026-01-01')
--until stringonly commits authored before this date

From facet defects backfill --help

facet deviations

List the documented behaviour that is a defect rather than a promise

Usage

facet deviations [flags]
Flags of facet deviations
FlagWhat it does
--jsonemit the list as JSON
--registry stringonly this registry (default: all declared in .facetrc.yaml)

From facet deviations --help

facet docs check

Report generated artifacts whose inputs have changed

Usage

facet docs check [flags]
Flags of facet docs check
FlagWhat it does
--jsonemit statuses as JSON
--strictexit non-zero when any artifact is not current

From facet docs check --help

facet docs record

Record what produced a generated artifact

Usage

facet docs record [flags]
Flags of facet docs record
FlagWhat it does
--artifact stringpath to the generated file, relative to the repo root
--feature stringfeature id the artifact was generated from
--generated-at stringISO date of generation
--model stringmodel that generated the artifact
--pipeline stringgenerator pipeline name (default facet-knowledge)
--prompt-version stringversion of the generation prompt
--slots stringsKnowledge slots the artifact consumed

From facet docs record --help

facet drift

Report anchored source that changed without its record following

Usage

facet drift [flags]
facet drift [command]
Flags of facet drift
FlagWhat it does
--baseline stringcompare against this revision (default: the accepted baseline, else HEAD)
--jsonemit drift as JSON
--registry stringcheck only this registry (default: all declared in .facetrc.yaml)
--repository stringcompare only this declared source repository (workspace-relative)

Subcommands

From facet drift --help

facet drift accept

Record that the changes since the baseline have been reviewed

Usage

facet drift accept [path...] [flags]
Flags of facet drift accept
FlagWhat it does
--baseline stringstart this acceptance at the confirmed reviewed revision, keeping other incoming paths unreviewed
--outcome stringwhat the review concluded (default behavior-unchanged)
--repository stringaccept only this declared source repository; paths stay workspace-relative

From facet drift accept --help

facet drift reset

Forget this worktree's accepted baseline and compare against HEAD again

Usage

facet drift reset [flags]
Flags of facet drift reset
FlagWhat it does
--repository stringreset only this declared source repository

From facet drift reset --help

facet errors

List identifiers found in scenario text, grouped and gap-checked by band

Usage

facet errors [flags]
Flags of facet errors
FlagWhat it does
--jsonemit the register as JSON
--registry stringonly this registry (default: all declared in .facetrc.yaml)

From facet errors --help

facet filter install

Configure this clone so anchors you add stay out of every commit

Usage

facet filter install [flags]
Flags of facet filter install
FlagWhat it does
--command stringthe facet executable git should run (default: this binary's path)

From facet filter install --help

facet filter refresh

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

facet filter status

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

facet filter uninstall

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

facet index

Print the record index agents are given

Usage

facet index [flags]
Flags of facet index
FlagWhat it does
--bareids only, without the intent summaries
--max-bytes intbudget for the rendered index (default 24576)

From facet index --help

facet lint

Check records against their schema and against the code they anchor

Usage

facet lint [flags]
Flags of facet lint
FlagWhat it does
--jsonemit findings as JSON
--registry stringcheck only this registry (default: all declared in .facetrc.yaml)
--skip stringschecks 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)
--stagedcheck only the index: report the errors it introduces compared with HEAD (what the commit gate runs)
--today stringISO date used for flag retirement checks (default: today, UTC)

From facet lint --help

facet lsp

Serve FACET code intelligence over LSP on stdio

Usage

facet lsp

No flags of its own beyond --root.

From facet lsp --help

facet mcp

Serve the registry over MCP on stdio

Usage

facet mcp

No flags of its own beyond --root.

From facet mcp --help

facet plugin add

Install a plugin package from a file, folder, https URL, or github:owner/repo@tag

Usage

facet plugin add <source> [flags]
Flags of facet plugin add
FlagWhat it does
--devlink a working folder instead of copying it (ADR-0004 §8)
--grant stringArraygrant a right without asking: tools=a,b / env=X,Y / ai=a,b / ai-env=X,Y
--replacereplace an already-installed plugin of the same id
--sha256 stringexpected SHA256 of the package (required for an https:// source)

From facet plugin add --help

facet plugin list

List installed plugins

Usage

facet plugin list [flags]
Flags of facet plugin list
FlagWhat it does
--jsonprint as JSON

From facet plugin list --help

facet plugin pack

Pack a plugin folder into a .facetplugin, writing SHA256SUMS from the actual files

Usage

facet plugin pack <dir> [flags]
Flags of facet plugin pack
FlagWhat it does
-o, --out stringoutput path (default <id>-<version>.facetplugin)

From facet plugin pack --help

facet plugin remove

Remove an installed plugin

Usage

facet plugin remove <id>

No flags of its own beyond --root.

From facet plugin remove --help

facet plugin update

Re-install a plugin from the source it was installed from

Usage

facet plugin update <id> [flags]
Flags of facet plugin update
FlagWhat it does
--grant stringArraygrant a right without asking: tools=a,b / env=X,Y / ai=a,b / ai-env=X,Y

From facet plugin update --help

facet rag index

Embed the records and generated documents into a vector index

Usage

facet rag index [flags]
Flags of facet rag index
FlagWhat it does
--embed-batch intchunks per request (default 64)
--embed-dimensions intshorten vectors, where the provider supports it
--embed-key-env stringenvironment variable holding the API key (never the key itself)
--embed-model stringembedding model name
--embed-provider string"openai" for any OpenAI-compatible endpoint, or "local" (default: from .facetrc.yaml)
--embed-url stringembeddings API root, without /embeddings
--index-path stringwhere the index lives (default: docs/facets/generated.rag.bin)
--jsonreport the build as JSON

From facet rag index --help

facet rag query

Search the index and print the nearest chunks

Usage

facet rag query <question> [flags]
Flags of facet rag query
--embed-batch intchunks per request (default 64)
--embed-dimensions intshorten vectors, where the provider supports it
--embed-key-env stringenvironment variable holding the API key (never the key itself)
--embed-model stringembedding model name
--embed-provider string"openai" for any OpenAI-compatible endpoint, or "local" (default: from .facetrc.yaml)
--embed-url stringembeddings API root, without /embeddings
--index-path stringwhere the index lives (default: docs/facets/generated.rag.bin)
--jsonemit hits as JSON
--kind stringonly "record" chunks or only "doc" chunks
-n, --limit inthow many chunks to return (default 5)
--min-score floatdrop hits below this cosine similarity

From facet rag query --help

facet registries

Show which features each registry documents

Usage

facet registries [flags]
Flags of facet registries
FlagWhat it does
--gapsshow only ids that some registry is missing
--jsonemit the matrix as JSON

From facet registries --help

Make facet reachable from your shell with a link to the current binary

facet setup link [flags]
Flags of facet setup link
FlagWhat it does
--candidateslist user-writable directories on your login shell's PATH
--dir stringdirectory to put the facet link in
--forcelink even when the directory is not on your login shell's PATH

From facet setup link --help

facet setup precommit

Install a git pre-commit hook that runs 'facet lint --staged'

Usage

facet setup precommit [flags]
Flags of facet setup precommit
FlagWhat it does
--removeremove the hook, only if FACET wrote it
--writeinstall the hook (default: dry run)

From facet setup precommit --help

facet setup status

Report, check by check, how far this project's FACET setup goes

Usage

facet setup status [flags]
Flags of facet setup status
FlagWhat it does
--evidenceprint each row's evidence under it
--jsonemit the rows as a JSON array of {id, state, finding, evidence}
--strictexit 1 when any row is red

From facet setup status --help

facet snapshot

Freeze this repository's Atlas corpus into one JSON file

Usage

facet snapshot [flags]
Flags of facet snapshot
FlagWhat it does
--no-excerptsdrop the source line quoted under every anchor
-o, --out stringfile to write ('-' or empty for stdout)
--registry stringregistry to freeze, in a repository that declares several

From facet snapshot --help

facet split

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]
Flags of facet split
FlagWhat it does
--checkreport what the split dropped
--from stringgit revision, or a path, to read the parent record from (default HEAD)
--jsonmachine-readable output
--registry stringwhich registry, in a monorepo that declares several

From facet split --help

facet test

Run declared test commands and report per-file verification results

Usage

facet test [flags]
Flags of facet test
FlagWhat it does
--checkcheck discovery and baseline drift without executing tests
--fail-unmeasuredexit 1 on incomplete feature or file evidence; preserve nonzero runner exits
--jsonemit reports as JSON; during execution runner output goes to stderr
--listlist discovered files and check drift without executing tests
--only stringshow only facet or runner output (execution only)
--registry stringselect one declared registry
--runner stringselect one declared runner; absence across other runners is unmeasured
--update-baselineremove stale baseline entries; never add paths

From facet test --help

facet ui

Read this repository's FACET registry in a browser

Usage

facet ui [flags]
Flags of facet ui
FlagWhat it does
--companion-bin stringClaude Code executable for the companion (default: claude on PATH)
--companion-model stringmodel the companion answers with (default: whatever Claude Code is set to)
--no-opendo not open a browser, only print the address
--port intport to listen on; a taken port falls back to one the system picks (default 7317)
--record stringopen straight at this record id, e.g. tasks/create/quick-add
--registry stringregistry to read (default: the first declared in .facetrc.yaml)

From facet ui --help

facet wiki check

Check the wiki, as CI would

Usage

facet wiki check [flags]
Flags of facet wiki check
FlagWhat it does
--jsonemit findings as JSON
--registry stringwhich registry's wiki (default: the first declared)
--stricttreat every warning as an error

From facet wiki check --help

facet wiki import

Bring pages in from another system, on a branch, and report what was lost

Usage

facet wiki import <source> <ref> [flags]
Flags of facet wiki import
FlagWhat it does
--branch stringthe branch to import onto (default: one named after the reference)
--jsonemit the report as JSON
--no-commitwrite the files on the branch but do not commit them
--registry stringwhich registry's wiki (default: the first declared)

From facet wiki import --help

facet wiki list

List the wiki's pages

Usage

facet wiki list [flags]
Flags of facet wiki list
FlagWhat it does
--bereich stringonly pages in this area
--jsonemit the listing as JSON
--kategorie stringonly pages of this category
--registry stringwhich registry's wiki (default: the first declared)
--tag stringonly pages carrying this tag

From facet wiki list --help

facet wiki mirror

Push the wiki's pages out again, refusing what changed on the far side

Usage

facet wiki mirror --to=confluence --space=KEY [flags]
Flags of facet wiki mirror
FlagWhat it does
--jsonemit the report as JSON
--registry stringwhich registry's wiki (default: the first declared)
--space stringthe Confluence space key to push into (required)
--to stringwhich system to push to (default confluence)

From facet wiki mirror --help

facet wiki new

Write a new page's header and scaffold

Usage

facet wiki new "Title" [flags]
Flags of facet wiki new
FlagWhat it does
--bereich stringthe area — the folder directly under wiki/ (required)
--gruppe stringan optional group folder under the area
--kategorie stringthe page's category, from those wiki.yaml declares
--records stringcomma-separated record ids this page is about
--registry stringwhich registry's wiki (default: the first declared)
--summary stringthe one line shown under the title in listings
--tags stringcomma-separated tags

From facet wiki new --help

facet wiki tag

Add or remove a page's tags, leaving everything else alone

Usage

facet wiki tag <path> [flags]
Flags of facet wiki tag
FlagWhat it does
--add stringcomma-separated tags to add
--registry stringwhich registry's wiki (default: the first declared)
--remove stringcomma-separated tags to remove

From facet wiki tag --help