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 your VMs and containers by name — like files — with their type, state, and hourly cost.

ccloud list

  my-vm              vm          running    $0.184/hr
  my-notebook        container   running    $0.052/hr
  old-staging-box    vm          shut_off   $0.021/hr

Add --json for the full raw API response (every instance type and field) — useful for scripting:

ccloud list --json

ccloud whoami

Show which account your API key belongs to, plus your compute limits, live usage against them, and rate limits — the same numbers the API enforces (see Who Am I & Limits).

ccloud whoami

  👤 You are: omar@multiplicity.studio

  Org            Multiplicity Studio
  API key        c7ef…
  Limits         256 vCPU · 512 GiB RAM · 1000 GiB disk
  Usage          8 vCPU · 16 GiB RAM · 40 GiB disk
  Rate limits    writes 60/minute · reads 600/minute · clones 6/minute
  Clone budget   0 / 500 GiB copying

Add --json for the full raw API response.

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
--json	Also print the full raw JSON response

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, 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 (vCPUs, RAM, disk).

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

# Attribute an instance to a billing project (or clear with --project none)
ccloud update dev-server --project genomics-q4

# Resize a container (applied live)
ccloud update my-container --cpus 16 --ram 64

# Resize a VM (reboots to apply)
ccloud update my-vm --cpus 16 --ram 64 --disk 200

# 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
--ram	New RAM in GiB
--disk	New disk size in GiB
--project	Billing project to attribute this instance to, or none to clear

Containers vs. VMs: container resizes are applied live (no restart), and a container’s disk can be grown or shrunk. A VM resize reboots the VM to apply the change — the API call returns immediately with the instance in a resizing state, and the VM is unavailable for roughly 60–90 seconds while it cycles. A VM’s disk can only grow; a request to shrink it is rejected. vCPUs and RAM can be adjusted in either direction on both. See VM resize for details.

ccloud rename <old-name> <new-name>

Rename an instance. Shorthand for ccloud update <old-name> --name <new-name>.

ccloud rename dev-server production-server

The new name must be kebab-case.

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 copy <uuid|name> [new-name]

Clone a VM into a new, independent copy with its own IP. The source VM briefly stops while its disk is copied, then restarts automatically. An optional second argument names the clone (kebab-case); otherwise it’s auto-named <source>-clone-<id>. VMs only. Up to 500 GiB of clone disk may be copying at once per account (one larger clone is allowed by itself); 6 clone requests per minute max.

ccloud copy dev-server                        # auto-named clone
ccloud copy dev-server dev-server-staging      # named clone
ccloud copy dev-server --move-public-ip        # move the source's public IP to the clone

See Cloning a VM for the full picture.

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

ccloud projects

Manage billing projects — named buckets of spend attribution for your org (see Projects).

ccloud projects list

  demo              0 instances   -          $0.000/hr
  nf-bench-ccloud   0 instances   0.652 TB   $0.008/hr

Columns: project name, instance count, warm storage (in TB, as billed), and total live burn (compute + storage). Add --json for the full raw API response.

ccloud projects create <name>

Create a billing project (kebab-case name). Attach resources with ccloud update <instance> --project <name> and ccloud buckets create --project <name>.

ccloud buckets

Manage object storage buckets.

ccloud buckets list

Lists your personal bucket plus your org’s buckets: name, provider, scope (project name, or personal/org), size in TB, and monthly cost. Add --json for the full raw API response — including each bucket’s S3 endpoint and access credentials, which is the quickest way to wire up rclone/aws s3.

ccloud buckets create --project <id|name> [--provider wasabi|cloudflare] [--region <wasabi-region>]

Create a bucket linked to a billing project (org admins only; one bucket per project per provider). Provider wasabi (default) is standard warm storage with a 90-day minimum storage duration; cloudflare is an R2 pipeline bucket with no minimum duration and zero egress fees. Prints the bucket’s endpoint and credentials on success.

ccloud buckets destroy <bucket-name> --i-am-sure

Permanently delete a project bucket and all data in it (org admins only). Without --i-am-sure it shows what would be deleted and refuses. Wasabi buckets still accrue their 90-day minimum storage duration charge after deletion.

ccloud org members

List your org’s members with their usage (org admins only): role, spend allocation, instance counts, and total hourly cost (compute + storage).

ccloud org members

  derek@carolinacloud.io   owner    3 instances (2 running)   $14.20 spent (no cap)   $0.184/hr
  jane@lab.example.edu     member   1 instances (1 running)   $8.75 / $50.00          $0.052/hr

Add --json for the full raw API response (includes per-instance and storage breakdowns).

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

# Full project lifecycle: project → compute + storage → work → wind down
ccloud projects create demo-rnaseq
ccloud new vm --cpus 8 --ram 16 --disk 100 --name demo-box
ccloud update demo-box --project demo-rnaseq
ccloud buckets create --project demo-rnaseq --provider cloudflare
# ... do the work ...
ccloud destroy demo-box
ccloud buckets destroy <bucket-name> --i-am-sure