Skip to main content
The cpln workload run command creates a temporary workload, waits for it to become healthy, executes your command, and optionally cleans up. It’s similar to docker run - perfect for one-off tasks, debugging, and running scripts in your cloud environment.

​
When to use this

Run migrations

Execute database migrations in your production environment

One-off scripts

Run maintenance scripts, data processing, or cleanup tasks

Debug with clones

Clone an existing workload to debug in an isolated environment

Quick tests

Spin up temporary containers to test configurations

​
Prerequisites

Install the Control Plane CLI. See Installation.
You need create and exec permissions on workloads. See Workload Permissions.

​
Basic usage

cpln workload run -- <command> [args...]
By default, this:
  1. Creates a temporary workload using ubuntu:22.04
  2. Waits for it to become healthy
  3. Executes the command
  4. Exits (workload remains unless --rm is used)

​
Options

OptionDescription
--cloneClone an existing workload instead of using the default image
--imageUse a custom image
--rm, --removeDelete the workload after the command completes
-i, --interactiveKeep the session open after command execution
--containerTarget container (when cloning multi-container workloads)
--cpuCPU allocation (e.g., 50m, 100m)
--memory, --memMemory allocation (e.g., 128Mi, 256Mi)
--shell, -sShell to use for interactive mode (default: bash)
--locationTarget location
--tagAdd tags to the temporary workload
-c, --commandOverride container command
-a, --argOverride container args

​
Run a simple command

cpln workload run -- echo "Hello from Control Plane!"

​
Use a custom image

cpln workload run --image python:3.11 -- python --version

​
Clone an existing workload

Run commands in an environment identical to an existing workload: 
cpln workload run --clone my-app -- npm run migrate
This clones my-app with all its configuration (env vars, secrets, identity) and runs the command.

​
Target a specific container

For multi-container workloads: 
cpln workload run --clone my-app --container worker -- python process.py

​
Automatic cleanup

Delete the temporary workload after the command completes: 
cpln workload run --rm -- echo "Hello from Control Plane!"
Use --rm for one-off tasks to avoid accumulating temporary workloads.

​
Interactive mode

Stay in the container after the command runs: 
cpln workload run --interactive -- ls -la
After the command executes, you’ll have an interactive shell to continue working.

​
Specify a shell

cpln workload run --interactive --shell sh -- cat /etc/os-release

​
Common workflows

​
Run database migrations

cpln workload run --clone my-app --rm -- npm run db:migrate

​
Debug in a cloned environment

cpln workload run --clone production-api --interactive -- bash

​
Run data processing

cpln workload run \
  --image python:3.11 \
  --cpu 500m \
  --memory 1Gi \
  --rm \
  -- python /scripts/process-data.py

​
Test in a specific location

cpln workload run --location aws-eu-central-1 -- curl -s https://api.example.com

​
Add tags for tracking

cpln workload run --tag job=nightly-backup --tag env=prod --rm -- ./backup.sh

​
Resource configuration

Override CPU and memory for resource-intensive tasks: 
cpln workload run \
  --cpu 200m \
  --memory 512Mi \
  -- ./heavy-computation.sh

​
Override container command

Replace the container’s default command: 
cpln workload run \
  --image myapp:latest \
  --command sleep \
  --arg "infinity" \
  --interactive \
  -- bash
This starts the container with sleep infinity instead of its default command, then opens a bash session.

​
Troubleshooting

The location may not be available in your GVC:
cpln gvc get my-gvc
Verify the location is in the GVC’s staticPlacement.locationLinks.
The default Ubuntu image may not have your tool. Use a custom image:
cpln workload run --image node:20 -- npm --version
Specify a different shell:
cpln workload run --interactive --shell sh -- echo "done"
The workload may take longer to start. Check the GVC locations and image availability.

​
Next steps

Execute Commands

Run commands in existing workloads

Connect to Workloads

Interactive shell in running workloads

Create a Workload

Create persistent workloads

Command Reference

Full run command reference