> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.
# facet adapter install
> Installs an adapter
## Usage
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet adapter install [specifier]
```
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
| Code | Meaning |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0` | Adapter installed |
| `1` | Install failed (bad specifier, no compatible release, download/clone failure, invalid adapter export, incompatible adapter API, or the no-argument form in a non-interactive shell) |
## 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//generations//`, 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](/cli/env) for the `FACET_DIR` layout.
## Specifier formats
```sh Built-in name theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet adapter install opencode
# resolves to the first-party npm package
```
```sh npm package theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet adapter install @acme/adapter-custom # highest compatible release
facet adapter install @acme/adapter-custom@1.2.3 # exact version — fails if incompatible
facet adapter install @acme/adapter-custom@1.* # highest compatible in the range
facet adapter install opencode@latest # explicit latest = highest compatible
```
```sh Git URL theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet adapter install git+https://github.com/user/repo.git#v1.0.0
# clones the repository; optional #ref pins a tag, branch, or commit
```
```sh Local path theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet adapter install ./path/to/adapter
# uses a local directory
```
Adapter specifiers accept `git+` URLs even though facet sources for [`facet add`](/cli/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
* [`facet adapter list`](/cli/adapters/list) -- list installed adapters.
* [`facet adapter remove`](/cli/adapters/remove) -- remove an installed adapter.
* [Environment variables](/cli/env) -- `FACET_DIR` and the directory layout.