Detailed CLI Options

The rackctl command-line interface provides several commands for managing Kubernetes clusters and related resources. This document details all available commands and their options.

Available Commands

Command	Description
`create`	Creates a new Kubernetes cluster
`delete`	Deletes an existing cluster
`gen-ssl`	Generates SSL certificates for a given domain
`ps`	Lists all running Kubernetes clusters
`switch`	Switches the current context to a specified cluster
`refresh-token`	Refreshes the kubeconfig for the currently selected cluster
`token-login`	Exchanges a long-lived API token for a session token and saves it locally

Command Details

`create` Command

Creates and provisions a new Kubernetes cluster.

Basic Usage

rackctl create <cluster-name>

Full Options

rackctl create <cluster-name> \
  [--description <description>] \
  [--cpu-limit <cpu>] \
  [--ram-limit <ram>] \
  [--disk-size <size>] \
  [--region-code <region>] \
  [--ttl <duration>] \
  [--do-not-delete] \
  [--it]

Parameters

Parameter	Description	Default	Example
`name`	Name of the cluster	(Required)	`production-cluster`
`--description`	Description of the cluster	”No description provided”	`--description "Production environment for e-commerce app"`
`--cpu-limit`	CPU limit in cores	2.0	`--cpu-limit 4.0`
`--ram-limit`	RAM limit in GB	3.5	`--ram-limit 8.0`
`--disk-size`	Disk size in GB	20	`--disk-size 100`
`--region-code`	Region to deploy the cluster	”ap_south_1”	`--region-code us_east_1`
`--ttl`	Time to live	50m	`--ttl 4h`, `--ttl 1d`, `--ttl 1.5d`, `--ttl 1w`, `--ttl 1mon`
`--do-not-delete`	Prevents automatic deletion. When set, the cluster is exempt from TTL-based expiry and `--ttl` is not sent to the API.	false	`--do-not-delete`
`--it`	Interactive mode — walks through picking a resource tier and a deletion policy via prompts, instead of `--cpu-limit`/`--ram-limit`/`--disk-size`/`--ttl`/`--do-not-delete`	false	`--it`

--ttl accepts human-friendly durations: m (minutes), h (hours), d (days), w (weeks), or mon (months) — e.g. 20m, 4h, 1d, 1.5d, 1w, 1mon. A bare number is still accepted and treated as seconds, for backward compatibility.

Interactive mode (`--it`)

Instead of specifying resource and TTL flags by hand, --it prompts you to pick from a curated list:

rackctl create test-cluster --it

? Select a configuration: ›
❯ 2 vCPU / 3.5 GB RAM / 20 GB Storage
  4 vCPU / 7 GB RAM / 40 GB Storage
  8 vCPU / 14 GB RAM / 80 GB Storage

? When should this cluster be deleted? ›
❯ Do not delete
  Delete after 1 hour
  Delete after 1 day
  Delete after 1 week
  Delete after 1 month

Your selections override any --cpu-limit, --ram-limit, --disk-size, --ttl, or --do-not-delete flags passed alongside --it. --region-code is not prompted for, since only one region is currently supported, and any value you passed (or its default) is kept as-is. Selecting “Do not delete” is equivalent to passing --do-not-delete.

Example

# Create a production cluster with 4 CPU cores, 8GB RAM, and 100GB disk space
rackctl create production-cluster \
  --description "Production environment" \
  --cpu-limit 4.0 \
  --ram-limit 8.0 \
  --disk-size 100 \
  --region-code us_east_1 \
  --ttl 1d

# Or walk through the same choices interactively
rackctl create production-cluster --it

`delete` Command

Deletes an existing Kubernetes cluster.

Usage

rackctl delete --uuid <cluster-uuid>

or, to delete whichever cluster was last created/switched to (saved in ~/.rackmint/k8), without specifying a UUID:

rackctl delete --i-understand

Parameters

Parameter	Description	Example
`--uuid`	UUID of the cluster to delete	`--uuid 413f3e1c-b3a5-4e2d-a981-53ecbd0358ff`
`--i-understand`	Skips `--uuid` and deletes the cluster saved in `~/.rackmint/k8`. Also skips the do-not-delete confirmation prompt below.	`--i-understand`

Do-not-delete protection

If the target cluster was created with --do-not-delete, rackctl looks up the cluster before deleting it and, unless --i-understand was passed, prompts you to confirm interactively:

⚠️  Cluster '413f3e1c-b3a5-4e2d-a981-53ecbd0358ff' is marked as `do_not_delete`.
? Are you sure you want to delete cluster '413f3e1c-b3a5-4e2d-a981-53ecbd0358ff'? (y/N)

Answering “no” (or pressing Ctrl+C) cancels the deletion. This check is skipped entirely when --i-understand is passed, so use it carefully in scripts/CI.

Example

# Delete a specific cluster
rackctl delete --uuid f75899c7-6d2a-4169-a7e2-450a3a8d7613

# Delete the last cluster you created/switched to, bypassing all prompts
rackctl delete --i-understand

`gen-ssl` Command

Generates SSL certificates for a specified domain.

Usage

rackctl gen-ssl <domain> [--skip-dns-check]

Parameters

Parameter	Description	Example
`domain`	Domain name for which SSL needs to be generated	`app1.dev.example.com`
`--skip-dns-check`	Skips the DNS resolution check — useful for wildcard DNS entries	`--skip-dns-check`

Example

# Generate SSL for a domain
rackctl gen-ssl app1.dev.example.com

`ps` Command

Lists all running Kubernetes clusters, similar to docker ps.

Usage

rackctl ps

Example Output

CLUSTER ID                             NAME       CREATED                STATE    REGION
413f3e1c-b3a5-4e2d-a981-53ecbd0358ff  may17-1    17/05/2025, 08:33:05   running  ap_south_1
f75899c7-6d2a-4169-a7e2-450a3a8d7613  may17      17/05/2025, 08:13:31   running  ap_south_1

`switch` Command

Switches the current context to a specified cluster.

Usage

rackctl switch <cluster-id>

Parameters

Parameter	Description	Example
`id`	ID or UUID of the cluster to switch to	`413f3e1c-b3a5-4e2d-a981-53ecbd0358ff`

Example

# Switch to a specific cluster
rackctl switch 413f3e1c-b3a5-4e2d-a981-53ecbd0358ff

`refresh-token` Command

Refreshes the kubeconfig for the currently selected cluster , the newly generated kubeconfig is valid for 1 hour.

Usage

rackctl refresh-token

`token-login` Command

Exchanges a long-lived API token for a short-lived session token and saves it to ~/.ginger-society/auth.json.

Usage

rackctl token-login <api-token>

Parameters

Parameter	Description	Example
`token_value`	The long-lived API token generated from the Token Management page	`rackctl token-login eyJ0eXAi...`

Example

rackctl token-login eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Once run, subsequent rackctl commands will automatically pick up the saved session token — no need to set RACKCTL_SESSION_TOKEN unless you want to override it (e.g., in CI/CD, see the CI/CD pipeline guide).

Environment Variables

Variable	Description	Example
`RACKCTL_SESSION_TOKEN`	Authentication token for API requests. If unset, `rackctl` falls back to the session token saved by `rackctl token-login`.	`export RACKCTL_SESSION_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`

Best Practices

Resource Management
- Request only the resources you need (CPU, RAM, disk) to optimize costs, or use --it to pick from a preset tier
- Use appropriate --ttl values for temporary clusters — --ttl is ignored when --do-not-delete is set
- Use --do-not-delete deliberately — deleting such a cluster later requires confirmation (or --i-understand)
Security
- Store tokens securely, preferably in environment variables or secrets management systems
- For CI/CD pipelines, use long-lived tokens from the token management interface, exchanged via rackctl token-login
Workflow Optimization
- Use rackctl ps to monitor your running clusters
- Use descriptive names and detailed descriptions for better organization
- Utilize the switch command to quickly change between working contexts

Detailed CLI Options

Available Commands

Command Details

create Command

Basic Usage

Full Options

Parameters

Interactive mode (--it)

Example

delete Command

Usage

Parameters

Do-not-delete protection

Example

gen-ssl Command

Usage

Parameters

Example

ps Command

Usage

Example Output

switch Command

Usage

Parameters

Example

refresh-token Command

Usage

token-login Command

Usage

Parameters

Example

Environment Variables

Best Practices

`create` Command

Interactive mode (`--it`)

`delete` Command

`gen-ssl` Command

`ps` Command

`switch` Command

`refresh-token` Command

`token-login` Command