Skip to main content

​
Usage

Installs an adapter from the given specifier. An adapter is a way for the facet system to talk to external tools, most often AI coding harnesses (OpenCode, Claude Code, Codex, etc.). Adapters define where assets and configuration live on disk. Run with no specifier to choose from an interactive picker of the first-party adapters (TTY only) — in a non-interactive shell the no-argument form fails with a structured error and exit 1.

​
Built-in adapters

These names resolve to the first-party adapter packages:
  • opencode — OpenCode adapter (@agent-facets/adapter-opencode)
  • claude-code — Claude Code adapter (@agent-facets/adapter-claude-code)
  • codex — Codex adapter (@agent-facets/adapter-codex)
A per-install --target-dir flag is intentionally not supported: later invocations (such as facet build) would have no way to locate adapters placed in non-default locations.

​
Exit codes

​
What it does

The install flow stages and verifies a candidate before it ever touches the existing installation:
  1. Download (or clone/copy) the source and bundle it into a self-contained adapter.js in temporary storage.
  2. Verify the bundle: it must export a valid adapter that declares a supported adapter API. For npm sources the runtime declaration must also match the package metadata used for selection.
  3. Acquire a per-adapter replacement lock, copy the verified bundle into a new generation under $FACET_DIR/adapters/<name>/generations/<generation-id>/, and verify it again at its final path.
  4. Atomically activate the new generation by replacing the installation.json receipt — the record of the active generation, verified API, and source provenance (specifier, resolved npm package/version, integrity).
  5. Remove the previous generation.
Any failure before activation leaves the existing installation untouched — replacement is atomic. A cleanup failure after activation is reported as a warning; the new version is already active. See environment variables for the FACET_DIR layout.

​
Specifier formats

Adapter specifiers accept git+ URLs even though facet sources for facet add reject them — adapter installs and facet installs follow different source rules.
Version selectors use the Facet grammar: exact 1.2.3, major wildcard 1.*, minor wildcard 1.2.*, *, or latest. npm range syntax (^1.2.3, ~1.2.3, comparators, hyphen/OR/x-ranges, prerelease tags) is rejected with an error listing the supported forms.

​
Compatible resolution

Every adapter declares the adapter API contract it was built against, and each CLI release supports an exact set of adapter APIs (currently 0.1, the tagged request/result contract). A CLI that supports only 0.1 treats an adapter still declaring the earlier positional 0.0 as unsupported; an older 0.0 CLI conversely keeps selecting the highest compatible 0.0 release, so the two lines advance independently. For npm installs, the CLI reads the package’s version metadata (the facetAdapterApiVersion field each release publishes) and selects the highest stable release that both satisfies your version 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 selector (1.*, 1.2.*) selects the highest compatible release in the range.
  • An exact version considers only that release: if it is incompatible, the install fails rather than substituting another version.
  • Releases with a missing or malformed declaration are never selected.
When no release in the requested set is compatible, the install fails with the newest considered release, its declared (or missing) adapter API, and the APIs this CLI supports. Git and local sources don’t participate in compatible resolution — the version-selector grammar and highest-compatible-release selection apply only to npm installs. A Git #ref still pins exactly what gets built (a tag, branch, or commit), and both Git and local sources are built as supplied and must pass the same runtime compatibility verification before installation.

​
See also