> ## 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 Commands with Cron Workloads

> Use a persistent cron workload runner to execute commands with better performance.

The `cpln workload cron run` command runs a command using a persistent suspended cron workload. The runner workload is created on first use and reused for subsequent runs, avoiding the overhead of creating and deleting a workload each time.

<Tip>
  This is the recommended approach for running one-off commands. If you need to create a temporary standard workload instead (e.g., to clone an existing workload's configuration), use [`cpln workload run`](/guides/cli/workload/run).
</Tip>

## When to use this

<CardGroup cols={2}>
  <Card title="Run migrations" icon="database">
    Execute database migrations with fast startup times
  </Card>

  <Card title="Recurring scripts" icon="rotate">
    Run maintenance scripts repeatedly without workload creation overhead
  </Card>

  <Card title="Background jobs" icon="clock">
    Fire-and-forget jobs that run without blocking your terminal
  </Card>

  <Card title="Interactive debugging" icon="terminal">
    Connect to an interactive session inside the runner workload
  </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 cron run -- <command> [args...]
```

On first use, this:

1. Creates a persistent suspended cron workload as the runner
2. Starts a job execution with your command
3. Waits for the job to complete and outputs the result

On subsequent runs, the existing runner workload is reused, making startup significantly faster.

## Options

| Option                    | Description                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--image`                 | Override image                                                                                              |
| `-i, --interactive`       | Make the session interactive                                                                                |
| `-b, --background`        | Run in background without waiting for completion (fire and forget)                                          |
| `-t, --timeout <seconds>` | Maximum time to wait for job completion (default: 600)                                                      |
| `--cpu`                   | Set allocated CPU for the main container                                                                    |
| `--memory, --mem`         | Set allocated memory for the main container                                                                 |
| `--env`                   | Environment variables in KEY=VALUE format (can be specified multiple times)                                 |
| `-s, --shell`             | Shell to use when interactive flag is true (default: `bash`)                                                |
| `--location`              | Location to run the command                                                                                 |
| `--container`             | Which container to run the command in                                                                       |
| `--tag`                   | Attach tags (e.g., `--tag drink=water`)                                                                     |
| `--identity`              | Identity to assign to the cron runner workload. Reuses an existing runner with that identity if one exists. |

<Warning>
  `--interactive` and `--background` are mutually exclusive.
</Warning>

## Execution modes

### Default (wait for completion)

Waits for the job to complete and outputs the final status:

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

### Background mode

Fires and forgets, outputting the job ID immediately:

```bash theme={null}
cpln workload cron run --image node:20 --background -- npm run db:migrate
```

Use this for long-running tasks where you don't need to wait for the result.

### Interactive mode

Waits for the job to start, then connects via WebSocket for an interactive terminal session:

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

### Specify a shell

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

## Use a custom image

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

## Common workflows

<Note>
  The cron runner uses `ubuntu:latest` by default, which won't have your application tools (Node.js, Python, etc.). Use `--image` to specify an image that has the tools your command needs.
</Note>

### Run database migrations

```bash theme={null}
cpln workload cron run \
  --image node:20 \
  -- npm run db:migrate
```

### Run data processing in the background

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

### Pass environment variables

```bash theme={null}
cpln workload cron run \
  --image node:20 \
  --env APP_MODE=maintenance \
  --env LOG_LEVEL=debug \
  -- node maintenance-script.js
```

### Run in a specific location

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

<Note>
  The specified location must be enabled in your GVC. You can check your GVC's locations with `cpln gvc get <gvc-name>`.
</Note>

### Add tags for tracking

```bash theme={null}
cpln workload cron run \
  --image node:20 \
  --tag job=nightly-backup \
  --tag env=prod \
  -- node backup.js
```

## Assign an identity

Use `--identity` to assign a specific identity to the cron runner workload. If a runner with that identity already exists, it will be reused instead of creating a new one:

```bash theme={null}
cpln workload cron run \
  --identity my-service-identity \
  --image node:20 \
  -- node scripts/access-cloud-resources.js
```

This is useful when your command needs to access cloud resources or secrets that require a specific identity's permissions.

## Resource configuration

Override CPU and memory for resource-intensive tasks:

```bash theme={null}
cpln workload cron run \
  --image python:3.11 \
  --cpu 200m \
  --memory 512Mi \
  -- python heavy-computation.py
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Timeout waiting for job completion">
    The default timeout is 600 seconds. For long-running tasks, specify an image with the tools you need and increase the timeout:

    ```bash theme={null}
    cpln workload cron run --image python:3.11 --timeout 1800 -- python long-running-task.py
    ```

    Alternatively, use `--background` for tasks that don't need to wait for completion.
  </Accordion>

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

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

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

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

## Next steps

<CardGroup cols={2}>
  <Card title="Run One-off Workloads" href="/guides/cli/workload/run" icon="play">
    Create temporary standard workloads for one-off tasks
  </Card>

  <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="Command Reference" href="/cli-reference/commands/workload#workload-cron-run" icon="book">
    Full cron run command reference
  </Card>
</CardGroup>