Command Reference | castctl

Every castctl command and its flags, for lookup.

Every command also accepts castctl <command> --help for the flags currently supported by your installed version.

castctl auth login

Authenticates castctl with your Cast AI account and stores the token in ~/.config/castctl/config.yaml. Takes no flags. Run it again to switch accounts or organizations.

castctl cluster connect

Flag	Description
`--dry-run`	Resolve and print the configuration as YAML without registering the cluster or making changes.
`--non-interactive`	Skip prompts; combine with feature-toggle flags for CI.
`--provider anywhere`	Connect a cluster outside EKS, GKE, or AKS via Cast AI Anywhere.
`--umbrella-values-file <path>`	Merge a YAML file of Helm values into the umbrella chart install.
`--import-config`	After a successful connect, run node-group discovery and import it as node configurations and node templates. See Import and apply cluster configuration with castctl.

Feature-toggle flags (for example --cluster-optimization, --workload-autoscaler) and cloud-credential flags vary by provider. Run castctl cluster connect --help for the complete, current list.

See Connect using the castctl CLI.

castctl cluster disconnect

No flags are required for the common case: castctl reads the cluster ID from the in-cluster configuration. Run castctl cluster disconnect --help for flags that skip cloud cleanup or the Kubernetes uninstall.

See Connect using the castctl CLI.

castctl cluster migrate

Flag	Description
`--yes`	Skip the interactive confirmation prompt.
`--umbrella-version <version>`	Install a specific umbrella chart version instead of the latest stable.
`--values-dump-path <path>`	On failure, write the preserved standalone release values to this path instead of the default `castai-migrate-values-<timestamp>.yaml`.
`--values-file <path>`	Recovery mode: skip standalone detection and uninstall, and install the umbrella chart using the values in this file.

Three subcommands support migrating clusters managed by GitOps or IaC (available in castctl 0.15.0 and later):

castctl cluster migrate generate

Read-only: scans the cluster for standalone Cast AI releases (including ArgoCD-managed components) and writes an umbrella chart values file, a tool-specific manifest, and a step-by-step MIGRATION-STEPS.md checklist.

Flag	Description
`--output`, `-o <dir>`	Directory to write the generated files. Defaults to the current directory.
`--format <format>`	Output format: `generic` (default), `argocd`, `flux`, or `terraform` (also valid for OpenTofu).
`--profile <profile>`	Override the auto-detected profile: `autoscaler` or `autoscaler-anywhere` for Cast AI Anywhere clusters.
`--repo-url <url>`	GitOps repository URL that will host the generated `values.yaml`. Recommended for `--format argocd`; without it the generated Application contains a `<YOUR-GITOPS-REPO>` placeholder.
`--namespace`, `-n <ns>`	Namespace where the standalone Cast AI components are installed. Defaults to `castai-agent`.

castctl cluster migrate pre-umbrella-install

Prepares the cluster for umbrella adoption without installing the umbrella chart: preserves Workload Autoscaler CRDs, deletes the standalone Helm release secrets (cluster resources survive), and orphan-deletes Deployments and DaemonSets with immutable selectors. Pods keep running.

Flag	Description
`--strategy <strategy>`	Adoption strategy: `helm-secrets` or `server-side-apply`. Auto-detected if not set (`server-side-apply` for kubectl-applied manifest installs).
`--dry-run`	Show what would be done without making changes.
`--yes`	Skip the interactive confirmation prompt.
`--namespace`, `-n <ns>`	Namespace where the standalone Cast AI components are installed. Defaults to `castai-agent`.

castctl cluster migrate post-umbrella-install

Cleans up after the umbrella chart is installed and its pods are Ready. It deletes stale ReplicaSets and orphaned pods from the standalone releases. On ArgoCD, it also sets preDeleteHook.enabled=false on Applications running the standalone workload-autoscaler chart, so Recommendation CR finalizers are preserved.

Flag	Description
`--dry-run`	Show what would be done without making changes.
`--yes`	Skip the interactive confirmation prompt.
`--namespace`, `-n <ns>`	Namespace where the standalone Cast AI components are installed. Defaults to `castai-agent`.

See Migrate standalone Helm charts with castctl for the imperative path and Migrate GitOps and IaC installations with castctl for the phased ArgoCD, Flux, and Terraform flow.

castctl cluster import-config

Flag	Description
`--cluster-id <id>`	Cast AI cluster ID. Auto-detected from the cluster in your kubeconfig if not provided.
`--file <path>`	Write the discovered plan to a file instead of applying it.
`--output <format>`	Plan serialization when `--file` is set: `yaml` (default) or `tf` (apply-ready Terraform).
`--non-interactive`	Skip the interactive review and apply the discovered plan directly.

See Import and apply cluster configuration with castctl.

castctl cluster apply-config

Flag	Description
`--file <path>`	Plan file to apply. Required. `apiVersion`, `kind`, and `metadata.clusterId` are validated before anything is applied.

See Apply a plan from a file.

castctl mcp

Configures AI clients to connect to Cast AI MCP for read-only access to your Cast AI data from AI tools.

castctl mcp add

Detects supported AI clients installed on your machine and configures the Cast AI MCP connection for them. Clients it cannot configure automatically, such as Claude Desktop, are listed with manual instructions and a link to the vendor's setup guide. Complete the browser sign-in when your client prompts for it; the timing depends on the client. For the full setup flow, see Connect AI tools to Cast AI MCP.

Flag	Description
`--api-region <region>`	Cast AI region for the connection: `us`, `eu`, or `india`.

castctl version

Prints the installed castctl version. Takes no flags.

castctl command reference