CLI - Cordium Docs

The cordium CLI is the primary tool for day-to-day Workspace management from a terminal, as well as for scripting and automation. It provides access to the full Cordium API with a command structure designed around common workflows, which is quite similar to the octelium and octeliumctl CLIs.

note

Read in detail on how to install the cordium CLI here.

Domain and Global Flags

Since the CLI is designed to work with multiple Clusters, you need to inform it of your Cluster's domain either via the --domain flag in every command or, more conveniently, via the OCTELIUM_DOMAIN environment variable:

export OCTELIUM_DOMAIN=example.com
# In Windows the PowerShell equivalent of the above command is $env:OCTELIUM_DOMAIN = "example.com"

Every command also supports the following global flags:

Flag	Description
`--domain`	The Cluster domain. Overrides the `OCTELIUM_DOMAIN` environment variable.
`--homedir`	Overrides the Octelium home directory where the authentication state is stored.
`--logout`	Logs out after executing the command. Useful in ephemeral environments such as containers.

Authentication

The cordium CLI shares its authentication state with the octelium and octeliumctl CLIs. In other words, once you log in via any of them, all of them are authenticated with the same Session. If you're not logged in, any cordium command automatically opens a browser window for you to authenticate via the Cluster's identity providers. You can also explicitly log in and out via the octelium CLI (read more here):

# Log in via the web identity providers
octelium login
# Log in via an authentication token Credential
octelium login --auth-token <AUTHENTICATION_TOKEN>
# Log out
octelium logout

For non-interactive environments such as CI pipelines, containers and AI agent orchestrators, a WORKLOAD User can authenticate without any login step via the following environment variables:

Environment variable	Description
`OCTELIUM_AUTH_TOKEN`	An authentication token Credential (read more here).
`OCTELIUM_AUTH_ASSERTION`	An OIDC-based assertion for secretless workload authentication, e.g. from GitHub Actions or Kubernetes (read more here).
`OCTELIUM_ACCESS_TOKEN`	An already issued access token (read more here).

Here is an example:

export OCTELIUM_DOMAIN=example.com
export OCTELIUM_AUTH_TOKEN=<AUTHENTICATION_TOKEN>

cordium run --template ci-runner.payments.cordium --ephemeral --rm --auto-stop

You can show your User, Session and Cluster information as follows:

cordium status
# Or as JSON
cordium status -o json

Resource Names

Workspaces are referred to by their Cluster-assigned names (e.g. abc, x7k2). Other resources are referred to by their names, which the Cluster completes for you relative to your User (read more about resource names here). For example, for the User alice:

You type	Resolves to
`--space research`	The `USER` Space `research.alice`
`--space payments.cordium`	The `ORGANIZATION` Space `payments.cordium`
`--template api-dev`	The Template `api-dev` of `alice`'s `default` Space (i.e. `api-dev.default.alice`)
`--template api-dev.research`	`api-dev.research.alice`
`--template api-dev.payments.cordium`	`api-dev.payments.cordium`
`--snapshot before-upgrade`	`before-upgrade.alice`

Running Workspaces

cordium run is the primary workflow command. It creates a Workspace (if no name is given) or picks an existing one, starts it if it is stopped, waits for it to be ready while showing its state, and opens an interactive terminal inside it. When the terminal session ends, the Workspace keeps running unless the --rm flag is used, in which case it is deleted. Here are some examples:

# Create a Workspace from the default Template of your default Space and open a terminal
cordium run

# Open a terminal in an existing Workspace, starting it first if it is stopped
cordium run abc

# Create from a specific Template
cordium run --template api-dev.payments.cordium

# Create from the default Template of a specific Space
cordium run --space payments.cordium

# Create from a YAML spec file
cordium run --file workspace.yaml

# Create from a container image or a local Dockerfile
cordium run --image python:3.13-slim
cordium run --dockerfile ./Dockerfile

# Clone a repository, at a branch or a tag, with a shallow depth
cordium run --repository https://github.com/myorg/my-project --branch develop --depth 1
cordium run --repository https://github.com/myorg/my-project --checkout v2.3.0

# Create an ephemeral Workspace whose storage is discarded when it stops,
# and delete it as soon as the terminal session ends
cordium run --ephemeral --rm --image ubuntu:26.04

# Set environment variables and source others from Space Secrets
cordium run --image node:24-bookworm \
  -e NODE_ENV=development \
  --env-from-secret NPM_TOKEN=npm-token.payments.cordium \
  --space payments.cordium

# Clone additional repositories next to the primary one
cordium run --repository https://github.com/myorg/api-service \
  --additional-repo shared-lib=https://github.com/myorg/shared-lib \
  --additional-repo proto=https://github.com/myorg/proto-defs

# Override the resource limits (CPU in millicores, memory and storage in megabytes)
cordium run --template api-dev.payments.cordium --cpu 8000 --memory 16384 --storage 50000

# Expose named application ports, the first one being the default application
cordium run --image node:24-bookworm \
  --repository https://github.com/myorg/fullstack \
  --port web:3000:default \
  --port api:8080

# Mount Volumes of the Space, the second one read-only
cordium run --space ml-research.cordium \
  --volume scratch:/scratch \
  --volume datasets:/data:ro

# Restore a new Workspace from a WorkspaceSnapshot
cordium run --snapshot before-upgrade

# Pass variables to a parameterized Template
cordium run --template claude-agent.payments.cordium --ephemeral \
  --var BRANCH=main \
  --var TASK="Fix the flaky TestWebhookRetry test"

# Lock down the Workspace's root filesystem and capabilities
cordium run --image python:3.13-slim --read-only --cap-drop NET_RAW

Workspace Flags

The following flags are shared by cordium run and cordium create workspace. When combined with --file, they override or extend the values of the YAML spec:

Flag	Description
`--space`	The parent Space. The Workspace is created from the Space's `default` Template. Mutually exclusive with `--template`.
`--template`	The parent Template (e.g. `api-dev.payments.cordium`).
`--file`	Path to a Workspace YAML spec file (read more here).
`--snapshot`	Restores the Workspace's storage from a WorkspaceSnapshot. The Workspace is created from the Template of the snapshotted Workspace unless `--template` or `--space` is set. Mutually exclusive with `--ephemeral` for `cordium create workspace`.
`--image`	A container image (e.g. `ubuntu:26.04`). Mutually exclusive with `--dockerfile`.
`--dockerfile`	Path to a local Dockerfile whose content is embedded inline in the spec. `COPY`/`ADD` instructions with local context paths are not supported.
`--repository`	The primary git repository, cloned into `/workspace/repo`.
`--branch`, `-b`	The branch to clone.
`--depth`	The shallow clone depth.
`--checkout`	A specific commit, tag or ref to check out after cloning.
`--additional-repo`	An additional repository in the `NAME=URL` format. Repeatable.
`--env`, `-e`	An environment variable in the `KEY=VALUE` format. Repeatable.
`--env-from-secret`	An environment variable sourced from a Secret of the Space in the `KEY=SECRET_FULL_NAME` format. Repeatable.
`--var`	A variable in the `NAME=VALUE` format (read more here). Repeatable.
`--cpu`, `--memory`, `--storage`	Resource limits in millicores and megabytes.
`--port`	An application in the `PORT`, `NAME:PORT` or `NAME:PORT:default` format. Repeatable.
`--volume`	Mounts a Volume of the Space in the `NAME:MOUNT_PATH[:ro]` format. Repeatable.
`--ephemeral`	Creates an ephemeral Workspace.
`--auto-stop`	Automatically stops the Workspace once all of its foreground lifecycle tasks complete.
`--read-only`	Uses a read-only root filesystem.
`--cap-add`, `--cap-drop`	Adds or drops a Linux capability. Repeatable.

cordium run additionally supports the --rm flag, while cordium create workspace additionally supports the following flags:

Flag	Description
`--start`	Starts the Workspace immediately after its creation, without waiting for it or opening a terminal.
`--out`, `-o`	Prints the created Workspace as `yaml` or `json`.
`--serve`	Serves an Octelium Service assigned to your User from within the Workspace (read more here). Repeatable.
`--serve-all`	Serves all the Octelium Services assigned to your User from within the Workspace.

Creating Workspaces

cordium create workspace (or simply cordium create ws) creates a Workspace in the STOPPED state without opening a terminal, which is typically what scripts and CI pipelines need. Here are some examples:

# Create a Workspace from a Template
cordium create ws --template api-dev.payments.cordium

# Create, start and print the Workspace's name as JSON
cordium create ws --template ci-runner.payments.cordium --ephemeral --auto-stop --start -o json

# Restore a new Workspace from a WorkspaceSnapshot and start it
cordium create ws --snapshot before-upgrade --start

Workspace Lifecycle

# Start a stopped Workspace without opening a terminal
cordium start abc

# Start it with run-specific variables that override the Workspace and Template variables for this run only
cordium start abc --var BRANCH=feat/new-auth --var TASK="Fix the authentication bug"

# Stop a running Workspace
cordium stop abc

# Delete a Workspace
cordium delete workspace abc
# Or simply
cordium rm ws abc

note

Inside a Workspace, cordium stop without any argument stops the Workspace itself, since the Workspace's name is available in the CORDIUM_NAME environment variable. This is useful for background tasks that need to stop their own Workspace once they are done (read more here).

Terminals

cordium terminal (or simply cordium term) opens an interactive terminal in a running Workspace. Unlike cordium run, it does not create or start a Workspace. Every invocation creates an independent terminal session inside the Workspace.

cordium terminal abc
# Or simply
cordium term abc

Executing Commands

cordium exec runs a single command in a running Workspace and streams its output. The command and its arguments must follow a double-dash (--) separator. stdin, stdout, and stderr are all connected and the exit code of the remote command is propagated, which makes it suitable for scripted automation. Sending Ctrl+C terminates the remote command. Here are some examples:

# Run a command
cordium exec abc --no-stdin -- make test

# Run in a specific working directory
cordium exec abc --no-stdin -w /workspace/repo -- go build ./...

# Run as root
cordium exec abc --no-stdin --root -- apt-get install -y ripgrep

# Set per-command environment variables
cordium exec abc --no-stdin -e GOOS=linux -e GOARCH=arm64 -- go build ./...

# Run a shell pipeline (use sh -c for pipelines and redirects)
cordium exec abc --no-stdin -- sh -c "cat /etc/os-release | grep VERSION_ID"

# Use the exit code in a script
if ! cordium exec abc --no-stdin -w /workspace/repo -- npm test; then
  echo "Tests failed"
  exit 1
fi

Flag	Description
`--workdir`, `-w`	The working directory of the command.
`--env`, `-e`	An environment variable for this command in the `KEY=VALUE` format. Repeatable.
`--root`	Runs the command as root inside the Workspace.
`--no-stdin`	Disables stdin forwarding.

note

Once your local stdin reaches its end, cordium exec terminates the remote command since the remote command's stdin cannot be closed independently. Therefore, always use the --no-stdin flag in scripts, CI pipelines and AI agent tools, where stdin is typically empty or closed, otherwise the command would be terminated right away. To pass files to a Workspace or to fetch files from it, use cordium cp (read more here) or the SDKs' file transfer helpers (read more here) instead of piping them through cordium exec.

Logs

cordium logs streams the initialization logs of a Workspace in real time, including the image pull and build output, the repository clone output, and the stdout and stderr of all the lifecycle tasks. Logs are streamed live while the Workspace is starting or running, which makes them the first place to look when a Workspace is slow to start or when a task misbehaves. They are not available anymore once the Workspace has stopped, in which case its status.failure field (e.g. via cordium get ws abc -o yaml) reports why its last run failed.

cordium logs abc

# Prefix each line with a timestamp
cordium logs abc --timestamp

# Disable colors (useful for CI log capture)
cordium logs abc --no-color

SSH and File Transfers

cordium ssh opens an SSH session to a running Workspace through the Cluster's identity-aware SSH proxy, while cordium cp copies files and directories between your machine and a Workspace or between two Workspaces over SFTP. Both require you to be connected to the Cluster via octelium connect:

octelium connect -d

cordium ssh abc
cordium ssh abc -- uptime
cordium ssh abc -N -L 5432:localhost:5432

cordium cp ./config.json abc:/workspace/repo/config.json
cordium cp -r abc:/workspace/repo/dist/ ./dist/
cordium cp abc:/workspace/repo/model.pt def:/workspace/repo/model.pt

# Open VS Code over SSH in /workspace/repo, or in another directory via --dir
cordium code abc

note

Read the complete guide on SSH access, port forwarding, file transfers and IDE integration here.

Snapshots

# Take a snapshot of a Workspace (running or stopped)
cordium create snapshot before-upgrade --workspace abc

# List your snapshots, optionally filtered by Workspace or Space
cordium get snapshot
cordium get snap --workspace abc
cordium get snap --space payments.cordium

# Restore a new Workspace from a snapshot once it is READY
cordium run --snapshot before-upgrade
cordium create ws --snapshot before-upgrade --start

# Delete a snapshot
cordium delete snapshot before-upgrade

Read more about WorkspaceSnapshots here.

Volumes

# Create a 50 GB Volume in your default Space
cordium create volume datasets --size 50000

# Create a SHARED Volume in an ORGANIZATION Space that several Workspaces can mount at once
cordium create volume build-cache.payments.cordium --size 20000 --shared

# Create a Volume in a specific Region
cordium create volume datasets.ml-research.cordium --size 100000 --region eu-west

# List Volumes
cordium get volume --space payments.cordium

# Mount Volumes in a new Workspace
cordium run --space payments.cordium --volume build-cache:/cache

# Delete a Volume once no Workspace or Template mounts it
cordium delete volume build-cache.payments.cordium

Spaces and Templates

# Create a personal Space
cordium create space research
# Create an ORGANIZATION Space shared by a team
cordium create space payments.cordium

# Create a Template from a YAML spec file
cordium create template api-dev.payments.cordium --file template.yaml

# Create a Template with inline flags
cordium create template python.research \
  --image python:3.13-bookworm \
  --repository https://github.com/myorg/ml-experiments \
  --env-from-secret HF_TOKEN=hf-token.research.alice \
  --cpu 4000 --memory 16384

# Trigger a pre-build of a Template, or cancel the running one
cordium build api-dev.payments.cordium
cordium build api-dev.payments.cordium --cancel

# List Spaces and Templates
cordium get space
cordium get template --space payments.cordium

# Delete a Template and a Space
cordium delete template python.research
cordium delete space research

cordium create template supports the --file (-f), --image, --dockerfile, --repository, --branch, --depth, --checkout, --env, --env-from-secret, --additional-repo, --cpu, --memory, --storage and --git-provider flags. Read more about Spaces here and Templates here.

note

Deleting a Space deletes all of its Workspaces, Templates, Secrets, GitProviders and Memberships.

Secrets, UserSecrets and GitProviders

# Create a Space Secret, entering its value interactively without echo
cordium create secret db-password.payments.cordium
# Or from a value, a file (or stdin via "-") or an environment variable
cordium create secret stripe-key.payments.cordium --value "sk_test_..."
cordium create secret tls-cert.payments.cordium --file ./cert.pem
cordium create secret npm-token.payments.cordium --from-env NPM_TOKEN

# Create a personal UserSecret
cordium create usersecret github-token --from-env GITHUB_TOKEN
# Generate an ECDSA SSH key pair whose private key never leaves the Cluster
cordium create usersecret signing-key --type ssh-key

# Create a GitHub GitProvider whose OAuth2 client secret is a Space Secret
cordium create gitprovider github.payments.cordium \
  --type github \
  --client-id Ov23liA4kq9Xp2mZ7bTe \
  --client-secret-from-secret github-oauth-client-secret.payments.cordium \
  --scope repo --scope read:user

# List them
cordium get secret --space payments.cordium
cordium get usersecret
cordium get gitprovider --space payments.cordium

Read more about Secrets and GitProviders here and UserSecrets here.

Listing and Output Formats

Every cordium get command prints a table by default and supports the -o yaml and -o json output formats, which print the full resources, including their full names and statuses:

cordium get ws
cordium get ws abc -o yaml
cordium get ws --space payments.cordium
cordium get ws --template api-dev.payments.cordium -o json

Here is an example of the table output:

┌───────┬─────────┬──────────────┬─────────────┬─────────┬──────────────┐
│ NAME  │ CREATED │   TEMPLATE   │    SPACE    │  STATE  │ LAST STARTED │
├───────┼─────────┼──────────────┼─────────────┼─────────┼──────────────┤
│ k3x9  │ 6d      │ api-dev      │ payments    │ RUNNING │ 2h4m         │
│ p7m2q │ 25m     │ claude-agent │ payments    │ RUNNING │ 24m          │
│ zt4   │ 4d      │ notebook     │ ml-research │ STOPPED │ 21h          │
└───────┴─────────┴──────────────┴─────────────┴─────────┴──────────────┘

Cluster Management

The cordium man commands manage the Cluster-wide Cordium configuration (read more here). They require your User to be authorized to use the Cordium ManagementService (read more here).

# Show the current ClusterConfig
cordium man get clusterconfig
cordium man get cc -o yaml

# Apply a ClusterConfig from a file, a directory or stdin
cordium man apply /path/to/clusterconfig.yaml
cat clusterconfig.yaml | cordium man apply -

Using the CLI Inside Workspaces

The cordium, octelium and octeliumctl binaries are automatically available inside every Workspace, and they are already authenticated as the Workspace's owner through the Workspace's own Session, without any token stored inside the Workspace. This means that a script or an AI agent running inside a Workspace can manage your other Workspaces as follows:

# From inside a Workspace
cordium get ws
cordium run --template ci-runner.payments.cordium --ephemeral --rm --auto-stop
cordium exec abc --no-stdin -- go test ./...
# The Workspace is already connected to the Cluster, so SSH-based commands work right away
cordium cp abc:/workspace/repo/coverage.out ./coverage.out
# Stop the current Workspace
cordium stop

note

The actions are authorized exactly as if you performed them yourself. You can still restrict what Workspace Sessions are allowed to do with the Cordium API via Octelium Policies (read more here).

Command Reference

Command	Description
`cordium run [WORKSPACE]`	Create (or pick), start and open a terminal in a Workspace.
`cordium create workspace`	Create a Workspace. Aliases: `ws`, `workspaces`.
`cordium start WORKSPACE`	Start a stopped Workspace.
`cordium stop [WORKSPACE]`	Stop a running Workspace.
`cordium terminal WORKSPACE`	Open an interactive terminal. Alias: `term`.
`cordium exec WORKSPACE -- CMD`	Run a command and stream its output.
`cordium logs WORKSPACE`	Stream the initialization logs.
`cordium ssh WORKSPACE [-- CMD]`	Open an SSH session, run a command or forward ports.
`cordium cp SRC DST`	Copy files to, from and between Workspaces.
`cordium code WORKSPACE`	Open VS Code inside a Workspace over SSH.
`cordium build TEMPLATE`	Trigger or cancel (`--cancel`) a Template pre-build.
`cordium create space\|template\|secret\|usersecret\|gitprovider\|volume\|snapshot`	Create a resource.
`cordium get workspace\|space\|template\|secret\|usersecret\|gitprovider\|volume\|snapshot`	List or show resources.
`cordium delete ...`	Delete a resource. Aliases: `del`, `rm`.
`cordium man get clusterconfig`	Show the `ClusterConfig`.
`cordium man apply PATH`	Apply the `ClusterConfig`.
`cordium status`	Show your User, Session and Cluster information.
`cordium version`	Show the CLI version, or check for a newer one via `--check`.