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, or annpm, yarn, pnpm, or bun global 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.
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.