Setup & Prerequisites

Install the CLI, an adapter, and a token

What you need before adding, authoring, or publishing facets. If you just want to try a facet, the Quickstart is faster.

1. Install the CLI

   curl

   curl -fsSL https://agentfacets.io/install | bash
   

   npm install -g agent-facets
   

   bun add -g agent-facets
   

   Keep it current with facet self-update — the newer authoring commands need v0.24.0+:

   facet --version
   facet self-update   # update in place if needed
   
2. Connect an adapter (required before adding facets)

   A facet is only useful once it’s materialized into an AI tool, which the adapter handles. Install one per machine with facet adapter install:

   facet adapter install claude-code   # or: opencode, codex
   facet adapter list
   

   Without an adapter, facet add shows a picker in a terminal — and fails in a non-interactive shell (CI). Install one first.

3. Create a registry account + token

   Adding public facets needs no account. A token is what unlocks the rest: publishing your own facets, plus accessing private or organization-owned facets you’re authorized to use. Sign up at agentfacets.io and create a personal access token (PAT) in your account settings. Sign in with facet login and confirm with facet whoami:

   facet login                     # interactive; stores the token
   export FACET_TOKEN=fct_pub_…    # or, preferred for CI/scripts
   facet whoami                    # confirm the signed-in identity
   

Verify your setup

facet --version        # CLI is installed and recent
facet adapter list     # at least one adapter connected
facet whoami           # signed in (needed to publish and to reach private facets)

Next steps

Install facets

Add, pin, reinstall, and remove facets.

Create your first facet

Scaffold, author, build, and verify.