# Updating & releasing (/docs/updating)



`warden update` does the right thing for however warden was built (`warden version` shows which):

| Build                                                          | `warden update`                                                                                                                                                                                                                                             |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **dev** — running from source                                  | compiles a `local` binary from this checkout → `~/.local/bin/warden`                                                                                                                                                                                        |
| **local** — compiled from a checkout                           | rebuilds from the checkout it was built from, in place (`--release` switches to releases)                                                                                                                                                                   |
| **release** — downloaded from GitHub                           | `gh release view` → newer? download `warden-<os>-<arch>` → verify sha256 → self-check → swap in place. If GitHub releases can't be reached (no `gh`, no repo access), it falls back to npm                                                                  |
| **release** — copied by `npx`/`bunx @delacour/warden install`  | npm registry: `@delacour/warden/latest` → newer? download `@delacour/warden-<os>-<arch>` → verify sha512 `dist.integrity` → self-check → swap in place                                                                                                      |
| **npm** — `@delacour/warden` via npm / bun / pnpm / npx / bunx | prints the package manager's upgrade command (`npm i -g @delacour/warden@latest`, `bun add -g @delacour/warden@latest`, `npx @delacour/warden@latest install`, …) and leaves `node_modules` alone. `--to <path>` still installs a standalone release binary |

The binary is swapped atomically at the same path, so the next `warden` in your current shell runs the new version — no new shell needed. If `PATH` resolves `warden` elsewhere, update warns you.

Flags: `--check` (report only), `--release` (install the latest GitHub release; also switches a dev / local build to it), `--force`, `--to <path>` (install the binary there instead), `--json`. GitHub releases come from the public `delacournz/warden` repo through the `gh` CLI; set `WARDEN_RELEASE_REPO` to use another, and `WARDEN_NPM_REGISTRY` for another npm registry.

## Releasing [#releasing]

<Steps>
  <Step>
    A PR into 

    `develop`

     that changes what 

    `@delacour/warden`

     ships adds a changeset with 

    `bun changeset`

    . Pick 

    `@delacour/warden`

     only; 

    `@delacour/warden-e2e`

     follows in lock-step. The one-line summary becomes the changelog entry.
  </Step>

  <Step>
    Every push to 

    `develop`

     opens or updates the "chore(release): vX.Y.Z" PR, titled with the version it will ship. It bumps 

    `apps/cli/package.json`

     and 

    `packages/e2e/package.json`

    , writes both 

    `CHANGELOG.md`

     files and consumes the changesets. Its 

    `signoff`

     status is written automatically.
  </Step>

  <Step>
    Merge the version PR. 

    `.github/workflows/promote.yml`

     fast-forwards 

    `main`

     to that commit and pushes tag 

    `v<version>`

    . The docs site deploys from 

    `main`

    .
  </Step>

  <Step>
    The tag runs 

    `.github/workflows/release.yml`

    . It checks the tag matches the version and is on 

    `main`

    , runs typecheck / check / test, builds 

    `warden-{darwin,linux}-{arm64,x64}`

    , the 

    `warden-simd`

     iOS driver helper and 

    `checksums.txt`

    , and publishes the GitHub release.
  </Step>

  <Step>
    The same workflow stages the npm packages (

    `bun run --cwd apps/cli build:npm`

    ) and publishes 

    `@delacour/warden-<os>-<arch>`

    , then 

    `@delacour/warden`

    , then 

    `@delacour/warden-e2e`

    , with public access, provenance and repository links. Publishing uses npm trusted publishing (OIDC) from the 

    `release`

     environment, so no token is stored. Versions already on npm are skipped.
  </Step>
</Steps>

Never edit `version` by hand. `bun run release <version>` is a break-glass for when CI is down. It bypasses changesets and the version PR, and its tag still goes through the normal tag ruleset.