Skip to main content
The cpln workload connect command opens an interactive terminal session to a running container, similar to docker exec -it or kubectl exec -it. Use it to inspect container state, debug issues, or run commands interactively.

​
When to use this

Interactive debugging

Explore container filesystem, check processes, and inspect state

Troubleshooting

Diagnose issues directly inside the running container

Manual operations

Run one-off commands, database migrations, or maintenance tasks

Log inspection

View logs and files that aren’t exposed externally

​
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 connect <workload>
This opens a bash shell in the first available container and replica.

​
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)
--shell, -sShell to use (default: bash)

​
Connect to a specific location

cpln workload connect my-app --location aws-eu-central-1
List available locations with cpln workload get-deployments my-app.

​
Connect to a specific replica

When a workload has multiple replicas, target a specific one: 
# List replicas
cpln workload replica get my-app --location aws-eu-central-1

# Connect to a specific replica
cpln workload connect my-app --replica my-app-7f8d9c-abc12

​
Connect to a specific container

For workloads with multiple containers (sidecars, init containers): 
cpln workload connect my-app --container sidecar

​
Use a different shell

Some containers don’t have bash. Use sh or another shell: 
cpln workload connect my-app --shell sh

​
Common workflows

​
Debug a crashing container

# Connect and check logs
cpln workload connect my-app
cat /var/log/app.log

# Check processes
ps aux

# Check environment
env | grep -i config

​
Inspect database state

cpln workload connect postgres-db --shell sh

# Inside the container
psql -U postgres -c "SELECT * FROM users LIMIT 10;"

​
Check filesystem

cpln workload connect my-app

# Check disk usage
df -h

# Find large files
du -sh /app/*

​
Run a migration

cpln workload connect my-app

# Run database migration for example
npm run migrate
# or
python manage.py migrate

​
Troubleshooting

The container doesn’t have bash. Use a different shell:
cpln workload connect my-app --shell sh
Alpine-based images typically use ash or sh.
The workload may not be running:
cpln workload get my-app
cpln workload replica get my-app
Wait for replicas to start or check the workload configuration.
The shell may be exiting. Try with a different shell or check container health:
cpln workload get-deployments my-app
You need exec permission on the workload. Check your policies or contact your admin.

​
Next steps

Execute Commands

Run non-interactive commands

Copy Files

Transfer files to/from workloads

Port Forwarding

Access workload ports locally

Command Reference

Full connect command reference