godspeed-cli

📖 Documentation: https://godspeedhq.github.io/godspeed-cli/ - the guide, worked examples, publishing, and a full command reference.

godspeed, the developer CLI for GodspeedOS: create, check, build, package, sign and publish Godspeed software on your workstation, against the public contracts of a GodspeedOS release - and fetch anyone's published package with every signature checked.

godspeed new service hello && cd hello
godspeed build --all          # one binary per architecture: x86_64, aarch64, armv7, riscv64
godspeed publish              # signed, uploaded, and installable as you/hello

The rules the CLI is built to are in CLAUDE.md.

Status: the first half of the workflow works end to end - create, check, build, test (libraries), package, sign, publish, fetch - against the live registry, and a Godspeed machine (GodspeedOS 0.29.0 and later) fetches and installs what you publish. What waits on the OS is godspeed run, booting a machine with your program already on it, and so a program's godspeed test (below). Godspeed programs are written in Rust today (why, and what about C, C++ or Go).

Install

Linux or macOS:

curl --proto '=https' --tlsv1.2 -sSf https://github.com/godspeedhq/godspeed-cli/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/godspeedhq/godspeed-cli/releases/latest/download/install.ps1 | iex

Either installs one prebuilt binary to ~/.godspeed/bin (%USERPROFILE%\.godspeed\bin on Windows), after checking it against the release's SHA256SUMS - a mismatch, or no way to check, installs nothing - and adds that folder to your PATH, saying which files it changed. Both scripts are short and say at the top what they do; read them first if you like (install/). Settings: GODSPEED_VERSION, GODSPEED_INSTALL_DIR, GODSPEED_NO_MODIFY_PATH=1. Builds exist for x86_64 and Arm64 Linux (static, any distribution), macOS on Apple silicon and Intel, and x64 and Arm64 Windows.

(Builds of the CLI for armv7 and riscv64 Linux hosts - a Raspberry Pi on a 32-bit OS, a VisionFive on Debian - would be cheap to add: two more static cross-builds. They are left out because GitHub has no runners for either, so they could only be tested under emulation. Packages, the programs the CLI builds, target all four Godspeed architectures regardless.)

Updating, as with rustup:

godspeed self update

It downloads the latest release's build for your machine and the release's SHA256SUMS, checks one against the other, runs the new binary to confirm it works, and only then swaps it in for the old one, in a single rename - until then nothing has changed. (0.1.0 predates it: update that one by running the installer again, which does the same checks. The installer, with GODSPEED_VERSION, is also how to go to a particular or older version.) The CLI also tells you when there is something to update to: at most once a day it asks GitHub which release is the latest - in the background, never slowing or failing a command - and if it is newer, says so after the command's output. It sends nothing but that request; it stays quiet in scripts, pipes and CI; GODSPEED_NO_UPDATE_CHECK=1 turns it off; and godspeed doctor asks on demand.

Uninstalling: godspeed self uninstall removes the binary, its folder, and the PATH entries the installer added, after listing them and asking (--yes to skip the question). It keeps your configuration directory - your signing key, tokens and trust records - and says where it is. A copy built with cargo install belongs to Cargo: self update and self uninstall point you to cargo install and cargo uninstall godspeed-cli instead.

Or build it yourself with Rust:

cargo install --git https://github.com/godspeedhq/godspeed-cli --tag <release tag> --locked godspeed-cli

where <release tag> is the latest release's, cli-v and its version (releases).

A checksum proves a download is the file the release lists; releases are not signed yet.

Setup

godspeed doctor

That is all: no clone of the OS. The CLI builds against a GodspeedOS release - its stdlib, its pinned Rust toolchain, its target list, its compiler flags, its service linker script and its contract schema - and fetches the few small files that say those things the first time it needs a release, then keeps them (the platform kit, in ~/.cache/godspeed/platform/<release>/; %LOCALAPPDATA% on Windows). Each kit comes from one commit of the release's tag and records every file's SHA-256; a damaged one is fetched again, never used. After that, the network is not needed.

Which release: godspeed new uses the latest (or --os-release 0.28.0), and a project keeps using the release it was created with - the stdlib tag in its Cargo.toml - until you change that tag. godspeed doctor says what is missing and the command that fixes it.

Working on GodspeedOS itself? Point the CLI at your checkout instead, with --os <path> or GODSPEED_OS; it is read, never written. (Why kits, and what comes next: docs/no-checkout.md.)

Releasing

Push a tag cli-v<version>, equal to the version in Cargo.toml. .github/workflows/release.yml builds all six binaries, runs each where it can, tests both installers against exactly those binaries on Linux, macOS and Windows, and then creates a draft release. Nothing is public until the draft is published; the installers' releases/latest never resolves to a draft.

Documentation

The guide is at godspeedhq.github.io/godspeed-cli:

This is the beginning of the README. Read the rest at the original. Read the full README ↗