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.
• --no-restart: Skip automatic restart after upgrade. Useful for scripted environments.
• --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).

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

Upgrade without auto-restart:

homeboy upgrade --no-restart

Force reinstall:

homeboy upgrade --force

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: Latest GitHub Release version (may be null if network fails)
• update_available: Boolean indicating if an update is available
• install_method: Detected installation method (homebrew, cargo, source, or unknown)

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