Usage
facet binary in place. facet self-upgrade is an alias.
It detects how the binary was installed and dispatches to that mechanism, so download, verification, and the swap are handled by the installer or package manager you already used. It never reads or writes facets.json, facets.lock, or any materialized asset. To move the facets a project declares, use facet update.
Examples
Flags
string
Install a specific version instead of the latest.
boolean
Print the plan and modify nothing.
Exit codes
This is the one command whose codes are not exclusively its own: it dispatches to the installer or package manager you used, and returns whatever that returns. Treat any non-zero code as a failure and read the output rather than branching on the number.
Output
A--dry-run names the current and target versions, the detected install method, and the exact command that would run.
Details
Install methods
The update path follows how the binary was installed: the curl installer, annpm, yarn, pnpm, or bun global install, or a verified mise install.
If the location cannot be classified, self-update falls back to the curl installer and warns when facet on your PATH still resolves elsewhere afterwards, so you can remove the older copy or reorder your PATH.
Mise installs
Starting with Facet 0.36.4, self-update supports mise installations usinggithub:agent-facets/facets with version_prefix=agent-facets@. See Install with mise for setup.
mise use --path with that config path and the target version.
If mise owns the binary but its provider, options, or configuration cannot be verified, self-update prints manual guidance without changing the configuration or invoking another installer. This guidance currently exits with 0; read the output to distinguish it from a completed update.
Environment
FACET_CLI_REGISTRY sets the npm registry used to look up CLI versions. It is not the facet registry, which is FACET_REGISTRY_URL and has no effect here. See environment variables.
Troubleshooting
self-update refuses in dev mode
self-update refuses in dev mode
Cause:
FACET_BIN_OVERRIDE is set, so you have taken control of which binary runs. Self-update will not write over the path you pointed at.Fix: unset FACET_BIN_OVERRIDE to update a real install.the update ran but facet still reports the old version
the update ran but facet still reports the old version
Cause: another copy of
facet comes first on your PATH, which happens after a fallback install.Fix: the warning names both paths. Remove the older copy, or reorder your PATH.the version list could not be read
the version list could not be read
Cause: the npm registry was unreachable, or returned data the CLI could not parse.Fix: check connectivity and retry. If you point
FACET_CLI_REGISTRY at a mirror, confirm it serves the agent-facets package.mise could not be safely updated automatically
mise could not be safely updated automatically
Cause: mise owns the running binary, but installation metadata is unavailable, invalid, or identifies an unsupported provider or version prefix.Fix: inspect
mise which facet --plugin and your existing mise configuration. Update the Facet entry in that same file manually, preserving its provider, options, and scope. Do not replace it with an unscoped mise use command from an unrelated directory. See supported mise installs.