Reference
Every command, option, environment variable, file and exit code. godspeed help
<command> says the same, offline.
Commands
Making and building
| Command | What it does |
|---|---|
new service <name>new utility <name>new app <name>new driver <name>new library <name> | Create the smallest valid project of that kind, against the OS release you build with (What you can make has each). --os-release <version> picks the GodspeedOS release (default: the latest); --dir puts it elsewhere; --publisher <you> fills in the publisher, so it can be packaged straight away (never for a library, which is not packaged). A driver needs GodspeedOS v0.30.0 or later; the template, which asks for an interrupt and a DMA arena, v0.31.0 or later. |
check | Validate the project, its toolchain pin, its stdlib release, and its contract against the OS's schema - without building. |
build [--arch <isa> | --all] | Build for one architecture (default x86_64; also aarch64, armv7, riscv64) or every one the OS supports. A program gives one ELF per architecture; a library, an rlib. |
test | Run a library's tests on your workstation. Refused for a service, a utility, an app or a driver, which run only on a Godspeed machine. |
run [--target qemu|hardware] | Refused, with the reason: there is no public way yet to boot a Godspeed machine with your program on it. Meanwhile package --local and godspeed install on the machine run it. |
doctor [--json] | Check your environment: this CLI's version against the latest release, the OS checkout, the pinned toolchain, every target, QEMU. Says the command that fixes each problem. |
This CLI itself
| Command | What it does |
|---|---|
self update | Download the latest release's build for this machine and its SHA256SUMS, check one against the other, run the new binary, and only then swap it in, in one rename. A checksum mismatch, or a binary that does not run, changes nothing. |
self uninstall [--yes] | Remove this binary, the installer's folder and the PATH entries the installer added, after listing them and asking. Keeps your configuration directory: your signing key, tokens and trust records. |
A copy built with cargo install belongs to Cargo; both commands point you to Cargo instead.
| Command | What it does |
|---|---|
completions <shell> | Print a tab-completion script for bash, zsh, fish, powershell or elvish. godspeed completions --help shows the line to add to your shell's startup file. |
Packaging and verifying
| Command | What it does |
|---|---|
package [--arch <isa>] [--out <dir>] [--local] [--json] | Build every architecture and write a package directory (default target/package/<publisher>-<name>-<version>), then verify it from disk before reporting it. Needs publisher in godspeed.toml. --local also signs it with your key and writes one <name>-<version>.gsp file, for a machine whose operator trusts your key: no registry and no network on either side. |
verify <dir> [--json] | Check every file of a package directory against its manifest, and its signature if it has one. Needs no OS checkout and no registry. |
sign <dir> | Sign a package directory with your key (writes manifest.sig) and verify the result. publish does this for you. |
fetch <publisher/name>[@version] [--out <dir>] [--trust-root sha256:...] [--offline [--arch <isa>|all]] [--json] | Download a release (default: the highest version) and verify it through the registry's whole chain of trust before keeping it. The official registry's root is built in; --trust-root pins another's. --offline writes the release and every document that checked it as one .gsp file, which a machine with no network installs. |
inspect <file>.gsp | <publisher/name>[@version] [--trust-root sha256:...] [--json] | Check a .gsp file offline, or a release on the registry, exactly as installing it would - and keep nothing. |
Publishing
| Command | What it does |
|---|---|
key generate | Make your Ed25519 signing key. Never replaces an existing one. |
key show | Print your public key, for the registry maintainer. |
login [--with-token] | Make a publisher token on this machine, store it, and print its fingerprint for the maintainer to approve. Again later: says whether it is approved. --with-token stores an existing token instead, read from the terminal or standard input, after checking it. |
token new | Make a token for CI: printed once, stored nowhere. |
whoami [--json] | Your account, the namespaces you may publish under, and when your token expires. |
publish [--dry-run] | Package, sign, reserve, upload and finalise. If finalising gets no answer, reads the registry's index and reports what it finds. Always safe to run again. --dry-run does everything up to the upload - package, sign, authenticate, check the namespace, look the version up in the index - and says what publishing would do. |
logout | Revoke the token at the registry and remove it from this machine. |
Belonging to a Godspeed machine
install, search, info, list, update,
upgrade and uninstall belong to a Godspeed machine, not to this CLI. This CLI recognises them and says so
(exit 22), rather than doing something else under their name.
The machine's own package manager, at its gsh> prompt, has search,
info, list, fetch, verify, inspect,
plan, resolve, install, upgrade, uninstall,
remove, cleanup, trust, registry, config and
check. It has no update: a newer release is godspeed upgrade, and
godspeed list updates shows what has one.
Options every command takes
| Option | Meaning |
|---|---|
--os <path> | A GodspeedOS checkout to build against, instead of the platform kit for the project's release. Default: GODSPEED_OS. For working on the OS itself. |
--registry <url> | The registry. Default: GODSPEED_REGISTRY, then the last login, then the official registry. |
Environment variables
| Variable | Meaning |
|---|---|
GODSPEED_OS | Path to a GodspeedOS checkout, used instead of the platform kit. Read, never written. |
GODSPEED_CACHE_DIR | Where the CLI keeps platform kits, in place of the default below. |
GODSPEED_REGISTRY | The registry URL. |
GODSPEED_TOKEN | A publisher token, in place of the stored one (for CI). |
GODSPEED_SIGNING_KEY | Your signing key's secret, in place of signing-key.toml (for CI). |
GODSPEED_CONFIG_DIR | Where the CLI keeps its files, in place of the default below. |
NO_COLOR | Set to anything to print diagnostics without colour. (Colour is used only on a terminal.) |
GODSPEED_NO_UPDATE_CHECK | Set to 1 to stop the once-a-day check for a newer release. It is also skipped when CI is set or stderr is not a terminal. |
Files
In ~/.config/godspeed/ (or $XDG_CONFIG_HOME/godspeed/; on Windows
%APPDATA%\godspeed\), each readable by you alone:
| File | Holds |
|---|---|
signing-key.toml | Your signing key. Back it up; never share it. |
credentials.toml | Your token for each registry, and which registry is the default. |
update-check.toml | When this machine last asked for the latest release, and the answer. Delete it and the next command asks again. |
trust/ | For each registry, the root of trust this machine accepted and the newest metadata versions it has seen, so it can never be sent back to older ones. |
In ~/.cache/godspeed/ (or $XDG_CACHE_HOME/godspeed/; on macOS
~/Library/Caches/godspeed/; on Windows %LOCALAPPDATA%\godspeed\cache\), only what can be
fetched again:
| File | Holds |
|---|---|
platform/<release>/ | The platform kit for one GodspeedOS release: the OS's toolchain pin, compiler flags, linker script, contract schema and version files, from one commit of the release tag, with each file's SHA-256 in kit.toml. A kit that no longer matches is removed and fetched again. self uninstall removes them. |
A project's files
godspeed.toml # what kind of project this is, where its contract is, and the publisher, # description and license a package of it carries Cargo.toml # how Rust builds it; depends on the `godspeed` stdlib at an OS release tag contracts/<name>.toml # (services) the OS service contract: the authority it REQUESTS rust-toolchain.toml # the compiler that OS release is built with src/
And a package directory, as package writes it and verify checks it:
manifest.toml # name, version, kind, publisher, and the size and SHA-256 of every file manifest.sig # the publisher's signature over the manifest contract.toml # (services) the contract, as built x86_64.elf aarch64.elf armv7.elf riscv64.elf
The format is defined in package-format.md, independent of any registry.
Exit codes
Scripts and CI can tell failures apart without reading the text.
doctor, verify, package, fetch, inspect and whoami take --json: the result is
one JSON document on stdout, and a refusal is one on stderr -
{"errors": [{"kind", "exit_code", "stage", "headline", "reason", "expected", "next"}]} - with
the same exit code. kind is a stable name for the code, such as not-found for
28.
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | The command line itself was wrong |
| 10 | Invalid project |
| 11 | Environment: no OS checkout, toolchain or target missing |
| 12 | Unavailable target or architecture |
| 13 | A dependency could not be fetched |
| 14 | Compilation failure |
| 15 | Test failure |
| 16 | Invalid package: a missing or extra file, a manifest that breaks the format |
| 17 | Integrity failure: a size or checksum mismatch |
| 18 | Authentication failure: not logged in, or the token is unknown, revoked or expired |
| 19 | The registry (or, for self update, GitHub) could not be reached, before anything was changed |
| 20 | GodspeedOS does not provide this yet |
| 21 | This CLI does not implement this yet |
| 22 | This is the native package manager's command, not this CLI's |
| 23 | Permission denied: the namespace is not yours, or the key is not listed for it |
| 24 | Conflict: the version is already published, or being published |
| 25 | Outcome unknown: finalising got no answer and the index does not show it yet - run publish again |
| 26 | Signature failure: a signature is malformed, or the named key did not sign this manifest |
| 27 | Untrusted: the registry's signed metadata does not vouch for it - an unknown, retired or revoked key, or metadata that is unsigned, expired, rolled back or inconsistent |
| 28 | Not found: the registry has no such package, or no such version of it |
| 29 | Cancelled: you declined, or there was no terminal to ask and --yes was not given; nothing was changed |
| 30 | A local file could not be read or written |