Genesis Docs

genesis update

Safely update Genesis and switch between stable/beta/dev channels.

If you installed via npm/pnpm/bun (global install, no git metadata), updates happen via the package-manager flow in Updating.

Usage

genesis update
genesis update status
genesis update wizard
genesis update --channel beta
genesis update --channel dev
genesis update --tag beta
genesis update --tag main
genesis update --dry-run
genesis update --no-restart
genesis update --yes
genesis update --json
genesis --update

Options

  • --no-restart: skip restarting the Gateway service after a successful update.
  • --channel <stable|beta|dev>: set the update channel (git + npm; persisted in config).
  • --tag <dist-tag|version|spec>: override the package target for this update only. For package installs, main maps to github:PIXELZX0/Genesis#main.
  • --dry-run: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
  • --json: print machine-readable UpdateRunResult JSON, including postUpdate.plugins.integrityDrifts when npm plugin artifact drift is detected during post-update plugin sync.
  • --timeout <seconds>: per-step timeout (default is 1200s).
  • --yes: skip confirmation prompts (for example downgrade confirmation)

Note: downgrades require confirmation because older versions can break configuration.

update status

Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.

genesis update status
genesis update status --json
genesis update status --timeout 10

Options:

  • --json: print machine-readable status JSON.
  • --timeout <seconds>: timeout for checks (default is 3s).

update wizard

Interactive flow to pick an update channel and confirm whether to restart the Gateway after updating (default is to restart). If you select dev without a git checkout, it offers to create one.

Options:

  • --timeout <seconds>: timeout for each update step (default 1200)

What it does

When you switch channels explicitly (--channel ...), Genesis also keeps the install method aligned:

  • dev → ensures a git checkout (default: ~/genesis, override with GENESIS_GIT_DIR), updates it, and installs the global CLI from that checkout.
  • stable → installs from npm using latest.
  • beta → prefers npm dist-tag beta, but falls back to latest when beta is missing or older than the current stable release.

When no update channel is configured, source checkouts infer the channel from the current checkout: stable tags use stable, beta tags use beta, and branch checkouts use dev.

The Gateway core auto-updater (when enabled via config) reuses this same update path.

For package-manager installs, genesis update resolves the target package version before invoking the package manager. If the installed version exactly matches the target and no update-channel change needs to be persisted, the command exits as skipped before package install, plugin sync, completion refresh, or gateway restart work.

Git checkout flow

Channels:

  • stable: checkout the latest non-beta tag, then build + doctor.
  • beta: prefer the latest -beta tag, but fall back to the latest stable tag when beta is missing or older.
  • dev: checkout main, then fetch + rebase.

High-level:

  1. Requires a clean worktree (no uncommitted changes).
  2. Switches to the selected channel (tag or branch).
  3. Fetches upstream (dev only).
  4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
  5. Rebases onto the selected commit (dev only).
  6. Installs deps with the repo package manager. For pnpm checkouts, the updater bootstraps pnpm on demand (via corepack first, then a temporary npm install pnpm@10 fallback) instead of running npm run build inside a pnpm workspace.
  7. Builds + builds the Control UI.
  8. Runs genesis doctor as the final “safe update” check.
  9. Syncs plugins to the active channel (dev uses bundled plugins; stable/beta uses npm) and updates npm-installed plugins.

If an exact pinned npm plugin update resolves to an artifact whose integrity differs from the stored install record, genesis update aborts that plugin artifact update instead of installing it. Reinstall or update the plugin explicitly only after verifying that you trust the new artifact.

If pnpm bootstrap still fails, the updater now stops early with a package-manager-specific error instead of trying npm run build inside the checkout.

--update shorthand

genesis --update rewrites to genesis update (useful for shells and launcher scripts).

Related