Skip to main content

​
Usage

Installs an adapter so facets can materialize into that tool. Run with no specifier for a picker of the first-party adapters. Without a terminal, the no-argument form fails. The candidate is staged, bundled, and verified before it replaces anything, and the switch is atomic. A failure before that switch leaves the existing installation untouched.
facet adapter install is a deprecated alias. It behaves identically and prints a deprecation notice on stderr.

​
Examples

First-party names are claude-code, opencode, and codex.

​
Exit codes

​
Details

​
Specifier grammar

Version selectors use the facet grammar: exact 1.2.3, 1.*, 1.2.*, *, or latest. npm range syntax such as ^1.2.3 or >=1.0.0 is rejected with a list of supported forms. Adapter specifiers accept git+ URLs, even though facet add rejects them for facets. Adapters and facets follow different source rules.

​
Compatible resolution

Every adapter declares the API contract it was built against, and this CLI supports exactly 0.3. See API versions. For npm installs the CLI reads each release’s declared API and selects the highest stable release that satisfies your selector and declares a supported API:
  • A bare name, *, or latest selects the highest compatible release, independent of npm’s latest dist-tag.
  • A wildcard selects the highest compatible release in that range.
  • An exact version considers only that release and fails if it is incompatible.
  • Releases with a missing or malformed declaration are never selected.
Git and local sources skip selection. They are built as supplied and must still pass runtime verification.

​
Where it is installed

The active bundle and its installation record live under $FACET_DIR/adapters/<name>/. Replacing an adapter stages a new generation and switches over atomically, so an interrupted install never leaves a half-written adapter active.
There is no --target-dir. Later commands would have no way to find adapters placed outside the standard location.
Installing is not the same as configuring MCP servers. An adapter with no MCP support installs and works normally, and only blocks a project with active declarations.

​
Troubleshooting

Cause: a facet must materialize into at least one adapter, and this project has none connected. In a terminal you get a picker; without one the command fails.Fix:
Two related failures name themselves differently: installed adapters that declare no text-asset support cannot materialize anything, and a picker that yields only such adapters fails the same way. Install one that materializes text assets.
Cause: nothing in the requested set declares an adapter SDK API this CLI supports. An exact version is never substituted, so pinning an incompatible release fails rather than resolving elsewhere.Fix: the message names the newest release considered and its declared API. Drop the exact pin, or widen the selector, so the CLI can choose a compatible release. For a git or local source, update the source itself.
Cause: the downloaded package did not match the integrity the registry published for it.Fix: do not retry blindly. Verify the package and the registry you are pointed at, then report it if the mismatch persists.
Cause: the built entry has no default export, exports something that is not an adapter, or declares a capability it does not implement.Fix: build the package and confirm it default-exports a defineAdapter call. See the Adapter SDK.
Cause: adapter replacement takes a per-adapter lock, and another process holds it.Fix: wait for that run to finish and re-run. The previous installation stays active meanwhile.

​
See also