Environment Variables

A small set of environment variables controls where the facet CLI writes state, how it authenticates, and which binary the launcher runs. FACET_DIR, FACET_TOKEN, and FACET_REGISTRY_URL are user-facing; the rest are for CLI development and specialized installs. The single base directory for everything the facet CLI manages on disk: the content-addressed cache, installed adapters, install advisory locks, and (for curl installs) the binary itself.

Path	Purpose
`$FACET_DIR/bin/`	Curl-installed binary (`$FACET_DIR/bin/facet`)
`$FACET_DIR/cache/`	Content-addressed cache for fetched facet payloads
`$FACET_DIR/adapters/`	Managed adapter installations (`installation.json` receipt + `generations/<id>/adapter.js`)
`$FACET_DIR/locks/`	Advisory locks: per-project install locks and per-adapter replacement locks
`$FACET_DIR/receipts/`	Machine-local install receipts (one per project, tracks materialized state)
`$FACET_DIR/credentials`	Registry credential written by `facet login` (INI format, mode `0600`)

Default: ~/.facet/. Setting FACET_DIR is the override — there are no separate per-subsystem env vars.

export FACET_DIR=/opt/facet
facet adapter install opencode
# adapter lands in /opt/facet/adapters/opencode/generations/<id>/adapter.js
# with its receipt at /opt/facet/adapters/opencode/installation.json
# cache lands in /opt/facet/cache/<name>@<version>/
# install locks land in /opt/facet/locks/<basename>-<hash>.lock
# adapter replacement locks land in /opt/facet/locks/adapter-<name>-<hash>.lock

Each adapter directory is a managed installation: the installation.json receipt records the active generation, the verified adapter API, and the source provenance used to install it (specifier, resolved npm package/version, integrity). Replacements stage a new generation and switch the receipt atomically — see facet adapter install. Whitespace-only values (FACET_DIR=, FACET_DIR=" ") are treated as unset so a misconfigured shell rc doesn’t accidentally point everything at a relative path. Surrounding whitespace is trimmed. A registry credential (a fct_pub_… personal access token) supplied via the environment. When set to a non-empty value it takes precedence over the credentials file written by facet login; whitespace-only values are treated as unset. Preferred for CI and scripts — see facet logout for the shell hygiene caveat.

export FACET_TOKEN=fct_pub_…
facet publish

Overrides the facet registry base URL (default https://api.agentfacets.io). The value is an origin only — no path suffix — and trailing slashes are stripped. Empty values are treated as unset. Not to be confused with FACET_CLI_REGISTRY below, which is the npm registry the installer fetches CLI tarballs from. A direct override of the binary the launcher executes. When set, the launcher skips its normal resolution (cached hard-link, platform package lookup, etc.) and runs the binary at the override path.

export FACET_BIN_OVERRIDE=/home/me/dev/facets/packages/cli/dist/facet
facet --version   # runs the binary at the override path

Setting FACET_BIN_OVERRIDE also disables facet self-update: when you’ve overridden which binary runs, self-update has no business writing over whatever you pointed it at. Unset the variable to re-enable self-update for a real install. This variable is primarily for CLI development. End users should not set it; if you want to control where the curl installer puts the binary, set FACET_DIR instead. Overrides the npm registry base URL the curl installer and self-update use to fetch CLI tarballs. Defaults to https://registry.npmjs.org. Read by the curl installer (install.sh) as an alternative to --version. If both are set, the flag wins.

CLI Reference

Facet Management

Adapters

Authentication

Authoring

CLI

`FACET_DIR`

`FACET_TOKEN`

`FACET_REGISTRY_URL`

`FACET_BIN_OVERRIDE`

`FACET_CLI_REGISTRY`

`FACET_VERSION`

​FACET_DIR

​FACET_TOKEN

​FACET_REGISTRY_URL

​FACET_BIN_OVERRIDE

​FACET_CLI_REGISTRY

​FACET_VERSION