Skip to main content

​
Usage

facets install [name]

​
Arguments

ArgumentDescription
nameName of the facet to install (optional)
If no name is provided, installs all declared facets that aren’t already installed.

​
What it does

Installs a facet by copying its resources into your project’s .opencode/ directory. The process:
  1. Resolve — Looks for the facet in local sources (.facets/<name>/) first, then the cache (~/.cache/facets/<name>/)
  2. Load — Reads and validates facet.yaml
  3. Prereq checks — If the manifest declares requires, you’re prompted to approve running the commands. Each command is executed (e.g., gh --version) and must succeed. Approval is cached at ~/.local/state/facets/prereqs/<name> so you’re only asked once per unique set of requirements.
  4. Copy resources to .opencode/:
ResourceSourceDestinationProcessing
Skillsskills/<name>/SKILL.md.opencode/skills/<name>/SKILL.mdVerbatim copy
AgentsPrompt file.opencode/agents/<name>.mdYAML frontmatter assembled from manifest
CommandsPrompt file.opencode/commands/<name>.mdYAML frontmatter assembled from manifest
Toolsopencode/tools/<name>.ts.opencode/tools/<name>.tsVerbatim copy

​
Example

# Install a specific facet
facets install viper
# Installed: viper
#   skill: viper-planning
#   agent: viper-agent

# Install all uninstalled facets
facets install

​
Prerequisite checks

When a facet declares requires, Facets runs those commands to verify dependencies are available. For example: 
requires:
  - gh --version
  - jq --version
The CLI will prompt before running these checks. Once approved and verified, the result is cached — if the requires list changes in a future update, you’ll be prompted again.

​
Failure modes

The install result is a discriminated union:
ResultMeaning
successResources installed successfully
not_foundFacet not found in local sources or cache
prereqA prerequisite command failed
copyA resource file couldn’t be copied