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
CLI installed
CLI installed
Install the Control Plane CLI. See Installation.
Running workload
Running workload
You need a running workload in at least one location. See the Create a Workload guide.
Required permissions
Required permissions
You need
exec permission on the workload. See Workload Permissions.Connect via Console
You can connect to workloads directly from the Control Plane Console:1
Navigate to workload
Open your workload in the Console.
2
Click Connect
In the left pane, click Connect.
3
Configure connection
Use the dropdowns to select:
- Location: The deployment location to connect to
- Container: The container within the workload
- Replica: The specific replica instance
4
Enter command
Type the shell command to use (e.g.,
bash, sh, node).5
Connect
Click Connect to open an interactive terminal session in your browser.
Connect via CLI
Basic usage
bash shell in the first available container and replica.
Options
Connect to a specific location
Connect to a specific replica
When a workload has multiple replicas, target a specific one:Connect to a specific container
For workloads with multiple containers (sidecars, init containers):Use a different shell
Some containers don’t havebash. Use sh or another shell:
- sh
- ash (Alpine)
- zsh
Common workflows
Debug a crashing container
Inspect database state
Check filesystem
Run a migration
Troubleshooting
bash: not found
bash: not found
The container doesn’t have bash. Use a different shell:Alpine-based images typically use
ash or sh.No replicas found
No replicas found
The workload may not be running:Wait for replicas to start or check the workload configuration.
Connection closed immediately
Connection closed immediately
The shell may be exiting. Try with a different shell or check container health:
Permission denied
Permission denied
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