upgrade

Self-update the installed swiftspawn binary by cloning the source repo into a local cache, rebuilding in release mode, and atomically replacing the running binary.

Synopsis

swiftspawn upgrade [--check] [--ref <ref>] [--repo <url>] [--clean]

Description

Because swiftspawn is distributed as source (no signed binaries), upgrade does the same thing you would do by hand: git fetch, checkout latest tag (or origin/main if no tags exist), swift build -c release, then move the result into place.

The cache lives at ~/Library/Caches/swiftspawn/source. Subsequent upgrades reuse the SPM cache, so they’re significantly faster than the first run.

The new binary is installed at the path of the currently running binary (Bundle.main.executablePath). Replacement is atomic via stage + mv -f; the kernel keeps the old inode alive until the current process exits, so the running command finishes cleanly.

If the install directory is owned by root (e.g. /usr/local/bin), re-run with sudo. If you installed to ~/.local/bin, no sudo is needed.

Examples

swiftspawn upgrade
swiftspawn upgrade --check
swiftspawn upgrade --ref main
swiftspawn upgrade --ref v0.2.0
swiftspawn upgrade --repo [email protected]:swiftspawn/swiftspawn-cli.git
swiftspawn upgrade --clean

Options

Flag	Description
--check	Fetch and report status only (“up to date” or “N commit(s) behind”). Does not rebuild or replace anything.
--ref <ref>	Pin to a specific tag or branch instead of “latest tag, falling back to main”.
--repo <url>	Override the source URL. Also reads SWIFTSPAWN_UPGRADE_URL from the environment.
--clean	Delete and re-clone the cache instead of fetching. Use as a recovery escape hatch.

Repo URL precedence

1. --repo <url> flag.
2. SWIFTSPAWN_UPGRADE_URL environment variable.
3. The bundled default (https://github.com/swiftspawn/swiftspawn-cli.git).

For private mirrors or forks, point either of the first two at your URL. SSH URLs ([email protected]:...) are recommended for private repos because they use your existing SSH key without prompting.

Side effects

• Creates ~/Library/Caches/swiftspawn/source on first run.
• Replaces the binary at the install path (atomic rename).

Exit codes

Code	Meaning
1	Unexpected failure (build, clone, fetch, or move failed). Read the printed error.
6	Required tool missing (git or swift).

See also

• Installation for the initial install.
• version
• doctor