Kubeasy CLI Reference

The kubeasy CLI is the main tool to interact with Kubeasy locally: start challenges, submit solutions, reset environments, and more.

Built with Go and powered by Cobra, the CLI is distributed as a single binary with no dependencies.

Installation: See the Getting Started guide for all installation methods (install script, Homebrew, NPM, Scoop, or manual download).

kubeasy version

Authentication

kubeasy login

Authenticate the CLI by entering your API key (generated from your profile page). The key is stored securely 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

You can also set the KUBEASY_API_KEY environment variable for CI/CD use.

Usage:

kubeasy login

Example:

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

Setup

kubeasy setup

Prepare your local environment for Kubeasy. This command:

• Creates a local Kind cluster named kubeasy (if one doesn't exist)
• Installs Kyverno (policy engine for bypass prevention)
• Installs local-path-provisioner (for PersistentVolume storage)

Usually run once per machine before starting challenges. Requires authentication -- run kubeasy login first.

Usage:

kubeasy setup

Example output:

$ kubeasy setup
Kubeasy Environment Setup

Creating kind cluster 'kubeasy' (Kubernetes 1.32)   [12s]
Installing infrastructure (Kyverno + local-path-provisioner)   [45s]

Kubeasy environment is ready!
You can now start challenges with 'kubeasy challenge start <slug>'

Challenge management

All challenge-related actions are available under the challenge subcommand.

kubeasy challenge get <challenge>

View details about a specific challenge before starting it.

Usage:

kubeasy challenge get <challenge-slug>

Example:

$ 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, but now Kubernetes keeps killing it.

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

Objective:
Investigate why the pod keeps crashing and fix it so it runs stably.

kubeasy challenge start <challenge>

Start a challenge. This command:

• Creates a dedicated namespace for the challenge
• Pulls the challenge OCI artifact from the registry
• Applies manifests and Kyverno policies
• Waits for resources to be ready
• Switches your kubectl context to the challenge namespace

Usage:

kubeasy challenge start <challenge-slug>

Example:

$ kubeasy challenge start pod-evicted
Starting Challenge: pod-evicted

Challenge: Pod Evicted
Fetching challenge details
Checking challenge progress
Creating namespace
Deploying challenge
Kubectl context configured

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

After starting: Your kubectl context is now set to the challenge namespace. You can immediately start investigating:

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

kubeasy challenge submit <challenge>

Submit your solution for validation.

• Loads validation objectives from the challenge definition
• Executes each validation against the cluster
• Sends results to the Kubeasy platform

Usage:

kubeasy challenge submit <challenge-slug>

Example (successful submission):

$ kubeasy challenge submit pod-evicted
Submitting Challenge: pod-evicted

Verifying challenge
Checking progress
Loading validations
Running validations...

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

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

Submission Result
All validations passed!
Sending results to server...
Congratulations! Challenge 'pod-evicted' completed!

Example (failed validation):

$ kubeasy challenge submit pod-evicted
Running validations...

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

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

Submission Result
Some validations failed
Review the results above and try again

kubeasy challenge reset <challenge>

Reset the challenge by removing all resources and resetting your progress on the platform. Use this if you want to start completely fresh.

Usage:

kubeasy challenge reset <challenge-slug>

Example:

$ kubeasy challenge reset pod-evicted
Resetting Challenge: pod-evicted

Deleting challenge resources   [5s]
Resetting challenge progress on server

Challenge 'pod-evicted' reset successfully!
You can start the challenge again with 'kubeasy challenge start pod-evicted'

kubeasy challenge clean <challenge>

Clean up all Kubernetes resources related to the challenge, including its namespace. This does not reset your challenge progress on the platform.

Usage:

kubeasy challenge clean <challenge-slug>

Example:

$ kubeasy challenge clean pod-evicted
Cleaning Challenge: pod-evicted

Deleting challenge resources   [5s]

Challenge 'pod-evicted' cleaned successfully!
All resources have been removed from your cluster

When to use:

• You've finished the challenge and want to free up resources
• You want to remove challenge resources without resetting your submission
• You're switching to a different challenge

Dev mode

The dev subcommands are designed for challenge creators. They let you scaffold, deploy, validate, and iterate on challenges locally — no API login required.

For a complete guide with workflows and examples, see the Dev Commands Reference.

kubeasy dev create

Scaffold a new challenge directory with a challenge.yaml template and the required folder structure (manifests/, policies/).

In interactive mode (TTY), prompts guide you through the setup. In non-interactive mode, use flags.

Usage:

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

kubeasy dev get

Display local challenge metadata by reading challenge.yaml from the local directory. No cluster or API required.

Usage:

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

kubeasy dev lint

Validate the structure and content of a challenge.yaml file. Checks required fields, valid values, objective structure, and manifests directory. No cluster needed.

Usage:

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

Example output:

$ 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. This is the dev equivalent of kubeasy challenge start but reads from the local filesystem instead of the OCI registry.

Usage:

kubeasy dev apply
kubeasy dev apply --clean
kubeasy dev apply --watch

kubeasy dev validate

Run challenge validations against the Kind cluster and display results. Does not send results to the API.

Usage:

kubeasy dev validate
kubeasy dev validate --watch
kubeasy dev validate --fail-fast --json

kubeasy dev test

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

Usage:

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

kubeasy dev status

Show pods, recent events, and objective count for a deployed challenge.

Usage:

kubeasy dev status

Example output:

$ 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"
  2m    Normal   Started   Started container app

Objectives: 3

kubeasy dev logs

Stream logs from pods in the challenge namespace. Attempts to find relevant pods from challenge.yaml label selectors, falling back to all pods.

Usage:

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.

Usage:

kubeasy dev clean

Shell autocompletion

kubeasy completion

Generate completion scripts for your shell:

• Bash
• Zsh
• Fish
• PowerShell

Example:

kubeasy completion bash | tee -a ~/.bashrc

Or for zsh:

kubeasy completion zsh | tee -a ~/.zshrc