Skip to content
Builderforce.ai Builderforce.ai BuilderForce Agents Docs

update

builderforce update

Section titled “builderforce update”

Safely update BuilderForce Agents and switch between stable/beta/dev channels.

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

Usage

Section titled “Usage”
Terminal window
builderforce update
builderforce update status
builderforce update wizard
builderforce update --channel beta
builderforce update --channel dev
builderforce update --tag beta
builderforce update --no-restart
builderforce update --json
builderforce --update

Options

Section titled “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>: override the npm dist-tag or version for this update only.
  • --json: print machine-readable UpdateRunResult JSON.
  • --timeout <seconds>: per-step timeout (default is 1200s).

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

update status

Section titled “update status”

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

Terminal window
builderforce update status
builderforce update status --json
builderforce update status --timeout 10

Options:

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

update wizard

Section titled “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.

What it does

Section titled “What it does”

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

  • dev → ensures a git checkout (default: ~/builderforce, override with BUILDERFORCE_AGENTS_GIT_DIR), updates it, and installs the global CLI from that checkout.
  • stable/beta → installs from npm using the matching dist-tag.

Git checkout flow

Section titled “Git checkout flow”

Channels:

  • stable: checkout the latest non-beta tag, then build + doctor.
  • beta: checkout the latest -beta tag, then build + doctor.
  • 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 (pnpm preferred; npm fallback).
  7. Builds + builds the Control UI.
  8. Runs builderforce doctor as the final “safe update” check.
  9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.

--update shorthand

Section titled “--update shorthand”

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

See also

Section titled “See also”