Synopsis

homeboy upgrade [OPTIONS]

Description

Upgrades Homeboy to the latest version. The command auto-detects the installation method (Homebrew, Cargo, source build, or downloaded release binary) and runs the appropriate upgrade process.

By default, after a successful local upgrade, Homeboy also checks configured SSH runners and runs their configured Homeboy binary through the same upgrade path. This keeps lab runners from drifting behind the local CLI.

Runner sync uses this contract:

• Run each configured SSH runner through its configured homeboy_path, falling back to bare homeboy only when no path is configured.
• Sync every parent extension that has portable source metadata (source_url plus source_revision) to the runner.
• Isolate extension sync failures per extension so one failed extension does not prevent later extensions from being attempted.
• Report configured homeboy_path versus bare homeboy version drift when both can be observed.
• Report a stale connected runner daemon when the daemon session version no longer matches the configured runner executable version.

Options

• --check: Check for updates without installing. Returns version information without making changes.
• --force: Force upgrade even if already at the latest version.
• --skip-extensions: Skip automatic extension updates.
• --skip-runners: Upgrade the controller only; cannot be combined with --upgrade-runner.
• --upgrade-runner: Select configured runners to converge with the controller upgrade. Repeat to target multiple runners.
• --runner-only: With --upgrade-runner, preserve the controller and refresh only the selected runners. The response explicitly reports this partial scope and the exact controller-plus-runner convergence command.
• --method: Override install method detection (homebrew|cargo|source|binary).
• --version <TAG>: Pin the published release to install (v0.332.0 or 0.332.0). Binary installs only, and it implies --force at the release gate so a deliberate downgrade is not discarded as "already at latest".

Release selection for binary installs

Binary installs download a release asset named homeboy-<target triple>.tar.xz, plus its .sha256 sidecar. A release published without this platform’s pair cannot be installed here, so upgrade does not simply resolve the newest tag:

• --check verifies an installable artifact, not just a newer version string. latest_version is the newest release carrying an artifact for the running target, and update_available is keyed off it. A release this platform cannot install is never reported as available.
• Selection falls back to the newest release that does have this target’s asset, and says so: v0.333.0 has no x86_64-unknown-linux-gnu asset; upgrading to v0.332.0 instead.
• --version <TAG> pins deliberately. A pin to a release with no asset for this target is refused before any binary mutation, naming the asset it looked for and the releases that would work.
• The target triple is detected honestly. An OS/architecture pair Homeboy publishes no assets for is reported as undetermined; asset availability is then explicitly not verified rather than guessed.
• A 404 names the resolved asset URL and the target triple it looked for, so diagnosing a missing asset does not require listing release assets by hand.

The installer honors HOMEBOY_UPGRADE_RELEASE_TAG to download from a specific tag instead of releases/latest/download; upgrade sets it from the release it selected.

Controllers released before the bootstrap admission contract can recover without running their legacy upgrade command by invoking the pinned release installer:

curl -fsSL https://github.com/Extra-Chill/homeboy/releases/download/v<fixed-version>/homeboy-installer.sh | sh

The installer stages the candidate, has that candidate read durable ownership with the legacy controller identity, and only replaces the installed binary when the candidate admission succeeds.

Installation Method Detection

Homeboy detects how it was installed and uses the appropriate upgrade method:

If the installation method cannot be detected, an error is returned with manual upgrade instructions. You can also override detection:

homeboy upgrade --method binary

Examples

Check for updates:

homeboy upgrade --check

Upgrade to the latest version:

homeboy upgrade

Force reinstall:

homeboy upgrade --force

Pin a specific published release (binary installs):

homeboy upgrade --version v0.332.0

Upgrade only a specific runner after the local upgrade:

homeboy upgrade --upgrade-runner lab

Upgrade locally without touching configured runners:

homeboy upgrade --skip-runners

JSON output

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract.

• command: upgrade.check
• current_version: Current installed version
• latest_version: The release an upgrade would install. For asset-installed methods this is the newest release carrying an artifact for target. Null when the network check failed, or when no published release ships this target’s artifact
• update_available: Boolean indicating if an installable update is available
• install_method: Detected installation method (homebrew, cargo, source, or unknown)
• target: Running target triple. Omitted when the OS/architecture pair could not be identified, which means asset availability was not verified
• newest_version: Newest published release, whatever its asset inventory. Equal to latest_version on a healthy release train
• uninstallable_versions: Releases newer than latest_version passed over for want of a target asset, newest first
• notice: Plain-language explanation when latest_version is not the newest release, when nothing installable was found, or when the target could not be determined

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract.

• command: upgrade
• install_method: Installation method used for upgrade
• previous_version: Version before upgrade
• new_version: Version after upgrade (may be null)
• upgraded: Boolean indicating if upgrade was performed
• partial: Present and true when a selected runner did not converge with the controller
• message: Human-readable status message
• restart_required: Boolean indicating if a restart is needed (true only for source installs)
• extensions_updated: Extension upgrade entries when installed extensions were checked
• extensions_skipped: Extension IDs that could not be updated
• projects_migrated: Project config migration entries
• runners_updated: Runner upgrade entries for configured runners that completed successfully
• runners_skipped: Runner upgrade entries for configured runners that failed or could not verify a version

homeboy upgrade --check data payload:

Exit code

• 0: Success (upgrade completed or already at latest)
• Non-zero: Error during upgrade process

Notes

• Version checking queries the GitHub Releases API. Network failures are handled gracefully.
• On Unix platforms, successful source installs automatically restart into the new binary. Binary and package-manager installs do not require a restart.

Related

• release
• extension