Usage
What it does
The build command runs a validation pipeline, assembles an archive, and computes content hashes:- Parse manifest — reads
facet.json, parses JSON, validates against the schema including business-rule constraints (at least one text asset, etc.) - Resolve prompts — reads prompt files at conventional paths. Skills use
skills/<name>/SKILL.md(Agent Skills directory convention). Agents useagents/<name>.md. Commands usecommands/<name>.md. If an expected file doesn’t exist, the build fails. - Validate assets — checks that all content files are non-empty and contain no YAML front matter. The manifest is the single source of truth for metadata — content files must be pure markdown.
- Check collisions — validates compact facets entries match the
name@versionformat. Fails if the same name is used more than once within the same asset type. - Validate adapters — validates adapter metadata for installed adapters (e.g.,
opencode,claude-code). Each adapter validates its own metadata schema. Unknown adapters produce a warning but do not fail the build. - Assemble archive — collects the manifest and all resolved text assets into a deterministic tar archive, computes the integrity hash, compresses it with gzip, then wraps the compressed archive and a build manifest into the self-contained
.facetfile.
dist/:
dist/<name>-<version>.facet— a self-contained archive (uncompressed tar containingbuild-manifest.jsonandarchive.tar.gz)
.facet file is the single distributable artifact. The build manifest is embedded inside it. 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.
Flags
| Flag | Description |
|---|---|
--emit-manifest | Write a loose build-manifest.json to dist/ alongside the .facet file |
Exit codes
| Code | Meaning |
|---|---|
0 | Build succeeded |
1 | Build failed (validation errors) |