facet modify

Make a headless, scriptable edit to a facet

Usage

facet modify <target> [name] [directory] [flags]

Requires the facet CLI v0.24.0 or newer. If facet modify reports “Unknown command”, update with facet self-update.

facet modify is the headless, flag-driven counterpart to the interactive facet edit wizard. It applies one change to a facet’s facet.json (and its asset files) and exits — the path AI agents and scripts should use for authoring. See facet instructions authoring.

<target> is one of skill, agent, command, or facet. [directory] defaults to the current directory and must contain a facet.json.

Flags

--add · boolean

Add a new asset (scaffold + manifest entry).

--remove · boolean

Remove an asset (delete file + manifest entry).

--rename <name> · string

Rename an asset to the given name.

--description <text> · string

Set the asset’s (or facet’s) description.

--adapter-<name> '<json>' · JSON object

Set an asset’s config for the named adapter (replaces the block).

--remove-adapter-<name> · boolean

Remove an asset’s config for the named adapter.

--name / --version / --private · facet target only

Set facet-level metadata (facet modify facet ...).

--json · boolean

Emit a machine-readable change summary.

Exit codes

Code	Meaning
0	Change applied successfully
1	Invalid arguments, asset not found, or the change would make the manifest invalid

Editing an asset

For the asset targets (skill, agent, command), pass the asset name and at most one lifecycle action, optionally with field changes.

Add an asset

Creates the manifest descriptor and scaffolds the starter file (skills/<name>/SKILL.md, agents/<name>.md, or commands/<name>.md). May carry a description and adapter config in the same call.

facet modify skill greet --add --description "Greets the user"

Change a description

facet modify agent helper --description "Reviews code"

Rename an asset

Renames the manifest key and moves the asset’s file (removing the now-empty skill directory, for skills).

facet modify command run --rename start

Remove an asset

Removes the manifest descriptor and deletes the asset’s file.

facet modify skill greet --remove

Adapter configuration

Each asset descriptor may carry an adapters block: a map of adapter name to a free-form config object that the CLI passes through to that adapter at install time. Set one with a name-embedded flag whose value is a JSON object — the whole suffix after --adapter- is the adapter name, so hyphenated names like claude-code work:

facet modify skill greet \
  --adapter-claude-code '{"permission":{"bash":"ask"}}' \
  --adapter-opencode    '{"model":"..."}'

Setting an adapter replaces that adapter’s block wholesale. Remove one with --remove-adapter-<name>:

facet modify skill greet --remove-adapter-opencode

Adapter flags may accompany --add or --rename, or stand alone. You can also hand-edit the adapters object in facet.json directly; edits round-trip safely because the CLI preserves unknown descriptor fields.

Editing facet metadata

The facet target sets facet-level fields (it takes no asset name). Pass at least one of --name, --description, --version, or --private.

facet modify facet --version 1.0.0 --description "..." --private

Validation

After every mutation the resulting manifest is re-validated before anything is written. A change that would make facet.json invalid (for example, removing the only asset) is rejected and nothing is written.

Rules

• Exactly one lifecycle action per call: --add, --remove, or --rename. Combining them is an error.
• --description and adapter flags may ride along with --add or --rename, or stand alone as an update. --remove takes no field flags.
• Asset flags (--add/--remove/--rename) are not valid for the facet target, and facet-metadata flags (--name/--version/--private) are not valid for asset targets.