Skip to main content

​
Usage

Validates and builds the facet in the specified directory (defaults to the current directory). The build command is purely deterministic — it never modifies the manifest and behaves identically in all environments.

​
Flags

​
boolean
Validate the facet without writing any output (no dist/ writes).
​
boolean
Emit a machine-readable JSON result to stdout instead of the interactive view.
​
boolean
Write a loose build-manifest.json to dist/ alongside the .facet file.

​
Exit codes

​
What it does

facet build runs the validation-and-assembly pipeline defined in the Build specification: parse and validate the manifest, resolve prompts from their conventional paths, resolve and validate declared supplementary files, validate content, validate adapter metadata, and assemble the deterministic two-layer archive. Validation happens before any dist/ cleanup, so a build that fails leaves your previous output intact. Build output shows the emitted archive-format version, the complete entry listing (assets and supplementary files), and the integrity hash. On success, the build writes dist/<name>-<version>.facet — the single distributable artifact, with the build manifest embedded inside it (see Archive format). dist/ is purged first, so it contains exactly one .facet after a successful build. For a scoped identity the name’s / renders as a nested path: @acme/cowsay at 1.0.0 lands at dist/@acme/cowsay-1.0.0.facet. Use --emit-manifest to also write a loose copy of build-manifest.json to dist/ for debugging or tooling integration. If the build fails, errors are displayed inline under the failed pipeline stage, with a suggestion to run facet edit to fix the issues.

​
Validate without building: --verify

The --verify and --json flags require the facet CLI v0.24.0 or newer. Update with facet self-update if your build doesn’t recognize them.
facet build --verify runs the full validation pipeline without writing any output — a no-op build. Nothing is written to dist/. Use it to confirm that facet.json and every asset file are valid and buildable, without producing an artifact.
A clean verify means the facet would build. To produce the actual .facet artifact, run facet build without --verify. This is the recommended check after editing a facet — see facet instructions authoring.

​
Machine-readable output: --json

facet build --json emits a structured JSON document to stdout instead of the interactive view. It works with or without --verify.
The document is versioned (schemaVersion) and reports ok, whether it was a verify (verified), and on success the facet name, version, assets, and integrity — or on failure a list of errors (each with a message and path) and any warnings.

​
See also