CLI Reference

The kubeasy CLI is the primary tool for interacting with Kubeasy. It manages authentication, the local cluster, challenges, and provides a development environment for challenge creators.

Built with Go and Cobra, it ships as a single binary with no runtime dependencies.

kubeasy version   # show version and check for updates

Authentication

kubeasy login

Authenticate the CLI with an API key from your Kubeasy profile page.

The key is stored using the best available backend:

1. System keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) — preferred
2. File-based storage (~/.config/kubeasy-cli/credentials) — fallback for headless environments

Set KUBEASY_API_KEY as an environment variable to skip interactive login (useful in CI).

kubeasy login

$ kubeasy login
API Key: ************************************
API key stored in system keyring
Welcome, Jane Doe
Login successful!

Setup

kubeasy setup

Create the local Kind cluster and install all infrastructure components. Run once per machine before starting challenges.

kubeasy setup

What gets installed:

If a cluster already exists, kubeasy setup checks for configuration drift and offers to recreate it if needed.

Challenge management

kubeasy challenge get <slug>

Display details about a challenge before starting it.

kubeasy challenge get pod-evicted

Pod Evicted

Difficulty: easy
Theme: resources-scaling
Slug: pod-evicted

Description:
A data processing pod keeps crashing and getting evicted.
It was working fine yesterday.

Initial Situation:
A data processing application is deployed as a single pod.
The pod starts but keeps crashing after a few seconds.

kubeasy challenge start <slug>

Start a challenge. Creates a namespace, deploys the challenge from the OCI registry, applies Kyverno policies, and switches your kubectl context to the challenge namespace.

kubeasy challenge start pod-evicted

$ kubeasy challenge start pod-evicted

Challenge: Pod Evicted
Creating namespace
Deploying challenge
Kubectl context configured

Challenge environment is ready!
Namespace: pod-evicted
Context: kind-kubeasy

After starting, your kubectl commands target the challenge namespace by default:

kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>

kubeasy challenge submit <slug>

Run all validation objectives against the cluster and submit results to the platform.

kubeasy challenge submit pod-evicted

On success:

Condition Validation
  pod-running: PASSED - All condition checks passed

Event Validation
  no-crash-events: PASSED - No forbidden events found

All validations passed!
Congratulations! Challenge 'pod-evicted' completed! +50 XP

On failure:

Condition Validation
  pod-running: FAILED - Condition Ready is False (expected True)

Event Validation
  no-crash-events: FAILED - Found forbidden event: OOMKilled

Some validations failed. Review the results above and try again.

Failed objectives include a message explaining what went wrong. Fix the issue and resubmit — there's no limit to submissions.

kubeasy challenge reset <slug>

Remove all challenge resources from the cluster and reset your progress on the platform. Use this to start completely fresh.

kubeasy challenge reset pod-evicted

kubeasy challenge clean <slug>

Remove all challenge resources from the cluster without resetting your platform progress. Use this when you're done with a challenge and want to free up cluster resources.

kubeasy challenge clean pod-evicted

When to use reset vs clean:

• reset — you want to retry the challenge from the beginning
• clean — you've finished and just want to remove the local resources

Dev mode

The kubeasy dev commands are designed for challenge creators. They provide a full local development loop — scaffold, deploy, test, and iterate — without needing an API account or OCI registry.

See Testing Challenges for the recommended development workflow.

kubeasy dev create

Scaffold a new challenge directory with a challenge.yaml template, manifests/, and policies/ folders.

In interactive mode (TTY), you'll be prompted for each field. In non-interactive mode, use flags.

kubeasy dev create
kubeasy dev create --name "Pod Evicted" --type fix --theme resources-scaling --difficulty easy

kubeasy dev get

Display challenge metadata from a local challenge.yaml. No cluster or API connection required.

kubeasy dev get
kubeasy dev get --dir ./my-challenge

kubeasy dev lint

Validate the structure and content of a challenge.yaml without a cluster. Checks required fields, valid enum values, objective structure, unique keys, and the existence of the manifests/ directory.

kubeasy dev lint

$ kubeasy dev lint
Linting challenge: pod-evicted

✓ All checks passed (0 errors, 0 warnings)

kubeasy dev apply

Deploy local challenge manifests to the Kind cluster. The dev equivalent of kubeasy challenge start, reading from the local filesystem instead of the OCI registry.

If an image/ directory exists, the Docker image is built locally and loaded into Kind automatically.

kubeasy dev apply
kubeasy dev apply --clean
kubeasy dev apply --watch   # auto-redeploy on file changes

kubeasy dev validate

Run validation objectives against the cluster without submitting to the API.

kubeasy dev validate
kubeasy dev validate --watch
kubeasy dev validate --json   # useful for CI scripts

kubeasy dev test

Apply manifests and run validations in one step. Equivalent to dev apply followed by dev validate.

kubeasy dev test --clean
kubeasy dev test --clean --watch

kubeasy dev status

Show pods, recent events (last 5 minutes), and objective count for a deployed challenge.

kubeasy dev status

Pods
  NAME                      STATUS    READY   RESTARTS   AGE
  data-processor-abc12      Running   1/1     0          2m

Events (last 5m)
  AGE   TYPE     REASON    MESSAGE
  2m    Normal   Pulled    Successfully pulled image "myapp:latest"

Objectives: 3

kubeasy dev logs

Stream logs from challenge pods.

kubeasy dev logs
kubeasy dev logs --follow
kubeasy dev logs --tail 100 --container app

kubeasy dev clean

Remove all Kubernetes resources for a dev challenge (deletes the namespace). No API login required.

kubeasy dev clean

Shell autocompletion

kubeasy completion <shell>

Generate a shell completion script. Supported shells: bash, zsh, fish, powershell.

# Bash
kubeasy completion bash >> ~/.bashrc
source ~/.bashrc

# Zsh
kubeasy completion zsh >> ~/.zshrc
source ~/.zshrc

# Fish
kubeasy completion fish > ~/.config/fish/completions/kubeasy.fish