Skip to main content
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

Install the Control Plane CLI. See Installation.
You need create and exec permissions on workloads. See Workload Permissions.

​
Basic usage

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

OptionDescription
--imageOverride image
-i, --interactiveMake the session interactive
-b, --backgroundRun in background without waiting for completion (fire and forget)
-t, --timeout <seconds>Maximum time to wait for job completion (default: 600)
--cpuSet allocated CPU for the main container
--memory, --memSet allocated memory for the main container
--envEnvironment variables in KEY=VALUE format (can be specified multiple times)
-s, --shellShell to use when interactive flag is true (default: bash)
--locationLocation to run the command
--containerWhich container to run the command in
--tagAttach tags (e.g., --tag drink=water)
--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

​
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

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.
The default image may not have your tool. Use a custom image:
cpln workload cron run --image node:20 -- npm --version
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