Skip to main content
Connect an adapter for your AI tool, then add the facets you want. This guide walks the loop: add, inspect, reinstall, update, and remove.

​
Connect an adapter

An adapter tells the CLI where your AI tool keeps its files and its MCP configuration. You need at least one.
Run facet adapter add with no name for a picker. Third-party adapters install the same way from npm, a git URL, or a local path.
Skip this and facet add opens the picker for you on first use. In CI it fails instead, so connect the adapter first.

​
Find and add a facet

facet add writes the entry to facets.json and installs it in one step. A bare name resolves to the latest registry release and is pinned to that version.See facet add for the full grammar and what is rejected.

​
What gets written

Commit both files so teammates and CI resolve identical versions.
facets.json records what your project depends on and how you want its assets named. facets.lock records exact versions, , and per-file records. The CLI owns the lockfile; never hand-edit it.A third file, the machine-local install receipt, lives outside your project under $FACET_DIR. It tracks what this machine wrote and holds your MCP approvals, which is why neither travels to teammates.

​
Where assets land

Text assets are written into every connected adapter at project scope. With opencode, adding cowsay writes:
Each adapter uses its own conventional locations. A skill installs and removes as one bundle, including its companion files. Files you add to a skill directory yourself are left alone. A facet’s top-level README.md or LICENSE ships in the archive but is never written into your tools.facet remove deletes only what your machine’s receipt records installing, so a file the CLI never wrote is left in place.

​
When two facets want one name

Two facets can publish a text asset with the same name. Nothing picks a winner for you, so the install pauses and asks:
Give each asset one outcome: Keep the published name, Alias it to a name you choose, or Omit it. Only one of them has to change.Your choice is saved to facets.json, so it happens once:
facets.json
Aliasing renames the file on disk only. The publisher’s name and every integrity hash are unchanged, so an alias cannot smuggle in different content. See Materialization.
CI cannot prompt. An unresolved collision fails the run and prints the exact facets.json edit to make. Resolve collisions locally and commit the result.

​
Approve MCP servers

A facet can declare MCP servers. Because that configuration lets your tool run a command or open a connection, the CLI asks before writing it. One screen lists every server, the facets that want it, and the exact command, arguments, and environment values or URL. Decline is selected by default.You are asked again only when a declaration changes. Approval is stored per machine, so a teammate approves on their own.In CI, pre-approve the set:
Without the flag, an unapproved declaration fails before anything is written and prints what you need to decide, including the edit that refuses one server:
facets.json
If a server name already exists in a tool’s config and this project did not put it there, the same screen says so, and whether the entry matches or would be replaced.

​
Reinstall after a clone

facet install materializes every declared facet at the versions in the lockfile.
In CI, add --frozen-lockfile. It never rewrites the lockfile and fails when facets.json and facets.lock disagree. See frozen installs.

​
Manage what is installed

facet update shows what is installed next to the versions it could move to. Git and local facets are listed as unsupported, since only registry facets have releases to compare. To pin instead, re-add at an exact version with facet add viper-plans@2.0.0.facet remove drops the facet from facets.json, deletes what it still owns, and rewrites the lockfile. Assets another declared facet still wants are kept, and removing a name that is not declared is a safe no-op.Connecting an adapter later hands it everything the project already owns: the next install materializes those assets into the new tool too.