Copy Files to/from Workloads

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

CLI installed

Install the Control Plane CLI before proceeding. See Installation.

Running workload

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

Container has tar

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.

Required permissions

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

Option	Description
`--location`	Target location (defaults to first available in GVC)
`--replica`	Target replica (defaults to first replica)
`--container`	Target container (defaults to first container)
`--no-preserve`	Don’t preserve ownership and permissions

Copy to a workload

File
Directory
Rename on copy

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 an entire directory:

cpln cp ./data my-app:/app/data

The directory and all contents are copied recursively.

Copy and rename in one command:

cpln cp local.json my-app:/app/config/settings.json

Copy from a workload

File
Directory
Rename on copy

Download a file from a container:

cpln cp my-app:/var/log/app.log ./logs/

Download an entire directory:

cpln cp my-app:/app/generated ./output/

Download and rename:

cpln cp my-app:/app/data.json ./backup-data.json

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

tar: not found

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

Permission denied

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/

No replicas found

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

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Copy Files to/from Workloads

When to use this

Upload configuration files

Download logs or data

Debug running workloads

Migrate data

Prerequisites

Basic usage

Options

Copy to a workload

Copy from a workload

Target specific replicas

Multi-container workloads

Common workflows

Upload a configuration file

Download application logs

Transfer debug tools

Troubleshooting

Next steps

Execute Commands

Connect to Workloads

Port Forwarding

Command Reference

​When to use this

Upload configuration files

Download logs or data

Debug running workloads

Migrate data

​Prerequisites

​Basic usage

​Options

​Copy to a workload

​Copy from a workload

​Target specific replicas

​Multi-container workloads

​Common workflows

​Upload a configuration file

​Download application logs

​Transfer debug tools

​Troubleshooting

​Next steps

Execute Commands

Connect to Workloads

Port Forwarding

Command Reference

When to use this

Prerequisites

Basic usage

Options

Copy to a workload

Copy from a workload

Target specific replicas

Multi-container workloads

Common workflows

Upload a configuration file

Download application logs

Transfer debug tools

Troubleshooting

Next steps