id       = "clusterctl"
name     = "clusterctl"
homepage = "https://cluster-api.sigs.k8s.io/"
executables   = ["clusterctl"]

[dotfiles]

# Cluster API's official configuration reference documents
# `$XDG_CONFIG_HOME/cluster-api/clusterctl.yaml`; its source retains the
# pre-XDG `~/.cluster-api/clusterctl.yaml` name for older installations.
# https://main.cluster-api.sigs.k8s.io/clusterctl/configuration
# https://pkg.go.dev/sigs.k8s.io/cluster-api/cmd/clusterctl/client/config
paths = []
secret = [
  "[configHome]/cluster-api/clusterctl.yaml",
  "~/.cluster-api/clusterctl.yaml",
]

# The YAML may contain provider and cloud credential variables (the official
# configuration page explicitly supports values such as API credentials), so
# the complete file is treated as a credential rather than partially matched.

[commands]
format = 1
label = "Cluster API management"
description = "Install providers, generate and describe clusters, and move Cluster API objects with clusterctl. Upgrade, delete and other commands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }


[[commands.subcommand]]
path = ["init"]
label = "Install providers"

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://cluster-api.sigs.k8s.io/clusterctl/commands/init.html"
revision = "2026-10-27"
evidence = """
clusterctl init --infrastructure aws
--core flag, the --bootstrap flag or the --control-plane flags
specify the target namespace by using the --target-namespace flag
"""

[[commands.subcommand.field]]
id = "infrastructure"
label = "Infrastructure provider"
description = "e.g. aws or aws:v0.4.1."
type = "string"
option = ["--infrastructure"]
sources = ["help"]

[[commands.subcommand.field]]
id = "core"
label = "Core provider"
type = "string"
option = ["--core"]
sources = ["help"]

[[commands.subcommand.field]]
id = "bootstrap"
label = "Bootstrap provider"
type = "string"
option = ["--bootstrap"]
sources = ["help"]

[[commands.subcommand.field]]
id = "control_plane"
label = "Control plane provider"
type = "string"
option = ["--control-plane"]
sources = ["help"]

[[commands.subcommand.field]]
id = "target_namespace"
label = "Target namespace"
type = "string"
option = ["--target-namespace"]
sources = ["help"]

[[commands.subcommand.task]]
id = "init"
label = "Init with infrastructure"
fields = ["infrastructure", "target_namespace"]
required = ["infrastructure"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["infrastructure", "target_namespace"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["core", "bootstrap", "control_plane"]

[[commands.subcommand]]
path = ["generate", "cluster"]
label = "Generate a cluster manifest"

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html"
revision = "2026-10-27"
evidence = """
clusterctl generate cluster my-cluster --kubernetes-version v1.28.0 --control-plane-machine-count=3 --worker-machine-count=3 > my-cluster.yaml
--infrastructure aws:v0.4.1
--flavor high-availability
--from https://foo.bar/my-template.yaml
--target-namespace
clusterctl generate cluster --list-variables flag
"""

[[commands.subcommand.field]]
id = "name"
label = "Cluster name"
type = "string"
position = 0
min = 1
sources = ["help"]

[[commands.subcommand.field]]
id = "kubernetes_version"
label = "Kubernetes version"
type = "string"
option = ["--kubernetes-version"]
sources = ["help"]

[[commands.subcommand.field]]
id = "control_plane_count"
label = "Control plane machines"
type = "integer"
option = ["--control-plane-machine-count"]
sources = ["help"]

[[commands.subcommand.field]]
id = "worker_count"
label = "Worker machines"
type = "integer"
option = ["--worker-machine-count"]
sources = ["help"]

[[commands.subcommand.field]]
id = "infrastructure"
label = "Infrastructure provider"
type = "string"
option = ["--infrastructure"]
sources = ["help"]

[[commands.subcommand.field]]
id = "flavor"
label = "Template flavor"
type = "string"
option = ["--flavor"]
sources = ["help"]

[[commands.subcommand.field]]
id = "from"
label = "Template source"
description = "URL or local file path of a cluster template."
type = "string"
option = ["--from"]
sources = ["help"]

[[commands.subcommand.field]]
id = "target_namespace"
label = "Target namespace"
type = "string"
option = ["--target-namespace"]
sources = ["help"]

[[commands.subcommand.field]]
id = "list_variables"
label = "List template variables"
type = "boolean"
option = ["--list-variables"]
sources = ["help"]

[[commands.subcommand.task]]
id = "gen"
label = "Generate manifest"
fields = ["name", "kubernetes_version", "control_plane_count", "worker_count", "infrastructure", "flavor"]
required = ["name"]

[[commands.subcommand.task]]
id = "vars"
label = "List variables"
set = { list_variables = [true] }
lock = ["list_variables"]
fields = ["name", "list_variables", "infrastructure", "flavor"]
required = ["name"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["name", "kubernetes_version", "control_plane_count", "worker_count", "infrastructure"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["flavor", "from", "target_namespace", "list_variables"]

[[commands.subcommand]]
path = ["describe", "cluster"]
label = "Describe a cluster"

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://cluster-api.sigs.k8s.io/clusterctl/commands/describe-cluster.html"
revision = "2026-10-27"
evidence = """
clusterctl describe cluster capi-quickstart
By using --grouping=false, the user can force the visualization to show all the machines
By using the --echo flag
--show-conditions KubeadmControlPlane
"""

[[commands.subcommand.field]]
id = "name"
label = "Cluster name"
type = "string"
position = 0
min = 1
sources = ["help"]

[[commands.subcommand.field]]
id = "grouping"
label = "Group identical machines"
type = "boolean"
option = ["--grouping"]
false_option = "--grouping=false"
sources = ["help"]

[[commands.subcommand.field]]
id = "echo"
label = "Show infrastructure and bootstrap objects"
type = "boolean"
option = ["--echo"]
sources = ["help"]

[[commands.subcommand.field]]
id = "show_conditions"
label = "Show all conditions for kinds"
description = "Comma separated kind or kind/name list."
type = "string"
option = ["--show-conditions"]
sources = ["help"]

[[commands.subcommand.task]]
id = "describe"
label = "Describe"
fields = ["name", "echo", "show_conditions"]
required = ["name"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["name", "echo", "show_conditions"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["grouping"]

[[commands.subcommand]]
path = ["move"]
label = "Move Cluster API objects"

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://cluster-api.sigs.k8s.io/clusterctl/commands/move.html"
revision = "2026-10-27"
evidence = """
clusterctl move --to-kubeconfig="path-to-target-kubeconfig.yaml"
use the --namespace flag
clusterctl move --to-directory and clusterctl move --from-directory
With --dry-run option you can dry-run the move action
"""

[[commands.subcommand.field]]
id = "to_kubeconfig"
label = "Target kubeconfig"
type = "path"
option = ["--to-kubeconfig"]
path = { kind = "file", role = "input" }
sources = ["help"]

[[commands.subcommand.field]]
id = "namespace"
label = "Namespace"
type = "string"
option = ["--namespace"]
sources = ["help"]

[[commands.subcommand.field]]
id = "to_directory"
label = "Export to directory"
type = "path"
option = ["--to-directory"]
path = { kind = "directory", role = "output" }
sources = ["help"]

[[commands.subcommand.field]]
id = "from_directory"
label = "Import from directory"
type = "path"
option = ["--from-directory"]
path = { kind = "directory", role = "input" }
sources = ["help"]

[[commands.subcommand.field]]
id = "dry_run"
label = "Dry run"
type = "boolean"
option = ["--dry-run"]
sources = ["help"]

[[commands.subcommand.task]]
id = "preview"
label = "Preview a move"
set = { dry_run = [true] }
lock = ["dry_run"]
fields = ["to_kubeconfig", "namespace", "dry_run"]
required = ["to_kubeconfig"]

[[commands.subcommand.task]]
id = "move"
label = "Move to another cluster"
fields = ["to_kubeconfig", "namespace"]
required = ["to_kubeconfig"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["to_kubeconfig", "namespace", "dry_run"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["to_directory", "from_directory"]