Skip to main content

​
Usage

Creates a facet project in the given directory, defaulting to the current one. With no authoring flags it runs an interactive wizard; with any authoring flag it scaffolds directly in headless mode. If facet.json already exists, the wizard asks before overwriting and --force skips that prompt. Headless mode has no prompt, so it requires --force in that case. A fresh directory needs no flag either way.

​
Examples

​
Flags

​
string
required
Facet name, required in headless mode. An unscoped slug or @scope/name. See the name grammar.
​
string
Facet description.
​
semver
Facet version. Defaults to 0.0.0.
​
boolean
Mark the facet private.
​
repeatable
A text asset to scaffold. Repeat per asset. At least one is required in headless mode. Names are single segment, and a skill and command cannot share one.
​
boolean
Write and declare an editable README.md, seeded from the name and description. On by default. Use --no-readme to skip it.
​
boolean
Overwrite an existing facet.json. Required in headless mode when a manifest already exists, because there is no confirmation prompt to fall back on. Scaffolding into a directory with no facet.json never needs it.
​
boolean
Emit a structured result: name, version, target directory, and the files written.

​
Exit codes

​
Output

Starter asset files are plain markdown with no front matter, because asset metadata lives in the manifest. You may add front matter later; the manifest still wins at install time. README.md and other supplementary files are written verbatim.

​
Details

​
Headless mode

Headless scaffolding requires v0.24.0 or newer. Passing --name, --description, --version, --private, --skill, --agent, or --command skips the wizard. --force and --json do not trigger headless mode on their own, so facet create --json alone still opens the wizard and prints no JSON document. After scaffolding, validate with facet build --verify or make further changes with facet modify.

​
Interactive wizard

The wizard asks for the name, description, version, and privacy, then the assets to scaffold. The README step is enabled by default and seeds content from the name and description, preserving your edits if you change either afterwards. A summary precedes any write.

​
Troubleshooting

Cause: the target directory already contains a facet.json. Headless mode has no prompt to fall back on.Fix: pass --force to overwrite, or scaffold into an empty directory.
Cause: --name is missing, or no --skill, --agent, or --command was given. Scaffolding needs at least one text asset.Fix: supply both, for example --name my-facet --skill greet.
Cause: the facet name breaks the name grammar, an asset name is not a single lowercase segment, or --version is not semver.Fix: correct the value. Names are validated, never normalized, so nothing is silently rewritten.

​
See also