Skip to main content

​
Usage

Removes facets from facets.json, deletes the files and MCP server entries they still own from every connected adapter, and rewrites facets.lock without them. Aliased as facet rm. The inverse of facet add. Ownership is decided by your machine’s records, so a facet this machine never installed loses its declaration but keeps its files. Removing a name that is not declared is a safe no-op, and several removals commit together or not at all.

​
Examples

​
Flags

​
boolean
Show detailed step output on stderr. Declaration contents never appear here. See where declarations appear.
​
boolean
Approve the MCP configuration this run would write, without prompting.remove accepts it because a removal that has to resolve the facets you are keeping re-enters the install path, and their declarations may need approval. Without the flag such a removal cannot finish in CI.

​
Exit codes

​
Output

The summary reports each facet as removed or removed-untracked, alongside the text assets and server entries that left disk. See outcomes. An untracked removal names the facet and says the files were left in place.

​
Details

​
What gets deleted

Deletion is keyed by the name each contribution was materialized under, not by the facet that published it.
  • A name another declared facet still claims is kept, so a name that transferred between facets is not deleted.
  • Contributions you omitted were never written, so there is nothing to delete.
  • Only files your machine recorded installing are deleted. If you pulled a teammate’s lockfile and never installed, the declaration is dropped, the files stay, and the summary says so. Remove those by hand.
  • An MCP entry is deleted only when your machine configured it and no kept facet still claims that name. Entries you or a teammate wrote by hand are never deleted.

​
Materialization overrides

Removing a facet discards the materialization overrides recorded for it. Overrides on the facets that remain are kept, even when the removal frees the name they worked around. To go back to published names, delete the materialization block and run facet install.

​
When a removal needs the network

A removal usually needs none: when your machine’s records already account for every facet you are keeping, it completes with a cold cache and an unreachable registry. When local state cannot answer, the removal falls back to the full install path. It then has to materialize what you are keeping before claiming it, so it succeeds when the content is reachable and fails, deleting nothing, when it is not. That fallback can also surface work a plain removal never does, such as an unresolved collision or MCP approval for the facets you keep.

​
Troubleshooting

Cause: this machine has no record of installing that facet, so nothing authorizes deleting its files. The declaration is still dropped from facets.json and facets.lock.Fix: delete the named files yourself. To avoid this next time, run facet install on a machine before removing what it never installed.
Cause: local state could not account for a facet you are keeping, so the removal fell back to the full install path and that facet could not be resolved.Fix: run facet install first to take ownership of what you are keeping, then remove again.
Cause: the fallback path re-resolves the facets you keep, and their declarations need approval on this machine.Fix: approve at the prompt, or pass --accept-mcp in CI. See MCP servers.

​
See also