> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Copy Files to/from Workloads

> Transfer files and directories between your local machine and running workload containers.

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

<CardGroup cols={2}>
  <Card title="Upload configuration files" icon="upload">
    Copy config files, scripts, or data to a running container
  </Card>

  <Card title="Download logs or data" icon="download">
    Retrieve log files, generated data, or debug artifacts from containers
  </Card>

  <Card title="Debug running workloads" icon="bug">
    Transfer debugging tools or inspect container state
  </Card>

  <Card title="Migrate data" icon="right-left">
    Move files between local development and deployed workloads
  </Card>
</CardGroup>

## Prerequisites

<AccordionGroup>
  <Accordion title="CLI installed">
    Install the Control Plane CLI before proceeding. See [Installation](/cli-reference/installation).
  </Accordion>

  <Accordion title="Running workload">
    You need a running [workload](/reference/workload) in at least one location. See the [Create a Workload](/guides/create-workload) guide.
  </Accordion>

  <Accordion title="Container has tar">
    The `tar` binary must be installed in the container image.

    <Warning>
      If your container image doesn't include `tar`, the `cpln cp` command will fail. Most standard images (Debian, Ubuntu, Alpine) include it by default.
    </Warning>
  </Accordion>

  <Accordion title="Required permissions">
    You need `exec` permission on the workload. See [Workload Permissions](/reference/workload#permissions).
  </Accordion>
</AccordionGroup>

## Basic usage

```bash theme={null}
# 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

<Tabs>
  <Tab title="File">
    Copy a local file to a container:

    ```bash theme={null}
    cpln cp config.json my-app:/app/config/
    ```

    The file is placed in `/app/config/config.json` in the container.
  </Tab>

  <Tab title="Directory">
    Copy an entire directory:

    ```bash theme={null}
    cpln cp ./data my-app:/app/data
    ```

    The directory and all contents are copied recursively.
  </Tab>

  <Tab title="Rename on copy">
    Copy and rename in one command:

    ```bash theme={null}
    cpln cp local.json my-app:/app/config/settings.json
    ```
  </Tab>
</Tabs>

## Copy from a workload

<Tabs>
  <Tab title="File">
    Download a file from a container:

    ```bash theme={null}
    cpln cp my-app:/var/log/app.log ./logs/
    ```
  </Tab>

  <Tab title="Directory">
    Download an entire directory:

    ```bash theme={null}
    cpln cp my-app:/app/generated ./output/
    ```
  </Tab>

  <Tab title="Rename on copy">
    Download and rename:

    ```bash theme={null}
    cpln cp my-app:/app/data.json ./backup-data.json
    ```
  </Tab>
</Tabs>

## Target specific replicas

When a workload has multiple replicas across locations, specify the exact target:

```bash theme={null}
cpln cp config.json my-app:/app/ \
  --location aws-us-west-2 \
  --replica my-app-7f8d9c-abc12
```

<Tip>
  Use `cpln workload replica get <workload>` to list available replicas and their locations.
</Tip>

## Multi-container workloads

For workloads with multiple containers, specify the target container:

```bash theme={null}
cpln cp logs.sh my-app:/scripts/ --container sidecar
```

<Note>
  If `--container` is not specified, the command targets the first container defined in the workload spec.
</Note>

## Common workflows

### Upload a configuration file

```bash theme={null}
# Copy config to a specific environment
cpln cp production.env my-app:/app/.env --gvc production
```

### Download application logs

```bash theme={null}
# Get logs from a specific location
cpln cp my-app:/var/log/app/ ./debug-logs/ --location aws-eu-central-1
```

### Transfer debug tools

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="Permission denied">
    The destination path may require elevated permissions. Try copying to `/tmp/` first, then move with `exec`:

    ```bash theme={null}
    cpln cp file.txt my-app:/tmp/
    cpln workload exec my-app -- mv /tmp/file.txt /app/
    ```
  </Accordion>

  <Accordion title="No replicas found">
    The workload may not be running in the specified location:

    ```bash theme={null}
    # Check workload status
    cpln workload get my-app

    # List replicas
    cpln workload replica get my-app
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Execute Commands" href="/guides/cli/workload/exec" icon="terminal">
    Run commands inside containers
  </Card>

  <Card title="Connect to Workloads" href="/guides/cli/workload/connect" icon="plug">
    Interactive shell access
  </Card>

  <Card title="Port Forwarding" href="/guides/cli/cpln-port-forward" icon="network-wired">
    Access workload ports locally
  </Card>

  <Card title="Command Reference" href="/cli-reference/commands/cp" icon="book">
    Full cp command reference
  </Card>
</CardGroup>