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.

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: Skip automatic configured runner upgrades.
• --runner: Upgrade only the named configured runner. Repeat to target multiple runners.
• --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 --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 available version from crates.io (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
• 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

Exit code

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

Notes

• The update command is an alias for upgrade with identical behavior.
• Version checking queries the crates.io 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

• version
• extension