CLI Reference

Krayne provides a command-line interface built with Typer and Rich for managing Ray clusters on Kubernetes.

Global options

These options are available on every command:

Option	Description
--version, -V	Show version and exit
--debug	Show full tracebacks on error
--output, -o	Output format: table (default) or json
--kubeconfig	Path to kubeconfig file

---

krayne init

Initialize Krayne with kubeconfig and Kubernetes context. Saves settings to ~/.krayne/config.yaml.

krayne init [OPTIONS]

Options:

Option	Default	Description
-k, --kubeconfig	—	Path to kubeconfig file (skips interactive prompt)
-c, --context	—	Kubernetes context name (skips interactive prompt)

Examples:

# Interactive mode — select kubeconfig and context from menus
krayne init

# Non-interactive mode
krayne init --kubeconfig ~/.kube/config --context my-context

Terminal output

╭─ Krayne Initialized ─────────────────────────╮
│  Kubeconfig:   ~/.kube/config               │
│  Context:      my-context                   │
╰─────────────────────────────────────────────╯

Note

In interactive mode, Krayne presents a menu to select the kubeconfig source (default location, sandbox, or custom path), then lists available contexts.

---

krayne create

Create a new Ray cluster.

krayne create <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace
--gpus-per-worker	0	Number of GPUs per worker node
--worker-gpu-type	t4	GPU accelerator type (e.g. t4, a100, v100)
--cpus-in-head	15	CPU count for the head node
--memory-in-head	48Gi	Memory for the head node
--workers	0	Desired worker replicas (initial count)
--min-workers	0	Minimum worker replicas for autoscaling
--max-workers	1	Maximum worker replicas for autoscaling
--no-autoscaling	false	Disable autoscaling (pin replicas)
--timeout	300	Timeout in seconds
--file, -f	—	Path to a YAML config file

Examples:

# Minimal — all defaults (autoscaling 0-1 workers)
krayne create my-cluster

# GPU cluster with 2 workers, autoscaling 0-4
krayne create gpu-cluster --gpus-per-worker 1 --worker-gpu-type a100 --workers 2 --max-workers 4

# Fixed replicas (no autoscaling)
krayne create my-cluster --no-autoscaling --workers 4

# From YAML config
krayne create my-cluster --file cluster.yaml

# JSON output
krayne create my-cluster --output json

Local access

Use krayne tun-open <cluster-name> to create localhost mirrors of all cluster services via kubectl port-forward. Use krayne tun-close <cluster-name> to stop.

Note

When using --file, the name argument and any CLI flags override the corresponding values in the YAML file.

---

krayne get

List all Ray clusters in a namespace.

krayne get [OPTIONS]

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace

Examples:

# List clusters in default namespace
krayne get

# List clusters in a specific namespace
krayne get -n ml-team

# JSON output for scripting
krayne get --output json

---

krayne describe

Show detailed information about a cluster, including head node and worker group resource allocations.

krayne describe <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace

Examples:

krayne describe my-cluster
krayne describe my-cluster -n ml-team --output json

---

krayne scale

Scale a worker group of a cluster to a target replica count.

krayne scale <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace
-g, --worker-group	worker	Name of the worker group to scale
-r, --replicas	—	Target desired replica count
--min-replicas	—	Minimum replicas for autoscaling
--max-replicas	—	Maximum replicas for autoscaling

At least one of --replicas, --min-replicas, or --max-replicas is required.

Examples:

# Scale default worker group to 4 desired replicas
krayne scale my-cluster --replicas 4

# Adjust autoscaling bounds
krayne scale my-cluster --min-replicas 1 --max-replicas 10

# Scale a named worker group
krayne scale my-cluster --worker-group gpu-workers --replicas 8 -n ml-team

---

krayne delete

Delete a Ray cluster.

krayne delete <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace
--force	false	Skip confirmation prompt

Examples:

# Interactive confirmation
krayne delete my-cluster

# Skip confirmation
krayne delete my-cluster --force

# Delete from specific namespace
krayne delete my-cluster -n ml-team --force

---

krayne tun-open

Start tunnels for cluster services to localhost via kubectl port-forward. Processes run in the background — use tun-close to stop them.

Both commands are idempotent: starting an already-active tunnel is a no-op (shows the existing tunnel info), and closing a non-existent tunnel is a no-op.

krayne tun-open <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace

Local ports are deterministically assigned from the cluster name and namespace, so the same cluster always gets the same local ports.

Examples:

# Start tunnels for all services on a cluster
krayne tun-open my-cluster

# Start tunnels in a specific namespace
krayne tun-open my-cluster -n ml-team

# Get tunnel info as JSON
krayne tun-open my-cluster --output json

Note

The cluster must be in ready or running state. Tunnels forward to the head Service (svc/<name>-head-svc), which survives pod restarts.

---

krayne tun-close

Stop tunnels for a cluster. Terminates all background kubectl port-forward processes.

krayne tun-close <name> [OPTIONS]

Arguments:

Argument	Description
name	Cluster name (required)

Options:

Option	Default	Description
-n, --namespace	default	Kubernetes namespace

Examples:

krayne tun-close my-cluster
krayne tun-close my-cluster -n ml-team

---

krayne sandbox setup

Set up a local k3s cluster with KubeRay for development.

krayne sandbox setup

Requires Docker with at least 2 CPUs and 6 GB RAM. Creates a k3s container named krayne-sandbox and installs the KubeRay operator.

Terminal output

          Sandbox Setup
  Component             Status
  Docker                ✓ ready
  K3S Container         ✓ ready
  K3S Node              ✓ ready
  Kubeconfig            ✓ ready
  KubeRay Helm Chart    ✓ ready
  RayCluster CRD        ✓ ready
  Operator Ready        ✓ ready
╭─ Sandbox Ready ─────────────────────────────────╮
│  Status        running                          │
│  Kubeconfig    ~/.krayne/sandbox-kubeconfig       │
╰─────────────────────────────────────────────────╯
╭─ Next Steps ────────────────────────────────────╮
│  1.  krayne init — select the sandbox            │
│      kubeconfig and context                     │
│  2.  krayne create my-cluster — launch your      │
│      first Ray cluster                          │
╰─────────────────────────────────────────────────╯

After setup, run krayne init to select the sandbox kubeconfig and context.

---

krayne sandbox teardown

Tear down the local sandbox cluster.

krayne sandbox teardown

Removes the Docker container, deletes the sandbox kubeconfig, and clears Krayne settings if they point to the sandbox.

---

krayne sandbox status

Show current status of the sandbox.

krayne sandbox status

---

Output formats

Table (default)

Rich-formatted tables and panels for human-readable output:

krayne get
krayne describe my-cluster

JSON

Machine-readable JSON output, useful for scripting:

krayne get --output json
krayne describe my-cluster -o json | jq '.info.status'

---

Error handling

Errors are displayed as Rich panels by default. Use --debug to see full Python tracebacks:

krayne describe nonexistent-cluster --debug

All errors are instances of KrayneError subclasses. See Error Types for the full exception hierarchy.