> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-jakob-ess-2-0-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run One-off Workloads

> Create temporary workloads to run commands, scripts, or debugging sessions.

The `cpln workload run` command creates a temporary workload, waits for it to become healthy, executes your command, and optionally cleans up. It's similar to `docker run` - perfect for one-off tasks, debugging, and running scripts in your cloud environment.

<Tip>
  **Recommendation:** Consider using [`cpln workload cron run`](/guides/cli/workload/cron-run) instead — it's significantly faster and the preferred way to run commands going forward. It uses a persistent cron workload runner that is reused across executions, eliminating the overhead of creating and tearing down a workload each time.
</Tip>

## When to use this

<CardGroup cols={2}>
  <Card title="Run migrations" icon="database">
    Execute database migrations in your production environment
  </Card>

  <Card title="One-off scripts" icon="play">
    Run maintenance scripts, data processing, or cleanup tasks
  </Card>

  <Card title="Debug with clones" icon="bug">
    Clone an existing workload to debug in an isolated environment
  </Card>

  <Card title="Quick tests" icon="vial">
    Spin up temporary containers to test configurations
  </Card>
</CardGroup>

## Prerequisites

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

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

## Basic usage

```bash theme={null}
cpln workload run -- <command> [args...]
```

By default, this:

1. Creates a temporary workload using `ubuntu:22.04`
2. Waits for it to become healthy
3. Executes the command
4. Exits (workload remains unless `--rm` is used)

## Options

| Option              | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `--clone`           | Clone an existing workload instead of using the default image |
| `--image`           | Use a custom image                                            |
| `--rm, --remove`    | Delete the workload after the command completes               |
| `-i, --interactive` | Keep the session open after command execution                 |
| `--container`       | Target container (when cloning multi-container workloads)     |
| `--cpu`             | CPU allocation (e.g., `50m`, `100m`)                          |
| `--memory, --mem`   | Memory allocation (e.g., `128Mi`, `256Mi`)                    |
| `--shell, -s`       | Shell to use for interactive mode (default: `bash`)           |
| `--location`        | Target location                                               |
| `--tag`             | Add tags to the temporary workload                            |
| `-c, --command`     | Override container command                                    |
| `-a, --arg`         | Override container args                                       |

## Run a simple command

```bash theme={null}
cpln workload run -- echo "Hello from Control Plane!"
```

## Use a custom image

```bash theme={null}
cpln workload run --image python:3.11 -- python --version
```

## Clone an existing workload

Run commands in an environment identical to an existing workload:

```bash theme={null}
cpln workload run --clone my-app -- npm run migrate
```

This clones `my-app` with all its configuration (env vars, secrets, identity) and runs the command.

### Target a specific container

For multi-container workloads:

```bash theme={null}
cpln workload run --clone my-app --container worker -- python process.py
```

## Automatic cleanup

Delete the temporary workload after the command completes:

```bash theme={null}
cpln workload run --rm -- echo "Hello from Control Plane!"
```

<Tip>
  Use `--rm` for one-off tasks to avoid accumulating temporary workloads.
</Tip>

## Interactive mode

Stay in the container after the command runs:

```bash theme={null}
cpln workload run --interactive -- ls -la
```

After the command executes, you'll have an interactive shell to continue working.

### Specify a shell

```bash theme={null}
cpln workload run --interactive --shell sh -- cat /etc/os-release
```

## Common workflows

### Run database migrations

```bash theme={null}
cpln workload run --clone my-app --rm -- npm run db:migrate
```

### Debug in a cloned environment

```bash theme={null}
cpln workload run --clone production-api --interactive -- bash
```

### Run data processing

```bash theme={null}
cpln workload run \
  --image python:3.11 \
  --cpu 500m \
  --memory 1Gi \
  --rm \
  -- python /scripts/process-data.py
```

### Test in a specific location

```bash theme={null}
cpln workload run --location aws-eu-central-1 -- curl -s https://api.example.com
```

### Add tags for tracking

```bash theme={null}
cpln workload run --tag job=nightly-backup --tag env=prod --rm -- ./backup.sh
```

## Resource configuration

Override CPU and memory for resource-intensive tasks:

```bash theme={null}
cpln workload run \
  --cpu 200m \
  --memory 512Mi \
  -- ./heavy-computation.sh
```

## Override container command

Replace the container's default command:

```bash theme={null}
cpln workload run \
  --image myapp:latest \
  --command sleep \
  --arg "infinity" \
  --interactive \
  -- bash
```

This starts the container with `sleep infinity` instead of its default command, then opens a bash session.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Workload never becomes ready">
    Run with `--verbose` to see what the platform reports about the deployment while the command waits:

    ```bash theme={null}
    cpln workload run --verbose -- echo hello
    ```

    Each time the reported status changes, it is written to stderr — naming the containers that are not ready yet and any message the platform attached, such as a deployment paused because it cannot reveal a referenced secret, or an image that cannot be pulled.

    If the status shows nothing unusual, the location may not be available in your GVC:

    ```bash theme={null}
    cpln gvc get my-gvc
    ```

    Verify the location is in the GVC's `staticPlacement.locationLinks`.
  </Accordion>

  <Accordion title="Command not found">
    The default Ubuntu image may not have your tool. Use a custom image:

    ```bash theme={null}
    cpln workload run --image node:20 -- npm --version
    ```
  </Accordion>

  <Accordion title="Shell not available">
    Specify a different shell:

    ```bash theme={null}
    cpln workload run --interactive --shell sh -- echo "done"
    ```
  </Accordion>

  <Accordion title="Timeout waiting for workload">
    The workload may take longer to start. Check the GVC locations and image availability.

    The error names the last status the platform reported, which usually identifies the container that never became ready. Run with `--verbose` to follow that status from the start of the wait.
  </Accordion>
</AccordionGroup>

## Next steps

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

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

  <Card title="Create a Workload" href="/guides/create-workload" icon="cube">
    Create persistent workloads
  </Card>

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