Usage
facets.json, deletes the assets they still own from every connected adapter, and rewrites facets.lock without them — in a single command. “Still own” is decided by your machine’s install receipt: a facet this machine never installed loses its declaration but keeps its files. The inverse of facet add. Aliased as facet rm.
Examples
Flags
boolean
Show detailed step output on stderr.
Exit codes
What it does
1
Load facets.json
A missing or invalid manifest fails before any change — and before adapter discovery, so you get the manifest error rather than “no adapters installed”.
2
Connect an adapter
Removal deletes assets from every connected adapter, so it needs one just like
facet add does. A project with none opens the picker in a terminal and fails in CI. This happens for every request, including one whose names all look undeclared: only the commit, holding the project lock, can know whether that is still true.3
Commit
Delegate to the install pipeline with the removals delta. Removal is receipt-driven; when your machine’s receipt accounts for the facets you are keeping, their lockfile entries are refined in place rather than re-fetched and nothing goes over the network; the manifest, lockfile, and receipt are written together.Deletion is keyed by the name each asset was materialized under, not by the facet that owned it. A name another declared facet still claims is kept, so removing a facet never deletes an asset that has since transferred to a different one. Assets you omitted were never written, so there is nothing to delete for them. Only files your machine’s receipt records are deleted: if this machine never installed the facet — you pulled a teammate’s
facets.lock and never ran an install — removing it updates facets.json and facets.lock, leaves the files alone, and says so. Clean those up by hand; nothing tracks them.4
On any failure
The journal rolls back all changes. Nothing is written ahead of success.
materialization block from facets.json and re-run facet install to go back to published names.
Removal does not re-fetch a facet it is keeping. When your machine’s receipt already accounts for every facet you are keeping, removal completes with a cold cache and an unreachable registry. It falls back to the full install pipeline when local state cannot answer — no lockfile at all, a kept facet that was never locked, one whose entry drifted, a collision already recorded among the facets you are keeping, a name a removed facet shared with one you are keeping, a receipt that is absent, corrupt, or path-mismatched, a kept facet your receipt does not record or does not match, or manifest intent the lockfile does not record. In those cases the removal materializes what you are keeping and only then records ownership of it, so it needs the content: reachable, it succeeds; fully offline, it fails rather than deleting files nothing proves this machine wrote. That fallback is also what can surface a name collision that was never resolved: in a terminal you get the same resolver
facet install uses; in CI it fails with the report.See also
facet add— the inverse: add a facet tofacets.jsonand install it in one step.facet install— reapplyfacets.jsonand the lockfile.