chaosctl

chaosctl is the command-line tool for managing ChaosPlane experiments, workflows, and policies.

Installation

# macOS
brew install chaosplane-hq/tap/chaosctl

# Linux
curl -sSL https://github.com/chaosplane-hq/chaosplane/releases/latest/download/chaosctl-linux-amd64 \
  -o /usr/local/bin/chaosctl
chmod +x /usr/local/bin/chaosctl

Global flags

Flag	Description
--kubeconfig	Path to kubeconfig file (default: ~/.kube/config)
--context	Kubernetes context to use
--namespace, -n	Namespace (default: current context namespace)
--output, -o	Output format: table, json, yaml

Commands

create

Create a resource from a file.

chaosctl create -f experiment.yaml
chaosctl create -f workflow.yaml -n production

Flags:

Flag	Description
-f, --filename	File path or URL
-n, --namespace	Target namespace

---

delete

Delete a resource.

chaosctl delete experiment pod-kill-test -n production
chaosctl delete workflow resilience-suite -n production
chaosctl delete policy production-guardrails

Usage:

chaosctl delete (experiment|workflow|policy) NAME [flags]

---

get

Get one or more resources with a summary view.

chaosctl get experiments -n production
chaosctl get experiment pod-kill-test -n production
chaosctl get workflows
chaosctl get policies

Flags:

Flag	Description
-n, --namespace	Namespace (use --all-namespaces / -A for all)
-A, --all-namespaces	List across all namespaces
-w, --watch	Watch for changes
-o, --output	Output format

Example output:

NAME              PHASE      TARGET   ACTION       AGE
pod-kill-test     Completed  Pod      pod-kill     5m
network-delay     Running    Pod      net-delay    1m

---

list

Alias for get with plural resource names.

chaosctl list experiments
chaosctl list workflows -n staging
chaosctl list policies

---

describe

Show detailed information about a resource, including spec, status, conditions, and events.

chaosctl describe experiment pod-kill-test -n production
chaosctl describe workflow resilience-suite -n production
chaosctl describe policy production-guardrails

Example output:

Name:         pod-kill-test
Namespace:    production
Phase:        Completed
Start Time:   2026-04-10 10:00:00 UTC
End Time:     2026-04-10 10:01:30 UTC

Target:
  Kind:       Pod
  Namespace:  production
  Selector:   app=my-app

Action:
  Type:       pod-kill
  Parameters:
    gracePeriodSeconds: 0

Affected Resources:
  - my-app-abc123
  - my-app-def456

Conditions:
  Type              Status  Reason
  SteadyStatePassed True    AllProbesPassed
  Completed         True    ExperimentFinished

Events:
  Time    Type    Reason              Message
  10:00   Normal  SteadyStateStarted  Running before probes
  10:00   Normal  SteadyStatePassed   All before probes passed
  10:00   Normal  ChaosStarted        Injecting pod-kill
  10:01   Normal  ChaosCompleted      Experiment duration elapsed
  10:01   Normal  RecoveryStarted     Running after probes
  10:01   Normal  RecoveryCompleted   All after probes passed

---

abort

Abort a running experiment or workflow.

chaosctl abort experiment pod-kill-test -n production
chaosctl abort workflow resilience-suite -n production

This sets the resource's phase to Aborted and triggers rollback if configured.

---

pause

Pause a running experiment or workflow.

chaosctl pause experiment pod-kill-test -n production
chaosctl pause workflow resilience-suite -n production

---

resume

Resume a paused experiment or workflow.

chaosctl resume experiment pod-kill-test -n production
chaosctl resume workflow resilience-suite -n production

---

logs

Stream logs from the operator for a specific experiment or workflow.

chaosctl logs experiment pod-kill-test -n production
chaosctl logs workflow resilience-suite -n production
chaosctl logs experiment pod-kill-test -n production --follow

Flags:

Flag	Description
-f, --follow	Stream logs continuously
--since	Show logs since duration (e.g. 5m, 1h)
--tail	Number of lines to show from the end

---

events

Show Kubernetes events for a resource.

chaosctl events -n production
chaosctl events experiment pod-kill-test -n production
chaosctl events workflow resilience-suite -n production

Flags:

Flag	Description
-n, --namespace	Namespace
-A, --all-namespaces	All namespaces
--watch, -w	Watch for new events

---

version

Print the chaosctl version and connected cluster info.

chaosctl version

Example output:

chaosctl version: v0.1.0
Kubernetes version: v1.29.0
ChaosPlane operator: v0.1.0

---

completion

Generate shell completion scripts.

# bash
chaosctl completion bash > /etc/bash_completion.d/chaosctl

# zsh
chaosctl completion zsh > "${fpath[1]}/_chaosctl"

# fish
chaosctl completion fish > ~/.config/fish/completions/chaosctl.fish

# PowerShell
chaosctl completion powershell > chaosctl.ps1

Supported shells: bash, zsh, fish, powershell

Common workflows

Run an experiment and watch it

chaosctl create -f my-experiment.yaml -n production
chaosctl get experiment my-experiment -n production -w

Get experiment details after it runs

chaosctl describe experiment my-experiment -n production
chaosctl events experiment my-experiment -n production

Emergency abort

# Abort all running experiments in a namespace
chaosctl get experiments -n production -o json | \
  jq -r '.items[] | select(.status.phase=="Running") | .metadata.name' | \
  xargs -I{} chaosctl abort experiment {} -n production

Export experiment as YAML

chaosctl get experiment pod-kill-test -n production -o yaml