Execute Commands in Workloads

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

CLI installed

Install the Control Plane CLI. See Installation.

Running workload

You need a running workload in at least one location. See the Create a Workload guide.

Required permissions

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

Option	Description
`--location`	Target location (defaults to first available in GVC)
`--replica`	Target a specific replica (defaults to first replica)
`--container`	Target a specific container (defaults to first container)
`-i, --stdin`	Pass stdin to the container
`-t, --tty`	Allocate a TTY
`-q, --quiet`	Only 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

Specific location
Specific replica
Specific container

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

cpln workload exec my-app --replica my-app-7f8d9c-abc12 -- cat /etc/hostname

cpln workload exec my-app --container sidecar -- ps aux

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

Command not found

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

Permission denied

The command may require elevated permissions, or you lack exec permission on the workload.

No replicas found

The workload may not be running:

cpln workload get my-app
cpln workload replica get my-app

Command arguments parsed incorrectly

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

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Execute Commands in Workloads

When to use this

Run scripts

Automation

Quick commands

Scripted debugging

Prerequisites

Basic usage

Options

Run a simple command

Run commands with arguments

Target specific locations or replicas

Interactive mode

Pipe input to commands

Quiet mode

Common workflows

Check environment variables

View logs

Check disk usage

Test network connectivity

Run database queries

Troubleshooting

Next steps

Connect to Workloads

Copy Files

Port Forwarding

Command Reference

​When to use this

Run scripts

Automation

Quick commands

Scripted debugging

​Prerequisites

​Basic usage

​Options

​Run a simple command

​Run commands with arguments

​Target specific locations or replicas

​Interactive mode

​Pipe input to commands

​Quiet mode

​Common workflows

​Check environment variables

​View logs

​Check disk usage

​Test network connectivity

​Run database queries

​Troubleshooting

​Next steps

Connect to Workloads

Copy Files

Port Forwarding

Command Reference

When to use this

Prerequisites

Basic usage

Options

Run a simple command

Run commands with arguments

Target specific locations or replicas

Interactive mode

Pipe input to commands

Quiet mode

Common workflows

Check environment variables

View logs

Check disk usage

Test network connectivity

Run database queries

Troubleshooting

Next steps