GoldenKube CLI

What the CLI does

GoldenKube CLI is a native command-line tool for the performance-based Kubernetes certifications, starting with the CKA. It builds a fresh Kubernetes cluster on your machine, injects a scenario (a broken component, a missing resource, a task to complete), shows you the task the way the real exam words it, and grades your work when you submit.

Each scenario is a self-contained lab: its own cluster topology, its own setup, its own checks. When you are done the cluster is destroyed and the next scenario starts clean.

Why local Kubernetes

Many CKA topics only exist on real nodes: kubeadm upgrades, etcd snapshot and restore, a kubelet that will not start, certificates, static pods, node-level networking. Hosted sandboxes and single-binary distributions hide exactly those layers.

• Runtime: Multipass with the QEMU backend, Ubuntu 24.04 LTS guests, kubeadm, Cilium CNI.
• Every scenario starts from a clean template, so a broken cluster can never bleed into the next task.
• No cloud account, no remote cluster and no credit card are needed; nothing runs outside your machine except sign-in and progress sync.

Why an account is required

The scenario catalog, your run history and your mock-exam results are tied to your free GoldenKube account. The CLI signs in once with a device code shown in the terminal; afterwards every graded submission appears on your dashboard together with your multiple-choice practice.

There is no paid tier and no trial period: the account is free, and the same account serves the website and the CLI.

Supported platform and prerequisites

Verified target: macOS on Apple Silicon (arm64). Other platforms are not advertised until they have been tested with the Kubernetes runtime.

• Multipass installed with the QEMU driver (the CLI checks this and never changes your Multipass settings for you).
• CPU: 6 cores recommended; fewer than 2 is refused.
• Memory: 16 GiB recommended; fewer than 8 GiB is refused.
• Free disk: 40 GiB recommended; fewer than 20 GiB is refused.
• An SSH client (ships with macOS). kubectl on the host is optional; the lab nodes have it.

Installation

Distribution is a Homebrew Cask from the public GoldenKube tap. The full sequence, including Multipass, is on the install page.

brew install --cask multipass

brew install --cask goldenkube/tap/goldenkube

Commands

Every command supports --json for machine-readable output and --no-color. Commands that need an account exit with code 3 until you sign in.

How grading works

Each scenario ships with a fixed list of checks that read the state of your cluster: does the Service exist, does it select the right pods, is the node Ready again. When you run submit, the grader evaluates every check against the live cluster and reports pass or fail per check.

The score is deterministic: the same cluster state always produces the same result, with no model, heuristics or partial-credit judgement calls. A scenario passes when every check passes; otherwise points are awarded in proportion to the checks that passed.

• Grading runs on your machine. Only the outcome (check ids with pass/fail and points) is sent to your account.
• Results are therefore locally graded and self-reported; they are practice feedback, not an official exam score.
• You can submit as often as you like; every submission is kept and the best one counts for your progress.

Where results are stored

• On your Mac: config in ~/Library/Application Support/goldenkube/config.yaml, the local run registry under state/, logs in ~/Library/Logs/goldenkube/. No secrets are written there; sign-in credentials are designed to live in the macOS keychain.
• In your account: each run (scenario, version, status, timing) and each graded submission, so the dashboard can show progress by exam and domain across devices.
• If the connection is down, submissions queue locally and sync on the next run of any command or goldenkube sync.

Hands-on labs versus multiple-choice practice

GoldenKube started with multiple-choice practice for the associate-level certifications; the CLI adds the performance-based exams. They are different products and both stay free.

• Multiple-choice (KCNA, KCSA, PCA, …): in the browser, one question at a time, instant explanation, spaced repetition. No installation.
• Hands-on (CKA first): in your terminal, a real cluster per scenario, graded by state checks, timed mock exams with curriculum-weighted task selection.
• Both report into the same account and the same dashboard.

Privacy and data collection

The CLI talks to goldenkube.dev only for sign-in, the catalog and progress. What it sends is defined by the API contract and limited to:

• Run lifecycle: scenario id and version, status changes (provisioning, active, finished, failed), timestamps and the CLI version.
• Submissions: the per-check pass/fail outcomes with their points and the grader version.
• Nothing from inside the cluster: no kubeconfig, no manifests, no shell history and no file contents are part of the API.
• Logs stay local. goldenkube diagnostics prints a report you can attach to a bug report; it contains paths and versions, never credentials.

Licensing

GoldenKube CLI is proprietary software, free to use with a GoldenKube account under the end-user licence published with each release. Third-party notices for the libraries it embeds ship alongside the binary. The multiple-choice practice site is unaffected.

Troubleshooting

• goldenkube doctor names the failing prerequisite and the fix; it exits with a specific code per cause (for example 6 when Multipass is missing, 7 when its driver is not qemu, 8 and 9 for memory and disk).
• goldenkube diagnostics collects build, paths, config, environment, the doctor report, the run registry and the VM list for a bug report.
• goldenkube destroy removes only VMs named goldenkube-*; your other Multipass instances are never listed, stopped or deleted.
• Exit code 70 means the command exists but is not available in your build yet; upgrade with Homebrew.

Release and version information

No public version has been released yet. Releases will be published as signed and notarized macOS builds in the public releases repository, with checksums and release notes, and installed through the Homebrew tap. goldenkube version prints the build, commit and Go version of an installed binary.

Frequently asked questions