Skip to main content
The cpln workload exec command runs commands inside a container and returns the output. Unlike connect, it’s designed for non-interactive commands and scripts, similar to docker exec or kubectl exec.

​
When to use this

Run scripts

Execute maintenance scripts, health checks, or one-off commands

Automation

Run commands from CI/CD pipelines or monitoring systems

Quick commands

Check environment variables, list files, or test connectivity

Scripted debugging

Run diagnostic commands and capture output

​
Prerequisites

Install the Control Plane CLI. See Installation.
You need a running workload in at least one location. See the Create a Workload guide.
You need exec permission on the workload. See Workload Permissions.

​
Basic usage

cpln workload exec <workload> -- <command> [args...]
The -- separates the CLI options from the command to execute.

​
Options

OptionDescription
--locationTarget location (defaults to first available in GVC)
--replicaTarget a specific replica (defaults to first replica)
--containerTarget a specific container (defaults to first container)
-i, --stdinPass stdin to the container
-t, --ttyAllocate a TTY
-q, --quietOnly print output from the remote session

​
Run a simple command

cpln workload exec my-app -- echo "Hello, World!"
Output: 
Hello, World!

​
Run commands with arguments

cpln workload exec my-app -- ls -la

​
Target specific locations or replicas

cpln workload exec my-app --location aws-eu-central-1 -- cat /etc/hostname

​
Interactive mode

Combine -i (stdin) and -t (TTY) for interactive commands: 
cpln workload exec my-app -it -- /bin/bash
For interactive sessions, consider using cpln workload connect which provides a simpler experience.

​
Pipe input to commands

Use -i to pipe data into a container: 
# Pipe a SQL file into psql
cat schema.sql | cpln workload exec postgres-db -i -- psql -U postgres

# Pipe JSON data to a script
echo '{"key": "value"}' | cpln workload exec my-app -i -- python process.py

​
Quiet mode

Suppress CLI output and show only command output: 
cpln workload exec my-app -q -- cat /app/version.txt
Useful for capturing output in scripts: 
VERSION=$(cpln workload exec my-app -q -- cat /app/version.txt)
echo "Deployed version: $VERSION"

​
Common workflows

​
Check environment variables

cpln workload exec my-app -- env | grep -E "^(DATABASE|API)"

​
View logs

cpln workload exec my-app -- tail -100 /var/log/app.log

​
Check disk usage

cpln workload exec my-app -- df -h

​
Test network connectivity

cpln workload exec my-app -- curl -s http://api-service:8080/health

​
Run database queries

cpln workload exec postgres-db -- psql -U postgres -c "SELECT count(*) FROM users;"

​
Troubleshooting

The command may not exist in the container. Check what’s available:
cpln workload exec my-app -- which bash
cpln workload exec my-app -- ls /bin /usr/bin
The command may require elevated permissions, or you lack exec permission on the workload.
The workload may not be running:
cpln workload get my-app
cpln workload replica get my-app
Ensure -- separates CLI options from the command:
# Correct
cpln workload exec my-app -- ls -la

# Incorrect - CLI will try to parse -la
cpln workload exec my-app ls -la

​
Next steps

Connect to Workloads

Interactive shell access

Copy Files

Transfer files to/from workloads

Port Forwarding

Access workload ports locally

Command Reference

Full exec command reference