Skip to main content

​
Usage

Validates and packages the facet in the given directory, defaulting to the current one. The build is deterministic and never modifies facet.json. Validation runs before any dist/ cleanup, so a failed build leaves your previous output intact. The normative rules are in the build specification.

​
Examples

​
Flags

​
boolean
Run the full validation pipeline without writing output. dist/ is never touched.
​
boolean
Emit a structured result to stdout instead of the interactive view. Works with or without --verify.
​
boolean
Also write a loose build-manifest.json into dist/ for debugging.
--verify and --json require v0.24.0 or newer.

​
Exit codes

​
Output

On success the build writes one artifact:
A scoped identity nests, so @acme/cowsay at 1.0.0 lands at dist/@acme/cowsay-1.0.0.facet. The build manifest is embedded inside the archive, and --emit-manifest writes a loose copy beside it.

​
JSON output

The document carries schemaVersion, ok, and verified. On success it reports name, version, facetVersion, files (the complete archive entry listing), integrity, and any warnings. On failure it reports errors, each with a message and a path.
schemaVersion is "2". Consumers pinned to schema 1 must migrate: the old assets field is gone, replaced by files.

​
Details

​
What is validated

The manifest is checked against the schema, each text asset’s prompt is resolved from its conventional path, declared supplementary files are read as opaque bytes, and per-text-asset adapter metadata is validated against every installed adapter. MCP server declarations are validated statically. A build never locates a command, starts a process, connects to a URL, or authenticates.

​
Troubleshooting

Cause: the manifest or a text asset broke a rule. Each error names a message and the path in facet.json that produced it.Fix: read the path in each error and correct that field. A common case is writing a text-asset group as an array: skills is a map of name to descriptor.
facet.json
Re-check with facet build --verify, which validates without touching dist/.
Cause: a text asset’s prompt file or a declared supplementary file does not exist at its declared path, is a symlink, or resolves outside the facet.Fix: create the file at the exact declared path, or drop the declaration. Paths are exact, and globs are not accepted.
Cause: a declaration is not a valid closed stdio or http object. Common reasons: an unrecognized member, a URL that is not absolute http: or https:, a URL carrying credentials, an environment name outside [A-Za-z_][A-Za-z0-9_]*, or a server name outside the asset-name grammar.Fix: correct the declaration in facet.json. See MCP server declarations.
Cause: adapter metadata is validated against every installed adapter, so an adapter this CLI cannot load stops the build before validation of your manifest completes.Fix: run facet adapter list and reinstall the entries it flags.

​
See also