Skip to main content
The cpln cp command copies files and directories between your local machine and workload containers, similar to kubectl cp or docker cp.

​
When to use this

Upload configuration files

Copy config files, scripts, or data to a running container

Download logs or data

Retrieve log files, generated data, or debug artifacts from containers

Debug running workloads

Transfer debugging tools or inspect container state

Migrate data

Move files between local development and deployed workloads

​
Prerequisites

Install the Control Plane CLI before proceeding. See Installation.
You need a running workload in at least one location. See the Create a Workload guide.
The tar binary must be installed in the container image.
If your container image doesn’t include tar, the cpln cp command will fail. Most standard images (Debian, Ubuntu, Alpine) include it by default.
You need exec permission on the workload. See Workload Permissions.

​
Basic usage

# Copy to workload
cpln cp <local-path> <workload>:<container-path>

# Copy from workload
cpln cp <workload>:<container-path> <local-path>

​
Options

OptionDescription
--locationTarget location (defaults to first available in GVC)
--replicaTarget replica (defaults to first replica)
--containerTarget container (defaults to first container)
--no-preserveDon’t preserve ownership and permissions

​
Copy to a workload

Copy a local file to a container:
cpln cp config.json my-app:/app/config/
The file is placed in /app/config/config.json in the container.

​
Copy from a workload

Download a file from a container:
cpln cp my-app:/var/log/app.log ./logs/

​
Target specific replicas

When a workload has multiple replicas across locations, specify the exact target: 
cpln cp config.json my-app:/app/ \
  --location aws-us-west-2 \
  --replica my-app-7f8d9c-abc12
Use cpln workload replica get <workload> to list available replicas and their locations.

​
Multi-container workloads

For workloads with multiple containers, specify the target container: 
cpln cp logs.sh my-app:/scripts/ --container sidecar
If --container is not specified, the command targets the first container defined in the workload spec.

​
Common workflows

​
Upload a configuration file

# Copy config to a specific environment
cpln cp production.env my-app:/app/.env --gvc production

​
Download application logs

# Get logs from a specific location
cpln cp my-app:/var/log/app/ ./debug-logs/ --location aws-eu-central-1

​
Transfer debug tools

# Upload a debugging script
cpln cp debug.sh my-app:/tmp/
cpln workload exec my-app -- chmod +x /tmp/debug.sh
cpln workload exec my-app -- /tmp/debug.sh

​
Troubleshooting

The container image doesn’t include tar. Either:
  • Use an image with tar installed
  • Install it in your Dockerfile: RUN apt-get install -y tar
  • For Alpine: RUN apk add --no-cache tar
The destination path may require elevated permissions. Try copying to /tmp/ first, then move with exec:
cpln cp file.txt my-app:/tmp/
cpln workload exec my-app -- mv /tmp/file.txt /app/
The workload may not be running in the specified location:
# Check workload status
cpln workload get my-app

# List replicas
cpln workload replica get my-app

​
Next steps

Execute Commands

Run commands inside containers

Connect to Workloads

Interactive shell access

Port Forwarding

Access workload ports locally

Command Reference

Full cp command reference