> ## 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 build

> Build a facet from the current directory

## Usage

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet build [directory]
```

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

<ResponseField name="--verify" type="boolean">
  Validate the facet without writing any output (no `dist/` writes).
</ResponseField>

<ResponseField name="--json" type="boolean">
  Emit a machine-readable JSON result to stdout instead of the interactive view.
</ResponseField>

<ResponseField name="--emit-manifest" type="boolean">
  Write a loose `build-manifest.json` to `dist/` alongside the `.facet` file.
</ResponseField>

## Exit codes

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `0`  | Build (or verify) succeeded                  |
| `1`  | Build (or verify) failed (validation errors) |

## What it does

`facet build` runs the validation-and-assembly pipeline defined in the [Build specification](/specification/build): parse and validate the manifest, resolve prompts from their conventional paths, resolve and validate declared [supplementary files](/specification/manifest#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](/specification/archive)). `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`

<Note>
  The `--verify` and `--json` flags require the facet CLI **v0.24.0 or newer**. Update with [`facet self-update`](/cli/self-update) if your build doesn't recognize them.
</Note>

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

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet build --verify          # validate only; dist/ is never touched
```

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`](/cli/instructions).

## 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`.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet build --verify --json   # validation result as JSON, no output written
facet build --json            # build and write output, then print JSON
```

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

* [`facet publish`](/cli/authoring/publish) -- verify and upload the built archive.
* [Build specification](/specification/build) -- the normative build steps and archive format.