Skip to main content
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.

​
FACET_DIR

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. Default: ~/.facet/. Setting FACET_DIR is the only override; there are no per-subsystem variables.
Each adapter directory is a managed installation. Its installation.json records the active generation, the verified adapter SDK API, and the source it came from. Replacements stage a new generation and switch over atomically. See facet adapter add. 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.

​
Install receipt

$FACET_DIR/receipts/ holds one record per project, identified by the project’s path. It tracks what this machine materialized and which MCP declarations you approved. It is deliberately outside your repository. Only this record authorizes deleting a file, so a lockfile pulled from a teammate never causes the CLI to delete something it did not write, and an approval never travels to another machine. There is nothing to commit and nothing to run: an ordinary successful install rewrites it as part of the same atomic write as facets.json and facets.lock.
A frozen install is the exception. It reproduces a locked set it already verified, so if the receipt cannot be written, for example when its directory cannot be created or the existing record is unreadable, the run still succeeds and warns that its assets stay untracked. Untracked files are not deleted by a later facet remove. Fix the cause and run a normal facet install to record them again.

​
FACET_TOKEN

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.

​
FACET_REGISTRY_URL

Overrides the facet registry base URL (default https://api.agentfacets.io). The value is an origin only, with 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.

​
FACET_BIN_OVERRIDE

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.
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.

​
FACET_CLI_REGISTRY

Overrides the npm registry base URL the curl installer and self-update use to fetch CLI tarballs. Defaults to https://registry.npmjs.org.

​
FACET_VERSION

Read by the curl installer (install.sh) as an alternative to --version. If both are set, the flag wins.