> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Where the facet CLI stores its state

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.

| 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`](/cli/login) (INI format, mode `0600`)        |

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

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`](/cli/adapters/install#what-it-does).

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.

## `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`](/cli/login);
whitespace-only values are treated as unset. Preferred for CI and
scripts — see [`facet logout`](/cli/logout) for the shell
hygiene caveat.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
export FACET_TOKEN=fct_pub_…
facet publish
```

## `FACET_REGISTRY_URL`

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.

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

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

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