PyCuerun User Guide

This guide covers the full capabilities of pycuerun for submitting and managing OpenCue jobs from the command line.

Note: PyCuerun is the CLI frontend for PyOutline, the Python library that defines job structure (outlines, layers, dependencies). PyCuerun loads PyOutline scripts, serializes them, and submits them to the render farm. Both ship in the same opencue-pyoutline package.

Basic Usage

Submitting a Job 

pycuerun [options] outline_script [frame_range]

The simplest invocation:

pycuerun my_render.outline

Specifying a Frame Range

Override the script’s default frame range:

pycuerun -f 1-100 my_render.outline

Or pass the frame range as a positional argument:

pycuerun my_render.outline 1-100

Frame range formats:

Format Meaning
1-100 Frames 1 through 100
1-100x5 Every 5th frame (1, 6, 11, …)
1,5,10,20 Specific frames
1-50,75-100 Multiple ranges

If no range is specified, pycuerun uses the $FR environment variable.

Job Control Options

Paused Launch

Launch the job in a paused state. Frames will not begin processing until you manually resume:

pycuerun -p my_render.outline

Wait for Completion

Block the terminal until the job finishes:

pycuerun -w my_render.outline

Test Mode

Block until completion and return a non-zero exit code if any frames fail:

pycuerun -t my_render.outline

This is useful in CI/CD pipelines or automated workflows.

Retry Control

Set the maximum number of retries per frame:

pycuerun --max-retries 3 my_render.outline

Auto-Eat Dead Frames

Automatically remove dead frames without retrying:

pycuerun --autoeat my_render.outline

Disable Email

Suppress email notifications:

pycuerun --no-mail my_render.outline

Target Configuration

Facility

Route the job to a specific facility:

pycuerun -F cloud_render my_render.outline

Operating System

Target a specific OS for execution:

pycuerun -o Linux my_render.outline

Server

Specify a Cuebot server:

pycuerun -s cuebot.example.com my_render.outline

Shot Override

Run the job under a different shot context:

pycuerun --shot sh020 my_render.outline

Job Base Name

Override the job’s base name:

pycuerun --base-name custom-job-name my_render.outline

Debugging and Development

Inspect a Script

View the structure of an outline script without submitting:

pycuerun -i my_render.outline

This displays layer names, frame ranges, and dependencies.

Execute a Single Frame

Run a specific frame locally for debugging:

pycuerun -e 5-render my_render.outline

The format is {frame_number}-{layer_name}.

Debug Mode

Enable debug logging:

pycuerun -D my_render.outline

Verbose Output

Enable verbose output:

pycuerun -V my_render.outline

Development Mode

Test with your local development version of PyOutline:

pycuerun --dev my_render.outline

Or test with another user’s development version:

pycuerun --dev-user colleague my_render.outline

Environment Variables

Setting Variables

Pass environment variables to the job:

pycuerun --env QUALITY=high --env RENDER_ENGINE=arnold my_render.outline

Key Environment Variables

Variable Purpose
CUEBOT_HOSTS Cuebot server address
SHOW Default show name
SHOT Default shot name
FR Default frame range
RENDER_TO / FACILITY Default facility
OL_VERSION PyOutline version override

Backend Selection

OpenCue Backend (default)

Submit to the Cuebot render farm:

pycuerun -b cue my_render.outline

Local Backend

Execute frames locally for testing:

pycuerun -b local my_render.outline

The local backend runs frames sequentially using a SQLite dispatcher and respects dependency order.

QC Integration

Add a Quality Control layer that pauses the job for artist review:

pycuerun --qc my_render.outline

This adds a wait_on_artist_to_qc layer that depends on all other layers and pauses execution for review.

Plugin Options

Local Cores

Book local machine resources for frame execution:

pycuerun -L 4 my_render.outline

Local Thread Count

Set threads per frame for local execution:

pycuerun -T 2 my_render.outline

Version Management

Pin a Specific Version 

pycuerun -v 1.2.3 my_render.outline

Specify a Repository Path 

pycuerun -r /path/to/pyoutline my_render.outline

Common Workflows

Render and Wait 

pycuerun -w -f 1-100 --max-retries 3 my_render.outline

CI/CD Test Submission 

pycuerun -t --no-mail -f 1-10 my_render.outline || echo "Job failed"

Debug a Failing Frame 

# First inspect the script
pycuerun -i my_render.outline

# Then execute the failing frame locally with debug logging
pycuerun -D -e 42-render my_render.outline

Paused Review Workflow 

# Launch paused for artist review
pycuerun -p --qc my_render.outline

# Artist reviews and resumes via CueGUI

Back to top