> ## 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 add > Add facets to a project and install them ## Usage ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add [more sources...] ``` Adds the named facet(s) to `facets.json` and immediately installs them into every connected adapter. There is no separate "install after add" step -- `facet add` is the single command for bringing a new facet into a project. Every source specifier is validated first. If the project then has no adapters installed, `facet add` launches the adapter picker — but only when the terminal can prompt. Otherwise it exits with an error pointing at `facet adapter install`. ## Examples ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add viper-plans # bare name — pins the resolved version facet add viper-plans@1.* # wildcard — floats within 1.x facet add @acme/deploy-tools # scoped facet facet add github:agent-facets/viper-plans#main facet add ./local-facets/my-plans facet add viper-plans rezi planner@2.* # multiple sources in one command ``` Every accepted form — and what each writes to `facets.json` — is in the [source grammar](#source-grammar) below. ## Flags Show detailed step output on stderr. ## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Add and install succeeded. | | `1` | Failed — parse error, no usable adapter, an unresolved [name collision](/cli/install#name-collisions), a cancelled resolution, or an install failure. Nothing is written unless the failure happened mid-write, in which case the journal rolls it back. | ## What it does Validate every source specifier up front. Invalid grammar exits before touching disk. If none installed: launch the picker when the terminal can prompt, or fail with recovery guidance when it cannot. Read each source's `facet.json` to learn its name. Sources that declare a non-empty `facets: [...]` array are rejected. Load the project manifest if it exists. Delegate to the [install pipeline](/specification/install) with the additions delta. Version resolution, integrity verification, [global collision detection](/specification/commit#compose), and the atomic write follow the [commit phase](/specification/commit) — additions always [re-resolve non-exact specifiers](/specification/commit#resolve), and new lockfile entries require [registry confirmation](/specification/commit#verify) (fails closed offline). Adding a facet is the most common way to hit a name collision: the new facet may want a name an installed facet already uses. See [Name collisions](/cli/install#name-collisions) for how that is resolved and what gets recorded. The manifest, lockfile, and receipt are **never written ahead** of success. A failure before the first write — including an unresolved collision — leaves the project byte-identical with nothing to undo; a failure after it rolls back through the journal. ## Source grammar `facet add` accepts these source forms (the normative source-kind taxonomy lives in [Planning — Accepted source kinds](/specification/planning#accepted-source-kinds)): ### Registry names ```sh Bare name theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add viper-plans # equivalent to viper-plans@latest; the resolved version is # written back to facets.json (default-to-pinned) ``` ```sh Exact version theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add viper-plans@1.2.3 # exact pin, written verbatim ``` ```sh @latest theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add viper-plans@latest # re-resolves to the newest published version; "latest" is preserved # verbatim in facets.json (the entry floats) — only a bare name pins ``` ```sh Wildcard theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add viper-plans@1.* # also 1.2.* and *; the wildcard is preserved in facets.json and # the resolved exact version goes in the lockfile ``` ```sh Scoped theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add @scope/name@1.2.3 # the leading @ marks the scope; a trailing @ separates the version. # versioning and pinning rules are identical to unscoped names ``` ### Git and GitHub sources ```sh GitHub shorthand theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add github:owner/repo#ref # optional #ref: branch, tag, or SHA ``` ```sh HTTPS git URL theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add https://host/repo.git#ref # must end in .git; optional #ref ``` ```sh SCP-style git URL theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add git@host:owner/repo.git#ref # standard user@host:path SSH form; optional #ref ``` ### Local paths ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add ./facets/my-plans # relative, absolute, or ~-prefixed; must resolve inside the # project tree. A file: prefix is tolerated (stripped, then # treated as a local path) ``` ### Forms that are rejected ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} facet add git+https://host/repo.git # git+ prefix — drop it: https://...git facet add viper-plans@^1.2.3 # caret/tilde ranges — use 1.*, 1.2.*, or 1.2.3 facet add viper-plans@">=1.0.0" # comparator and OR ranges — pick one version facet add viper-plans@1.x # x-style placeholders — use 1.* or 1.2.* ``` ## Re-adding a facet Running `facet add` against a facet that's already in `facets.json` is supported: * Same source as before → no-op (lockfile may report `unchanged` or `repaired`). If you have since aliased or omitted one of its assets, it reports `updated` instead — the version did not move, but its materialization did. * Different version pin → updates the entry; the install summary shows `(was X → Y)`. * Bare re-add (no version) → resolves the newest published version and **pins** it in `facets.json`. A bare add always pins to the resolved exact version, even over an existing wildcard spec. * Explicit `@latest`/wildcard re-add → re-resolves to the newest match (the lockfile never pins an explicit non-exact add), but the specifier itself is written verbatim and keeps floating. In every case, any [materialization overrides](/specification/materialization#recording-intent) already recorded for the facet are preserved. Changing where a facet comes from is not a statement about how its assets should be named. An override naming an asset the new version no longer contains is dropped, and the install tells you which one. What gets written per specifier shape is defined by the [manifest-write policy](/specification/commit#manifest-write-policy). ## See also * [`facet install`](/cli/install) -- re-runs the install pipeline against the current `facets.json` and lockfile, useful after a fresh `git clone` or to reapply assets after manual edits. * [`facet adapter install`](/cli/adapters/install) -- install adapters into your machine.