🚀 godspeed 0.5.0

🚀 godspeed 0.5.0 - drivers with an interrupt and a DMA arena

The developer CLI for GodspeedOS, released alongside
GodspeedOS v0.31.0. That OS release gives a driver package its device's interrupt, a DMA arena, a
device taken over from the built-in driver, and USB devices. This CLI's driver template uses the first two.

godspeed new driver sensor        # 🔌 now waits for its interrupt and owns a DMA arena

Updating from 0.4.0: godspeed self update.

📖 What a driver package can be given, and how it is shown on every board: Driver packages (GodspeedOS docs/developer-services-design.md 13.1) · 🧭 Making a driver, end to end

✨ What's new

🔌 The driver template takes its interrupt and a DMA arena

• 🔔 hw_pci_irq = true in its contract, and it waits with gs::driver::irq instead of polling.
• 🧱 hw_dma = "...", laid out by name with gs::driver::arena, never an address.
• ✅ It needs GodspeedOS v0.31.0 or later: godspeed check against v0.30.0 refuses hw_dma, by name.

🧭 The machine's verbs, said right

• ⬆️ upgrade is a verb on the machine, not on your workstation. Typing it here says to run it at the gsh>
  prompt (exit 22, like the other machine verbs). update isn't a verb anywhere, and points you to
  upgrade, list updates and self update.
• 📦 After publish, the next-step hint prints godspeed fetch <name> before godspeed install <name>,
  because a machine installs only what it has fetched (or a .gsp file).

📚 Documentation

The README, the site, CLAUDE.md, the template and example READMEs and the design documents were checked
against the CLI, the registry and the OS, and corrected where they said something that was not true. The
README no longer names versions that move with every release.

💻 Builds

🐧 Linux x86_64 and Arm64 (static, any distribution) · 🍎 macOS Apple silicon and Intel · 🪟 Windows x64 and Arm64.
Built against GodspeedOS v0.31.0, and CI proves every template against it.

⬇️ Install

Install on Linux or macOS:

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

Install on Windows (PowerShell):

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

The installers check each binary against SHA256SUMS before running it. A checksum shows the file is
the one this release lists; releases are not signed yet.

🚀 godspeed 0.4.0

🚀 godspeed 0.4.0 - drivers on gs::driver, packages that need packages, and every kind proven

The developer CLI for GodspeedOS, released alongside
GodspeedOS v0.30.0. That OS release finishes gs::driver: every driver in the OS is written on it, from its
register window to its interrupts. This CLI follows straight away: the driver you make is written the same
way, a package can require another package, and every kind of program is now built in CI and
installed and run on a real GodspeedOS.

godspeed new driver sensor        # 🔌 now on gs::driver::registers and gs::driver::wait
godspeed new utility greet        # 🔧 greet Bankole  ->  hello, Bankole
godspeed new app notes            # 🖼️ the screen is yours until a key
godspeed new service clock        # ⚙️ kept running by the system
godspeed new library parser       # 📚 shared, tested on your workstation

📖 New guide, one section for every kind:

Kind	Make it	📖 Step-by-step guide	🧰 API reference
🔁 Service	godspeed new service clock	Make a service	gs::ipc
⚡ Utility	godspeed new utility greet	Make a utility	gs::program
🖼️ App	godspeed new app notes	Make an app	gs::app
🔌 Driver	godspeed new driver sensor	Make a driver	gs::driver
📚 Library	godspeed new library parser	Make a library	gs

🗺️ Not sure which? Which kind? · ✍️ The whole story: Writing a program for GodspeedOS

Updating from 0.3.0: godspeed self update.

✨ What's new

🔌 The driver template is written on gs::driver

The OS's own drivers moved onto gs::driver this release - waits, holds, interrupts, register windows, DMA
arenas, input, power - and the template you start from now speaks the same language:

• 🪟 gs::driver::registers(&ctx) takes the device's register window, instead of the SDK's raw ctx.mmio().
• ⏱️ gs::driver::wait::until(&ctx, Budget::ms(10), ..) waits on the device by time, measured on the
  machine's own clock, instead of counting a thousand 1 ms sleeps. A device that never answers is said, not
  waited on forever.
• 🧪 Installed on QEMU with its edu device, it logs device id 0x010000ed, alive true, 5! = 120.
• ⚠️ It needs GodspeedOS v0.30.0 or later, the first release with gs::driver::registers.

🧩 A package can require another

• 📋 Name what your program needs in godspeed.toml, and a Godspeed machine installs and starts it first:

  [requires]
  "alice/notes-store" = "^1.2.0"

• 🎯 Ranges are written with the whole version: ^1.2.0, =1.2.3 or >=1.2.0. One spelling each, so ^0 and
  ^0.0.0 can never be confused. Before 1.0 a caret holds the minor: ^0.3.1 takes 0.3.5 but never 0.4.0,
  and ^0.0.3 is exactly 0.0.3.

• 📦 A package with requirements is manifest format 2; one without stays format 1 and installs on
  GodspeedOS 0.29.0 exactly as before. An older reader refuses format 2 by name, as "a format this reader does not
  know", rather than misreading it.

• 🌐 The registry reads format 2: it is rebuilt on this release's package crate, so a package with
  requirements can be published. Its contract names the package it sends to (godspeed/dep-store), which the
  contract schema allows from GodspeedOS v0.30.0.

• 🛑 godspeed publish refuses a requirement the registry cannot supply, before a single byte is uploaded,
  and names the newest release there is. --dry-run gives the same answer, and an index that cannot be read stops
  the publish rather than letting it through unchecked.

• 🔍 godspeed check refuses a contract peer that is a package (publisher/name) but is not in
  [requires], and says the line to add. A built-in such as fs is never required, a library requires nothing,
  and a package has at most 8 requirements, none twice and never itself.

• 🧾 godspeed fetch and godspeed inspect say what a release requires, in text and in --json.

• 🔐 A requirement grants nothing: the contract still names every peer, and the operator still approves each.

On the machine (GodspeedOS v0.30.0), the whole plan is one question, dependencies first:

gsh> godspeed install alice/notes
alice/notes 1.0.0 needs 1 more package:
  alice/notes-store            1.2.4     a service  asks for: fs   (needed by alice/notes)
  alice/notes                  1.0.0     an app     asks for: console, alice/notes-store
Install all 2 and grant them? (no privilege) [y/N]:

• ▶️ Each dependency is started before the package that needs it, at install and at every boot.
• 🧱 uninstall refuses a package another one requires, and upgrade refuses a version that would break a
  dependent's range, each naming the package in the way.
• 🧪 Seen on GodspeedOS in QEMU: osdev test deps, 19 of 19.

✅ Every kind is built in CI, and run on the OS

• 🏗️ The end-to-end test used to build only the service template. It now makes, checks and builds service,
  utility, app and driver for all four architectures and checks every ELF: the machine it claims, a real
  entry point.
• 🖥️ GodspeedOS's new osdev test kinds installs one package of each kind, made by this CLI's templates
  untouched, and sees each do its job: the service starts and stays up, the utility answers and pipes, the app
  holds the screen and gives it back, and the driver drives its device. 19 of 19.

📖 A guide that matches what you can build

• 🗺️ What you can make (kinds.html): a page for each kind, from godspeed new to godspeed install on the
  machine - what it is given, what its template does, and which kind to pick.
• 🔄 The overview, examples and reference now say what is true: every kind works, install works on the
  machine, package --local, fetch --offline and inspect are in the reference, and what still waits is named.
• 💬 godspeed run says what it would add - booting a machine with your program already on it - and how to run
  it today: package --local, then godspeed install on the machine.

🧪 Tested

• The whole test suite, cargo fmt and clippy -D warnings.
• Every program kind generated, checked and built for all four architectures, and the library's tests run,
  against a checkout of GodspeedOS (the code that becomes v0.30.0).
• The four templates packaged and installed on GodspeedOS in QEMU, each seen working (osdev test kinds, 19/0).
• Every example checked and built for all four architectures.
• Requirements on GodspeedOS in QEMU, from refusal to boot order (osdev test deps, 19/0).

🚧 Still waiting on GodspeedOS

• 🔌 A driver package is given its device's registers only: no DMA arena and no interrupt yet.
• 📴 godspeed fetch --offline does not yet carry a package's requirements in the same file: install each
  requirement from its own file first, then the package (that order works today). One file for all of them is
  recorded as backlog item 3.
• ▶️ godspeed run and godspeed test for a program: there is no public way yet to boot a machine with your
  program on it, so the CLI says so instead of pretending.

💻 Builds

🐧 Linux x86_64 and Arm64 (static, any distribution) · 🍎 macOS Apple silicon and Intel · 🪟 Windows x64 and Arm64.
Built against GodspeedOS v0.30.0.

⬇️ Install

Install on Linux or macOS:

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

Install on Windows (PowerShell):

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

The installers check each binary against SHA256SUMS before running it. A checksum shows the file is
the one this release lists; releases are not signed yet.

🚀 godspeed 0.3.0

🚀 godspeed 0.3.0 - every kind of program, and packages that travel without a network

The developer CLI for GodspeedOS, released alongside
GodspeedOS v0.29.0 "Signed, Sealed, Delivered". That OS release brings TLS 1.3, its own package manager,
and a supervisor that installs what you publish. This CLI is the other half: you can now build all four
kinds of Godspeed program, and ship any of them as one file to a machine that is never online.

godspeed new utility hello          # 🔧 a program that does one job and ends with a status
godspeed new app notes              # 🖼️ one that owns the screen and keyboard while it runs
godspeed new driver mydev           # 🔌 one that drives a device, named by its PCI class
godspeed fetch godspeed/hello --offline   # 💾 hello-0.3.0.gsp, installable with no network
godspeed inspect hello-0.3.0.gsp          # 🔍 checked offline; nothing kept

📖 Guide and examples: https://godspeedhq.github.io/godspeed-cli/

Updating from 0.2.0: godspeed self update.

✨ What's new

🧩 Four kinds of program, not one

A GodspeedOS 0.29.0 machine installs four kinds of package, and godspeed new makes every one. Each has a
template, a project kind and its own package format:

Kind	Whose life	New in 0.3.0
⚙️ service	the system's: started at boot, restarted if it dies	may declare handover, so godspeed upgrade replaces it live
🔧 utility	its own: runs when typed, ends with a status, pipes like a built-in	✅ new
🖼️ app	the operator's: owns the console while it runs	✅ new
🔌 driver	its device's: given one device by PCI class, registers only	✅ new

godspeed check refuses handover on anything but a service. Only a service is ever replaced while it runs.

💾 Packages that travel as one file

• 📦 godspeed fetch <pkg> --offline writes <name>-<version>.gsp (.gsp for GodspeedOS
  Package). It holds every document the fetch read and checked: the roots, the timestamp, the snapshot,
  the namespaces, the package's index, its manifest, signature and contract, and its binaries (all of them,
  or --arch one). Copy it to a USB stick and run godspeed install hello-0.3.0.gsp on a machine with no
  network. The machine checks it with the same code as a download.
• 🏠 godspeed package --local makes a .gsp of your own, unpublished package, signed with your key.
  A machine installs it only once its operator trusts that key directly (godspeed trust add on the machine).
• 🔍 godspeed inspect checks a .gsp offline, or a release on the registry, and keeps nothing.
• 🏷️ You never name the file: the flag says what it is for, and the name comes from the manifest. Nobody
  names a .deb when they make one.

🛡️ Stronger, and in step with the OS

• 📏 Package names follow the machine: publisher/name at most 128 bytes, the OS's new limit.
• 🌊 The snapshot streams. It is verified from its digest and read a line at a time, so a client never has
  to hold the whole registry in memory.
• 🧰 The platform kit is read from the release's godspeed-platform.toml, checked against its
  SHA256SUMS. GodspeedOS v0.29.0 is the first release to publish one, and this CLI uses it: a project made
  with no checkout fetched the 0.29.0 kit from the release the hour it was published.
• 🧪 Building against a checkout (--os) accepts a stdlib tag at or before its release, so a checkout
  ahead of its last release builds again.
• 🗣️ godspeed install, update and the other native verbs now say where they run: at the Godspeed
  machine's gsh> prompt. The CLI no longer says the package manager is not built, because it is.
• 🤫 Template manifests are Cargo.toml.template, so a git dependency on this repository builds quietly.

🧪 Tested

• cargo fmt, clippy -D warnings, and the whole test suite.
• Every template generated, built and tested against a checkout of GodspeedOS v0.29.0 (4/4), which CI now
  proves on every change.
• Every example checked and built for all four architectures, and a library's tests run, against v0.29.0.
• A new service built with no OS checkout at all, from the published v0.29.0 platform file.

🚧 Still waiting on GodspeedOS

godspeed run and godspeed test for a service: the OS has no public way to start an outside program inside
its test image yet, so the CLI says so instead of pretending. Installing on a machine is the OS's own
godspeed install, at its prompt.

💻 Builds

🐧 Linux x86_64 and Arm64 (static, any distribution) · 🍎 macOS Apple silicon and Intel · 🪟 Windows x64 and Arm64.
Built against GodspeedOS v0.29.0.

⬇️ Install

Install on Linux or macOS:

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

Install on Windows (PowerShell):

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

The installers check each binary against SHA256SUMS before running it. A checksum shows the file is
the one this release lists; releases are not signed yet.

🚀 godspeed 0.2.0

🚀 godspeed 0.2.0 - install it, and that's the setup

The developer CLI for GodspeedOS. This release removes the setup:
no clone of the OS, no environment variable, no registry address. The CLI also updates itself, and checks a
publish before anything leaves your machine.

godspeed new service hello         # 📦 no GodspeedOS clone needed any more
godspeed self update               # ⬆️ from now on, this is how you update
godspeed fetch godspeed/hello      # 🛡️ no flags: the official registry and its root of trust are built in
godspeed publish --dry-run         # 🧪 everything but the upload

📖 Guide and examples: https://godspeedhq.github.io/godspeed-cli/

Coming from 0.1.0? It has no self update yet, so update this once by running the installer again (below).
From 0.2.0 on, godspeed self update does it.

✨ What's new

• 📦 No OS checkout needed. The CLI fetches the few small files that describe a GodspeedOS release - its
  pinned compiler, targets, compiler flags, linker script and contract schema - the first time it needs that
  release, from one commit of the release tag, and caches them with their checksums (a damaged cache is
  fetched again, never used). godspeed new uses the latest release, or --os-release 0.28.0; a project keeps
  the release it was made with. --os <path> still builds against a checkout, for work on the OS itself.
• ⬆️ godspeed self update, as with rustup: it downloads the latest release's build for your machine,
  checks it against the release's SHA256SUMS, runs it, and only then swaps it in. A mismatch, or a binary that
  does not run, changes nothing. The update notice and doctor now point here.
• 🧹 godspeed self uninstall removes the binary, its folder and the PATH entries the installer added -
  after listing them and asking (--yes to skip). It keeps your signing key and tokens, and says where they are.
• 🌍 The official registry is the default, with its root of trust built into the CLI. fetch, login,
  whoami and publish need no --registry, and a first fetch accepts the registry only if its root matches
  the one built in. --registry, GODSPEED_REGISTRY and login still choose any other.
• 🧪 godspeed publish --dry-run packages, signs, checks your token, your namespace and whether the version is
  free, then says what publishing would do. Nothing is uploaded.
• 🆕 godspeed new service hello --publisher alice fills in the publisher, so the project packages straight away.
• ⌨️ Tab completion: godspeed completions bash | zsh | fish | powershell | elvish
  (godspeed completions --help says how to load it).
• 🤖 --json on doctor, verify, package, fetch and whoami, for CI and scripts. Refusals come as JSON
  too, with a stable kind and the same exit code.
• 🎨 Colour in error messages on a terminal (NO_COLOR turns it off).
• 🚦 New exit code 29, cancelled: you declined, or there was no terminal to ask and --yes was not given.

🔬 Tested harder

• The "nobody knows if it published" path now has an end-to-end test: a real build and publish against a stand-in
  registry whose final step never answers. The CLI reads the index and reports published when it was, and
  outcome unknown (exit 25) when it cannot tell - never a guess.

🚧 Still waiting on GodspeedOS

godspeed run, godspeed install, and the utility, app and driver kinds - as in 0.1.0, the CLI says what the OS
is missing instead of pretending.

💻 Builds

🐧 Linux x86_64 and Arm64 (static, any distribution) · 🍎 macOS Apple silicon and Intel · 🪟 Windows x64 and Arm64.
Built against GodspeedOS v0.28.0.

⬇️ 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

🔐 The installers check each binary against SHA256SUMS before running it. A checksum shows the file is
the one this release lists; releases are not signed yet.

⬆️ Already on 0.2.0 or later? godspeed self update.

🚀 godspeed 0.1.0

🚀 godspeed 0.1.0 - the first release

The developer CLI for GodspeedOS: create, build, package, sign and publish Godspeed software from your workstation, for all four architectures at once, and verify anyone's, without touching the kernel, raw IPC or the supervisor.

godspeed new service hello && cd hello
godspeed build --all      # 🧩 x86_64, aarch64, armv7, riscv64
godspeed publish          # ✍️ signed, uploaded, installable as you/hello

📖 Guide and examples: https://godspeedhq.github.io/godspeed-cli/

✨ What's in it

• 🆕 godspeed new service | library: the smallest valid project of each kind, on the public stdlib only. Kinds the OS cannot run yet (utility, app, driver) are refused, with the reason and where the OS tracks it.
• 🔍 check validates the project, its toolchain pin and its contract against the OS's own schema.
• 🏗️ build [--arch | --all] builds one ELF per architecture. test runs a library's tests on your machine.
• 🩺 doctor checks your toolchain, targets and QEMU, and this CLI's version, and prints the command that fixes each problem.
• 📦 package and verify: see exactly what would be published, with every file's size and SHA-256, before anything leaves your machine. Verifying a package needs no registry.
• 🔑 key generate makes your Ed25519 signing key. It stays on your machine; only the public half is shared.
• 🎫 login makes your publisher token on your machine, like an SSH key; the registry stores only its fingerprint. token new makes one for CI.
• 🚢 publish: package, sign, reserve, upload and finalise. A published version never changes, nothing half-published is ever visible, and if the network drops it reads the registry instead of guessing.
• 🛡️ fetch downloads a release and verifies the registry's whole chain of trust (root → timestamp → snapshot → namespaces → index → manifest → signature → files) before keeping anything. The design follows The Update Framework.
• 🔔 Update notice: at most once a day, in the background, it tells you when a newer release is out. It's quiet in CI and scripts; GODSPEED_NO_UPDATE_CHECK=1 turns it off.
• 🚦 A distinct exit code for every kind of failure, and every refusal says what failed, why, and what to do next.

🌍 The registry is live

godspeed/hello@0.1.0 is already published and verifiable:

godspeed fetch godspeed/hello --registry https://godspeed-registry.bankole-422.workers.dev \
  --trust-root sha256:d769d1a64c3105c8da0ffcc2f54aba1c3a16ce4ae707a6d206556f08824a146d

🧪 Examples

examples/ has real projects, each built for every architecture in CI:

• 💓 heartbeat: a loop that sleeps
• 📣 shout: a request/reply server
• 🔢 bootcount: files, a library dependency, and an honest unknown outcome
• 🧵 fixedbuf: a no-heap text library

🚧 Not yet: these wait on GodspeedOS

• ▶️ godspeed run and godspeed install: GodspeedOS starts only the services compiled into its image.
• 🛠️ Utilities, apps and drivers: the OS has no terminating task, no app interfaces, and no device grants for outside drivers yet.
• 🦀 Rust only, for now: C and C++ wait on a C interface to the OS; Go would need its runtime ported.

The CLI says so instead of pretending. Each of these is the OS's to build, and the CLI will follow.

💻 Builds

🐧 Linux x86_64 and Arm64 (static, any distribution) · 🍎 macOS Apple silicon and Intel · 🪟 Windows x64 and Arm64. Built against GodspeedOS v0.28.0.

⬇️ Install

Install on Linux or macOS:

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

Install on Windows (PowerShell):

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

The installers check each binary against SHA256SUMS before running it. A checksum shows the file is
the one this release lists; releases are not signed yet.