> ## 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.

# 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">
    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.
  </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>