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.