Skip to main content

​
Usage

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

Every accepted form — and what each writes to facets.json — is in the source grammar below.

​
Flags

​
boolean
Show detailed step output on stderr.

​
Exit codes

​
What it does

1

Parse

Validate every source specifier up front. Invalid grammar exits before touching disk.
2

Discover adapters

If none installed: launch the picker when the terminal can prompt, or fail with recovery guidance when it cannot.
3

Prepare

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.
4

Commit

Delegate to the install pipeline with the additions delta. Version resolution, integrity verification, global collision detection, and the atomic write follow the commit phase — additions always re-resolve non-exact specifiers, and new lockfile entries require registry confirmation (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 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):

​
Registry names

​
Git and GitHub sources

​
Local paths

​
Forms that are rejected

​
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 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.

​
See also

  • facet 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 — install adapters into your machine.