ReferenceCLI
vx upgrade
Update vx to the latest release, then refresh the project's vexillum scaffold
Update vx to the latest release, then refresh the project's vexillum scaffold with it.
Usage:
vx upgrade [--channel stable|canary] [--check] [--scaffold-only] [--force] [--yes] [--lang en|es] [--skills | --no-skills]
upgrade works in two steps.
1. The binary. It looks at how vx was installed:
- Homebrew: it runs 'brew upgrade vexillum'.
- The install script (a direct download): it downloads the release archive
for your OS and architecture from GitHub Releases, verifies its sha256
checksum against the release's checksums.txt, and replaces the
executable atomically, keeping its file mode. A checksum mismatch, or a
directory you cannot write to, stops the upgrade with the binary
untouched.
- Anything else (a build from source, a renamed binary): it refuses and
tells you how to reinstall. 'vx upgrade --scaffold-only' still works.
When vx is already on the latest release nothing is replaced, and it
never downgrades. A running sentinel notices the replaced binary and
retires; the next command that needs one starts it from the new binary.
2. The scaffold. The new binary is started to refresh the project's files,
so its own templates apply. It lists the files of yours it will change and
asks for consent first, exactly like 'vx init'. See its help. Then it:
- writes or updates the vexillum block in the file that holds it (AGENTS.md,
or CLAUDE.md when the block lives there), and makes sure CLAUDE.md imports
AGENTS.md when the block is in AGENTS.md. A block you edited is not
overwritten: upgrade prints the diff between yours and the current
template. A malformed block (unbalanced or duplicated markers) is not
touched until you confirm the repairs it lists; the file is saved as
.vexillum/<file>.backup first.
- refreshes the installed skills that are unchanged since vexillum wrote
them (a content hash per skill is kept in .vexillum/config.json) and
reports the ones you edited. When no skill is installed yet it offers to
install them, as init does.
- keeps the sentinel Stop hook current, and creates .vexillum/models.json
if it is missing. An existing models.json is never overwritten, and your
own hooks are kept.
Outside an initialized project only the binary is updated. Without a terminal
the scaffold step asks nothing and does nothing unless --yes is given.
Flags:
--channel stable|canary
Release channel to follow (default stable). stable is the
latest full release; canary is the latest pre-release whose
tag contains -canary. A Homebrew install only follows
stable: install a canary build with the install script's
--channel canary instead.
--check Print the available version and change nothing.
--scaffold-only
Refresh the scaffold and leave the binary alone.
--yes, -y Accept every question, including the repairs to a malformed
block (the file is backed up first).
--force Overwrite what you edited: the vexillum block, an edited
skill. A backup is saved first
(.vexillum/agents-md-slot.backup.md for the block,
.vexillum/backups/skills/<name>/ for a skill).
--lang en|es Language of the block, instead of keeping the block's
current language or detecting it.
--skills Also install the skills that are missing.
--no-skills Leave the skills alone: no install, no refresh.