Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install cosmon

Cosmon is one command, cs. There is no daemon to run, no service to register, no account to create: you put it on your PATH and you are done.

Every route installs two files: cs and cosmon-remote, the connector for driving a remote cosmon service, side by side in the same directory. cs is the whole product; cosmon-remote is inert until you point it at a remote service, so you can ignore it. It is named here so the second file is listed here to explain its presence in the install directory.

Pick whichever of the three routes below fits how you already manage tools. The first two install the same bytes. The release pipeline builds the tarballs once, signs them once, and Homebrew's formula is rendered from those very artifacts. The third compiles from source, for platforms outside the four release targets.

Already installed? To update or roll back, see Update and roll back cosmon; otherwise skip to Ten minutes to cosmon.

Works on macOS and Linux, on arm64 and x86_64:

curl -fsSL https://noogram.org/cosmon/install.sh | sh

On Linux, add --with-services to install and activate the scheduler and daemon supervisor as user services. This is opt-in; the command above remains a client-only install:

curl -fsSL https://noogram.org/cosmon/install.sh | sh -s -- --with-services

The service option requires a working user service manager. It creates only missing, valid empty supervisor and scheduler configuration files under ~/.config/cosmon, preserves existing configuration and state byte-for-byte, and prints the exact status and uninstall commands. --dir also controls where the two service binaries are installed.

The installer writes to ~/.local/bin, which is not on the default PATH on a fresh macOS or Linux account. When it is not, the installer says so and prints the line to add. Add it before you check the version, and the check succeeds the first time:

export PATH="$HOME/.local/bin:$PATH"   # skip if the installer did not ask for it
cs --version
cs --help

You should see the command groups (lifecycle, fleet, execution, …). That export only affects the current shell. Put the same line in your shell profile (~/.zshrc, ~/.bashrc) so the next terminal finds cs too.

If you installed elsewhere (--dir, COSMON_INSTALL_DIR, or the /usr/local/bin fallback), export that directory instead.

The same route, verifying the installer first

The installer is signed. Every release publishes it as cosmon-install-<version>.sh with a .sig and a .pem beside it, keyless and Rekor-anchored like the binaries. But piping it into sh consumes it before anything could check that signature, so on the one-liner above the signature does no work. Reported by an external reader on issue #32, and correct: the bytes served at that URL are byte-identical to the signed asset today, which is exactly the property an attacker at the CDN or in the TLS path would change.

The convenience route stays. If you would rather check before you run on a shared machine, in CI, or the first time you install cosmon anywhere, download the versioned asset, verify it, then run it:

ver=0.7.3                                   # the release you want
base="https://github.com/noogram/cosmon/releases/download/v${ver}"
curl -fsSLO "${base}/cosmon-install-${ver}.sh"
curl -fsSLO "${base}/cosmon-install-${ver}.sh.sig"
curl -fsSLO "${base}/cosmon-install-${ver}.sh.pem"

cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/.*/cosmon/.github/workflows/release.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature  "cosmon-install-${ver}.sh.sig" \
  --certificate "cosmon-install-${ver}.sh.pem" \
  "cosmon-install-${ver}.sh" \
  && sh "cosmon-install-${ver}.sh"

cosign verify-blob exits non-zero on anything it cannot tie back to release.yml at a cosmon tag, and the && is what makes that exit status refuse to run the script. Everything after that is the same installer doing the same sha256 check on the same tarballs. You have only moved the trust boundary from the endpoint served me these bytes to this workflow, at this tag, produced them.

What that one line actually does

Piping a script from the internet into your shell deserves an explanation, so here is the whole of it. The installer:

  1. Detects your platform from uname -s and uname -m, and maps it to one of the four targets cosmon builds: macOS on arm64 or x86_64, Linux on x86_64 or arm64. Anything else is refused with a clear message rather than guessed at. To see what it resolves for your machine without installing anything: curl -fsSL https://noogram.org/cosmon/install.sh | sh -s -- --print-target.
  2. Downloads the release SHA256SUMS from the GitHub Releases of noogram/cosmon. That file is the source of truth for both the exact tarball name and its digest, which is how the installer can ask for latest without knowing the version string up front.
  3. Downloads the tarball for your target over HTTPS (--proto '=https' --tlsv1.2), using curl or wget, whichever you have.
  4. Verifies the sha256 of what it downloaded against SHA256SUMS. This leg is fail-closed: a mismatch, a missing digest, or no sha256sum/shasum on the box all abort the install rather than proceeding. Nothing is written to your PATH before the digest matches.
  5. Unpacks and installs cs into ~/.local/bin, falling back to /usr/local/bin if that directory is not writable. The tarball also carries cosmon-remote, the connector for driving a remote cosmon service, and the installer places it in the same directory, so one command gives you both laptop tools.

It carries no secret and needs no privilege beyond writing to that one directory.

Choosing a version

The default is the latest release. To pin a specific one, either flag or environment works:

curl -fsSL https://noogram.org/cosmon/install.sh | sh -s -- --version v0.1.0
# or
curl -fsSL https://noogram.org/cosmon/install.sh | COSMON_VERSION=v0.1.0 sh

v0.1.0 is the tag format the installer expects, shown here as an example. pinning any specific version requires that tag to actually exist as a published release. --dir <path> (or COSMON_INSTALL_DIR) changes where cs lands.

Route 2: Homebrew

Since v0.2.0 the tap noogram/homebrew-tap is live, on macOS and on Linuxbrew, arm64 and x86_64 alike:

brew install noogram/tap/cosmon

This is not a separate build. The release pipeline renders the formula from the same tagged, signed release tarballs the install script downloads, and brew verifies the same sha256 digests. Identical bytes, identical provenance.

Route 3: build from source

If you would rather compile it yourself, or you are on a platform outside the four release targets, build from the cosmon repository.

On Linux (glibc) the build links the Secret Service keyring backend through libdbus, so install the system headers first, otherwise the compile fails at libdbus-sys with "The system library dbus-1 required by crate libdbus-sys was not found". macOS needs nothing extra (it uses the native keychain), and the prebuilt Linux release binaries above are static musl, so this applies only when you compile on glibc:

sudo apt install libdbus-1-dev pkg-config          # Debian/Ubuntu
sudo dnf install dbus-devel pkgconf-pkg-config     # Fedora

Then build:

git clone https://github.com/noogram/cosmon && cd cosmon
cargo install --path crates/cosmon-cli --locked

Re-run cs --help afterwards to confirm it landed on your PATH. Note that a source build is your build: it is not covered by the release signature, so the provenance check below does not apply to it.

Verify where the binary came from

The sha256 check proves the bytes match the digest the release published. It does not, on its own, prove who produced that release. That proof is a cosign signature check you run once, deliberately, and it is worth doing:

→ Verify the binary's provenance

A note on package registries

The product is the cs binary published on GitHub Releases, versioned by the git tag it was built from. If cosmon ever appears on crates.io, npm, or PyPI, those entries only hold the name and point back here. They do not contain the shipped binary. Do not expect cargo install cosmon / npm install cosmon / pip install cosmon to give you the released binary.

What is not installed

A manual page. man cs reports No manual entry for cs after any of the three routes: the release tarball carries the binaries and nothing else, and the installer writes no man1 page. The manual source is tracked in the repository at crates/cosmon-cli/man/cs.1 if you want to install it by hand; otherwise the same reference is available from the tool itself, which is where it is kept current:

cs help            # the command groups
cs help guide      # the handbook
cs <command> --help

The generated CLI reference in this book is rendered from that same source.

Next