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

# facet self-update

> Update the facet CLI to a newer version

## Usage

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet self-update
```

`facet self-upgrade` is an alias of the same command.

## Examples

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet self-update                  # update to the latest published version
facet self-update --version 0.7.0  # pin to a specific version
facet self-update --dry-run        # preview the plan without changing anything
```

The `--dry-run` output reports the current and target versions, the
detected install method, and the exact command that would run if you
re-ran without `--dry-run`.

## Flags

<ResponseField name="--version <x.y.z>" type="string">
  Pin to a specific version instead of latest.
</ResponseField>

<ResponseField name="--dry-run" type="boolean">
  Print the plan; do not modify any files.
</ResponseField>

## Exit codes

| Code  | Meaning                                                                           |
| ----- | --------------------------------------------------------------------------------- |
| `0`   | Successful update, already up to date, or `--dry-run` (any state except dev mode) |
| `1`   | Dev-mode refusal, network error, or malformed registry data                       |
| other | The underlying installer or package manager's exit code, passed through           |

## What it does

Updates the running `facet` binary in place. Detects how the binary was
installed  -- the curl installer, an `npm` / `yarn` / `pnpm` / `bun` global
install, dev mode, or an unclassified location  -- and dispatches to the
matching update mechanism for that path. Existing trust roots (the
[install script](https://agentfacets.io/install) and the user's package
manager) handle download, integrity verification, and the binary swap.

## Install methods

| Detected method | Update command                                    |
| --------------- | ------------------------------------------------- |
| curl installer  | re-runs `agentfacets.io/install` (no PATH change) |
| `npm` global    | `npm install -g agent-facets@<version>`           |
| `yarn` global   | `yarn global add agent-facets@<version>`          |
| `pnpm` global   | `pnpm add -g agent-facets@<version>`              |
| `bun` global    | `bun add -g agent-facets@<version>`               |
| unclassified    | falls back to the curl installer + PATH warning   |

If the binary location can't be classified, `facet self-update` falls back
to the curl installer (which installs to `~/.facet/bin/facet`) and warns
if `facet` on your `$PATH` still resolves to a different binary after the
install  -- so you can decide whether to remove the older copy or reorder
your `$PATH`.

## Dev mode

When the `FACET_BIN_OVERRIDE` environment variable is set (typical in a
workspace shell where you're testing changes via `bun dev`),
`facet self-update` refuses with a clear stderr message and exits with
code `1`. This is intentional: when you've overridden which binary the
launcher executes, you've taken control of binary placement  -- self-update
has no business writing over the path you pointed it at. Unset
`FACET_BIN_OVERRIDE` to update a real install.

## Environment variables

Three variables affect self-update — `FACET_CLI_REGISTRY` (npm registry for version lookup), `FACET_DIR` (where the curl-installed binary lives), and `FACET_BIN_OVERRIDE` (triggers the dev-mode refusal above). See the [environment variables reference](/cli/env) for details.

## See also

* [Environment variables](/cli/env) -- `FACET_CLI_REGISTRY`, `FACET_DIR`, and `FACET_BIN_OVERRIDE` in full.