Upgrading

vx upgrade does two things, in this order: it updates the vx binary itself, then it refreshes the files vexillum scaffolded into the current project, using the new binary so its templates are the ones that apply.

vx upgrade

To see what a version brings, read its notes on the GitHub releases page. That page is the only place release notes live.

The binaryCopy Anchor Link

How vx was installed decides what upgrade does. It resolves the path of the running executable and picks one of three cases:

upgrade stops, with the binary untouched, when the checksum does not match, when the release has no archive for your platform, or when the directory that holds vx is not writable. For the last case it tells you to reinstall into a directory you own: run the install script with VX_INSTALL_DIR set to it.

When vx is already on the latest release it leaves the binary alone, and upgrade never downgrades. It still refreshes the project's scaffold.

A sentinel that is already running notices that its binary was replaced and retires, and the next command that needs one starts it from the new binary. You do not restart it yourself. See Sentinel.

ChannelsCopy Anchor Link

--channel picks which releases upgrade follows. There are two:

vx upgrade --channel canary

A Homebrew install only follows stable. To follow canary, install a canary build with the install script instead, and use the command above to keep it current. See Release channels. To go back to the stable releases, run vx upgrade --channel stable: it installs the latest stable release once that is newer than the version you have.

Check without changing anythingCopy Anchor Link

vx upgrade --check

prints the version that is available on the channel and changes nothing: not the binary, not the project.

A project's scaffoldCopy Anchor Link

A new binary may ship a newer commander core, newer skills or a newer hook. After the binary step, upgrade refreshes the project you ran it in. Outside an initialized project it only updates the binary.

The refresh works like init: it lists the files of yours it will change and asks first (Continue? [Y/n]). 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, when the block is in AGENTS.md, makes sure CLAUDE.md imports it. A block you edited is not overwritten: upgrade prints the diff between yours and the current template. A malformed block is not touched until you confirm the repairs it lists, and the file is saved to .vexillum/AGENTS.md.backup (or .vexillum/CLAUDE.md.backup) first. See The AGENTS.md slot;
• 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. See Skills;
• Keeps the sentinel Stop hook current, so it finds vx even when it is not on the PATH of the hook's shell (the command also tries ~/.local/bin, Homebrew and /usr/local/bin). Your own Stop hooks are kept. See Sentinel;
• Creates .vexillum/models.json if it is missing. An existing one is never overwritten: it is yours. See models.json.

Without a terminal the refresh asks nothing and changes nothing unless you pass --yes.

To refresh only the scaffold and leave the binary alone, for example offline or in a script, run:

vx upgrade --scaffold-only

FlagsCopy Anchor Link

See the vx upgrade reference.