Run Commands with Cron Workloads

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.

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.

When to use this

Run migrations

Execute database migrations with fast startup times

Recurring scripts

Run maintenance scripts repeatedly without workload creation overhead

Background jobs

Fire-and-forget jobs that run without blocking your terminal

Interactive debugging

Connect to an interactive session inside the runner workload

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Required permissions

You need create and exec permissions on workloads. See Workload Permissions.

Basic usage

cpln workload cron run -- <command> [args...]

On first use, this:

Creates a persistent suspended cron workload as the runner
Starts a job execution with your command
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.

--interactive and --background are mutually exclusive.

Execution modes

Default (wait for completion)

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

cpln workload cron run -- echo "Hello from Control Plane!"

Background mode

Fires and forgets, outputting the job ID immediately:

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:

cpln workload cron run --interactive -- bash

Specify a shell

cpln workload cron run --interactive --shell sh -- cat /etc/os-release

Use a custom image

cpln workload cron run --image python:3.11 -- python --version

Common workflows

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.

Run database migrations

cpln workload cron run \
  --image node:20 \
  -- npm run db:migrate

Run data processing in the background

cpln workload cron run \
  --image python:3.11 \
  --background \
  --cpu 500m \
  --memory 1Gi \
  -- python /scripts/process-data.py

Pass environment variables

cpln workload cron run \
  --image node:20 \
  --env APP_MODE=maintenance \
  --env LOG_LEVEL=debug \
  -- node maintenance-script.js

Run in a specific location

cpln workload cron run --location aws-eu-central-1 -- curl -s https://api.example.com

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

Add tags for tracking

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:

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:

cpln workload cron run \
  --image python:3.11 \
  --cpu 200m \
  --memory 512Mi \
  -- python heavy-computation.py

Troubleshooting

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:

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.

Command not found

The default image may not have your tool. Use a custom image:

cpln workload cron run --image node:20 -- npm --version

Shell not available

Specify a different shell for interactive sessions:

cpln workload cron run --interactive --shell sh -- echo "done"

Next steps

Run One-off Workloads

Create temporary standard workloads for one-off tasks

Execute Commands

Run commands in existing workloads

Connect to Workloads

Interactive shell in running workloads

Command Reference

Full cron run command reference

​When to use this

Run migrations

Recurring scripts

Background jobs

Interactive debugging

​Prerequisites

​Basic usage

​Options

​Execution modes

​Default (wait for completion)

​Background mode

​Interactive mode

​Specify a shell

​Use a custom image

​Common workflows

​Run database migrations

​Run data processing in the background

​Pass environment variables

​Run in a specific location

​Add tags for tracking

​Assign an identity

​Resource configuration

​Troubleshooting

​Next steps

Run One-off Workloads

Execute Commands

Connect to Workloads

Command Reference

When to use this

Prerequisites

Basic usage

Options

Execution modes

Default (wait for completion)

Background mode

Interactive mode

Specify a shell

Use a custom image

Common workflows

Run database migrations

Run data processing in the background

Pass environment variables

Run in a specific location

Add tags for tracking

Assign an identity

Resource configuration

Troubleshooting

Next steps