CLI Reference

The ccloud CLI is a lightweight command-line tool for managing Carolina Cloud instances. It wraps the REST API and provides quick access to common operations from your terminal.

Installation

curl -fsSL https://console.carolinacloud.io/static/cli/install.sh | bash

This installs the ccloud binary for your platform (Linux amd64/arm64, macOS arm64, Windows amd64).

Authentication

Set your API key as an environment variable:

export CCLOUD_API_KEY="your-api-key-here"

Generate an API key from the dashboard under Settings > API Key. Add the export to your shell profile (~/.bashrc, ~/.zshrc) to persist it.

Commands

ccloud list

List all your instances with their status, resources, and access information.

ccloud list

ccloud get <uuid|name>

Get detailed information about a specific instance by UUID or name.

ccloud get dev-server
ccloud get a1b2c3d4-e5f6-7890-abcd-ef1234567890

ccloud new vm

Create a new virtual machine.

ccloud new vm --cpus 8 --ram 16 --disk 100

Required flags:

Flag	Description
--cpus	Number of vCPUs
--ram	RAM in GiB
--disk	Disk size in GiB

Optional flags:

Flag	Description
--name	Instance name
--tier	general-purpose (default) or high-performance
--ssh-key	Path to SSH public key file

ccloud new container

Create a new container.

ccloud new container --cpus 4 --ram 8 --disk 50 --flavor genomics

Same flags as ccloud new vm, plus:

Flag	Description
--flavor	Container flavor: base, genomics, plaingenomics, datascience, marimo, datasciencemarimo, rstudioserver, rgeospatial
--anthropic-api-key	Anthropic API key. Pre-authenticates Claude Code and notebook AI surfaces on AI-wired flavors.

ccloud update <uuid|name>

Update an instance’s name or resize its resources (containers only).

# Rename an instance
ccloud update dev-server --name production-server

# Resize a container
ccloud update my-container --cpus 16 --ram 64

# Rename and resize at the same time
ccloud update my-container --name big-container --cpus 32 --ram 128 --disk 500

Flags (all optional, but at least one required):

Flag	Description
--name	New name for the instance (kebab-case)
--cpus	New number of vCPUs (containers only)
--ram	New RAM in GiB (containers only)
--disk	New disk size in GiB (containers only)

ccloud stop <uuid|name>

Stop a running instance. Data is preserved, compute billing stops.

ccloud stop dev-server
ccloud stop a1b2c3d4-e5f6-7890-abcd-ef1234567890

ccloud restart <uuid|name>

Restart a stopped instance.

ccloud restart dev-server

ccloud destroy <uuid|name>

Permanently delete an instance. All data is lost.

ccloud destroy a1b2c3d4-e5f6-7890-abcd-ef1234567890

ccloud ssh <uuid|name>

SSH into an instance by UUID or name. If sshpass is installed, the password is entered automatically.

ccloud ssh dev-server

Configuration

Environment variable	Description
CCLOUD_API_KEY	API key for authentication (required)
CCLOUD_API_URL	API base URL (default: https://api.carolinacloud.io)

Instance Names

All commands that accept a UUID also accept an instance name. Names are globally unique and must be kebab-case (lowercase letters, numbers, and hyphens, e.g. my-server-1). If you don’t provide a name when creating, one is auto-generated.

Examples

# Spin up a genomics container, run a pipeline, destroy when done
ccloud new container --cpus 32 --ram 128 --disk 1000 \
  --flavor genomics --tier high-performance --name wgs-pipeline
ccloud ssh wgs-pipeline
# ... run your pipeline ...
ccloud destroy wgs-pipeline

# Quick Marimo notebook for exploratory analysis
ccloud new container --cpus 4 --ram 16 --disk 50 \
  --flavor marimo --name exploration

# Resize a running container
ccloud update exploration --cpus 8 --ram 32

# Rename an instance
ccloud update exploration --name analysis-final

# List everything
ccloud list