Install it, run it, read what it says.
Everything here is what the program does today. Each command names the plan it needs as the binary checks it — the table below is tested against the binary's own table, so it cannot drift.
Install
Every program is on the releases page, one archive per system. Nothing is installed in your cluster, and no account is involved.
| File | What it is |
|---|---|
| Shoalcheck_<v>_macos_universal.dmg | The desktop app for macOS 12 and later, signed with a Developer ID and checked by Apple's notary service from 0.1.0-rc.12. |
| shoalcheck_<v>_<os>_<arch> | The command line (.zip on Windows). On macOS it is signed and checked by Apple's notary service from
0.1.0-rc.12; on Windows, SmartScreen may warn once (More info → Run anyway). |
| shoalcheck-app_<v>_<os>_<arch> | The desktop app for Windows and Linux: it serves the window on this machine and opens it in your browser. |
| kubectl-shoalcheck_<v>_<os>_<arch> | The same command line as a kubectl plugin, run as kubectl shoalcheck …. |
| shoalcheck-mcp_<v>_<os>_<arch> | An MCP server that hands an assistant the readings already on this machine. It has no kubeconfig and cannot read a cluster. |
First commands
shoalcheck preflight drain node-1 # can this node be evacuated? exit 0 · 2 · 1 shoalcheck preflight zone eu-west-1a # what has nowhere to go if this zone is lost? shoalcheck preflight upgrade 1.34 # what stops the way to that version? shoalcheck audit --context prod # the size of the reading and its five most serious kinds, free shoalcheck audit --context prod --output report.html --json reading.json # the full reading, with a licence
Preflight is free on every plan, in full. shoalcheck --help lists every command and its flags.
Exit codes
| Code | Means |
|---|---|
| 0 | Done; for preflight, nothing this model checks stops the change. |
| 2 | Preflight stops the change, or the gate’s policy fired — the answer names it. |
| 1 | The answer is partial — a kind it needed could not be read, and it says which — or the command failed. |
| 3 | The report was written, and its wording broke the copy policy: a defect in the words, reported rather than swallowed. |
| 4 | The licence on this machine does not cover the command; it says which plan does. |
Every command, and the plan it needs
A command the licence on this machine does not cover exits 4 and names the plan that does. Free needs no account and no key.
| Command | Plan | What it does |
|---|---|---|
| preflight drain | zone | upgrade | Free | Answers one question before a change, from only the kinds that question needs: can these nodes be evacuated, what has nowhere to go if a zone is lost, what stops an upgrade. |
| audit | Free | Reads a cluster. Free: the size of the reading — its problems by severity and kind, and what they cost — and its five most serious kinds, with nothing kept. With Pro: every finding with its evidence and fix, the HTML report (--output), JSON (--json), exports, and history (--save-history). |
| support | Free | Writes a file describing this install, and with --input reading.json a reading, without naming anything in the cluster. |
| upgrade | Free | Replaces this program with the newest release once its signature, digest and version check out; --check only asks. |
| licence show | install | plans | fingerprint | Free | What the key on this machine covers and until when; installs a key; lists the plans; prints a cluster's fingerprint for a key bound to it. |
| activate | Free | Installs a key, the same as licence install. |
| render | Pro | Renders a kept reading (--input reading.json) as the report or, with --instrument, as the workspace. A kept fleet (fleet --json) renders too, on Team. |
| findings | Pro | Lists a reading's findings, filtered by severity, rule, category or namespace; as a table, JSON, Markdown or SARIF. |
| explain | Pro | One finding in full: what it is, why it matters, what it rests on, the fix. |
| diff | Pro | What changed between the two newest readings of a cluster, and what the comparison could not say. |
| browse | Pro | Walks a reading in the terminal. |
| history list | diff | timeline | verify | Pro | The readings kept on this machine: each one signed by this install, each finding's state reading by reading, and whether any file changed after it was signed. |
| evidence | Pro | An evidence pack for a framework (CIS-K8s, SOC2, PCI-DSS) from a reading; evidence verify and evidence pubkey are free, for whoever receives the pack. The sample's pack (zip, one file per control). |
| fleet | Team | Several clusters in one reading, and what they declare differently; a context that cannot be read is named, never counted as a cluster with no problems. |
| gate | Team | For CI: compares a reading with a baseline and fails on what you choose — new findings at a severity, regressions, unreadable kinds. |
| schedule | Team | Scheduled readings through launchd or systemd, or a CI job (schedule render --ci github|gitlab). |
| ticket push | Team | Files findings as Linear or Jira Cloud issues, deduplicated, so the same finding is not filed twice; --dry-run contacts nothing. Both are written from the trackers' published APIs and tested against fakes of them — no push has reached a real Linear or Jira site yet. A reading's Export & act also opens a filled-in Jira or Linear issue form in your own browser. |
| team | Team | A team space in a folder your team already shares — a git repository or a synced folder: a signed roster, decisions about findings merged across members, published readings, the gate's baseline and CI runs. Nothing is sent anywhere, and Shoalcheck never runs or configures version control: the folder is synchronised with whatever your team already trusts, and team sync lists what changed. |
What it reads
get and list only, never watch, and never Secrets, ConfigMaps, environment
values or logs. deploy/rbac.yaml, in the command-line archive, is the role it needs and nothing more;
shoalcheck audit --show-permissions prints it before anything connects. What it does to your cluster
has the whole list and the file or gate behind each claim.
Check a download
cosign verify-blob --key cosign.pub --bundle checksums.txt.sigstore.json checksums.txt shasum -a 256 --ignore-missing -c checksums.txt
The checksums file, its signature bundle and the public key are on every release; the key is also in the releases repository.
Updates
The command line: shoalcheck upgrade. The app: Settings → Updates, once a day if you allow it, or Check now. Either
installs a release only after its manifest verifies under the Shoalcheck release key, the file's SHA-256 matches the signed one,
and the new program starts and names its version. A copy Homebrew or krew installed updates with their own command.
When something does not work
There is no support desk, no telemetry and no crash report. The app's Help has a section called "When something does not
work", with this machine's own paths. Settings → Diagnostics, or shoalcheck support, writes a file that describes
the install, and a reading if you choose one, without naming anything in the cluster: versions, counts, this tool's own rule
ids, and the cause recorded for anything a reading did not get back. It is JSON — read it before you show it to anyone.
Changelog
Every release says what changed since the one before, on the
releases page. An installed copy offers a newer release in Settings → Updates or through shoalcheck upgrade --check.