CLI Reference

Complete reference documentation for the Renku command-line interface.

Global Options

These options apply to all commands:

Option	Description
--help, -h	Show help for any command
--version, -v	Show CLI version

Commands

renku init

Initialize a new Renku workspace and storage configuration.

Usage:

renku init --root=/path/to/storage

Options:

Option	Required	Description
--root	Yes	Storage root directory for builds and blueprints

Creates:

• ~/.config/renku/cli-config.json - Storage configuration (fixed location)
• {rootFolder}/.gitignore - Ignores **/builds/ and **/artifacts/
• {rootFolder}/catalog/ containing:
  • models/ - Supported model configurations
  • producers/ - Supported producer definitions
  • blueprints/ - Example blueprints to get started

Note: Builds and artifacts are created in your current working directory when running renku generate, not in the root folder. This supports project-based workflows.

Example:

renku init --root=/Users/alice/renku-projects

---

renku update

Update the catalog in the active workspace by replacing it with the latest bundled catalog (models, producers, and example blueprints).

Usage:

renku update

Behavior:

• Reads the active workspace from the CLI config
• Replaces the workspace catalog/ contents from the bundled catalog (stale files are removed)
• Fails fast if the configured catalog path is not the canonical {workspaceRoot}/catalog path
• Users can revert changes using git if needed

Example:

renku update

---

renku use

Switch to an existing Renku workspace.

Usage:

renku use --root=/path/to/workspace

Options:

Option	Required	Description
--root	Yes	Path to an existing Renku workspace

Behavior:

• Validates the folder is a valid Renku workspace (has catalog)
• Updates the CLI config to point to the specified workspace
• Does not copy any files

Example:

renku use --root=~/other-workspace

---

renku new:blueprint

Create a new blueprint project, either from scratch or by copying an existing blueprint from the catalog.

Usage:

# Create from scratch (scaffold)
renku new:blueprint <name>

# Copy from catalog blueprint
renku new:blueprint <name> --using=<catalog-blueprint>

Arguments:

Argument	Required	Description
<name>	Yes	Name for the new blueprint (kebab-case, e.g., my-video-project)

Options:

Option	Required	Description
--using	No	Name of an existing blueprint in the catalog to copy from

Behavior:

Without --using (scaffold mode):

• Creates a new folder with the blueprint name
• Generates a skeleton blueprint YAML with all required sections
• Generates an input-template.yaml with example structure
• The blueprint ID is auto-generated as PascalCase from the name

With --using (copy mode):

• Copies the entire blueprint folder from the catalog
• Renames the blueprint YAML file to match the new name
• Preserves all files including prompt producers, schemas, etc.

Examples:

# Create a new blueprint from scratch
renku new:blueprint my-video-project

# Create a project based on an existing blueprint
renku new:blueprint my-ken-burns --using=ken-burns

# Create a documentary-style project
renku new:blueprint history-series --using=documentary-talkinghead

Output Structure:

my-video-project/
├── my-video-project.yaml    # Blueprint definition
├── input-template.yaml      # Input template
└── (additional files if copied from catalog)

Notes:

• Always use this command instead of directly referencing catalog blueprints
• Blueprint names must be kebab-case (lowercase with hyphens)
• The blueprint ID in the YAML is automatically converted to PascalCase

---

renku generate

Create a new movie or continue an existing one.

Usage (new movie):

renku generate \
  --inputs=<path> \
  --blueprint=<path> \
  [--dry-run] \
  [--dry-run-profile=<path> | --profile=<path>] \
  [--non-interactive] \
  [--up-to-layer=<n>] \
  [--re-run-from=<n>]

Usage (continue existing):

renku generate --movie-id=<id> --inputs=<path> [options]
renku generate --last --inputs=<path> [options]

Usage (surgical regeneration):

renku generate --last --artifact-id="Artifact:AudioProducer.GeneratedAudio[0]" --inputs=<path> [--up-to-layer=<n>]
renku generate --last --aid="Artifact:AudioProducer.GeneratedAudio[0]" --aid="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=<path> [--up-to-layer=<n>]
renku generate --last --pin="Artifact:ScriptProducer.NarrationScript[0]" --pin="Producer:ImageProducer" --inputs=<path> [options]

Options:

Option	Description
--inputs, --in	Path to inputs YAML file (required)
--blueprint, --bp	Path to blueprint YAML file (required for new movies)
--movie-id, --id	Continue a specific movie by ID
--last	Continue the most recent movie
--dry-run	Execute without calling providers (mock run)
--dry-run-profile, --profile	Use a pre-generated dry-run profile for simulation coverage (requires --dry-run)
--non-interactive	Skip confirmation prompts
--explain	Print plan explanation and cost summary, then exit without execution
--up-to-layer, --up	Stop after specified layer (live runs only)
--re-run-from, --from	Re-run from specified layer (0-indexed), skipping earlier layers
--artifact-id, --artifact, --aid	Regenerate specific artifact(s) and their downstream dependencies (requires --last or --movie-id). Requires canonical Artifact:... IDs. Can be specified multiple times.
--pin	Keep existing outputs from regeneration. Accepts canonical Artifact:... or Producer:... IDs. Repeatable. Requires --last or --movie-id.

Behavior:

For new movies:

1. Validates inputs and blueprint
2. Generates a new movie ID
3. Creates builds/movie-{id}/ directory
4. Executes the workflow

For continuing movies:

1. Runs a pre-plan recovery pass for recoverable failed artifacts (currently fal-ai) using stored provider request IDs
2. Loads existing manifest
3. Detects changed inputs and artifacts (dirty tracking)
4. Applies planning precedence: dirty detection + explicit regenerate (--artifact-id/--aid) - explicit pin (--pin)
5. Regenerates affected artifacts and updates the artifacts view
6. With --explain, includes a recovery summary section (checked, recovered, pending, failed attempts)

Examples:

# New movie with inputs file
renku generate --inputs=./my-inputs.yaml --blueprint=./audio-only.yaml

# Continue specific movie
renku generate --movie-id=movie-a1b2c3d4 --inputs=./updated-inputs.yaml

# Continue most recent movie
renku generate --last --inputs=./inputs.yaml

# Dry run to validate
renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml --dry-run

# Generate a reusable dry-run profile
renku blueprints:dry-run-profile ./blueprint.yaml

# Dry run using a profile file (alias flag)
renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml --dry-run --profile=./blueprint.dry-run-profile.yaml

# Generate up to layer 1 only
renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml --up-to-layer=1

# Re-run from layer 2 (skips layers 0-1, uses existing artifacts)
renku generate --last --inputs=./inputs.yaml --from=2

# Re-run from layer 3 with layer limit
renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml --from=3 --up-to-layer=4

# Surgical regeneration: regenerate only one artifact and its downstream dependencies
renku generate --last --artifact-id="Artifact:AudioProducer.GeneratedAudio[0]" --inputs=./inputs.yaml

# Surgical regeneration with layer limit
renku generate --last --artifact-id="Artifact:ImageProducer.GeneratedImage[2]" --inputs=./inputs.yaml --up-to-layer=1

# Multiple artifact regeneration using --aid alias
renku generate --last --aid="Artifact:AudioProducer.GeneratedAudio[0]" --aid="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

# Multiple artifacts with layer limit
renku generate --last --aid="Artifact:ImageProducer.GeneratedImage[1]" --aid="Artifact:ImageProducer.GeneratedImage[3]" --inputs=./inputs.yaml --up-to-layer=2

# Pin one artifact (keep from regeneration)
renku generate --last --inputs=./inputs.yaml --pin="Artifact:ScriptProducer.NarrationScript[0]"

# Pin all outputs of a producer
renku generate --last --inputs=./inputs.yaml --pin="Producer:ScriptProducer" --from=1

# Multiple pins
renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml --pin="Artifact:AudioProducer.GeneratedAudio[0]" --pin="Producer:ImageProducer"

Note: When using IDs with brackets in zsh, quote the ID to prevent bracket expansion.
Note: Non-canonical --artifact-id/--aid values are rejected; use canonical Artifact:... IDs.
Note: Pins are applied last; a pinned job/artifact is excluded even if dirty or explicitly targeted.

---

renku list

List all builds in the current project directory.

Usage:

renku list

Behavior:

• Scans builds/ in the current working directory
• Shows which builds have artifacts (completed runs) vs. dry-run only builds
• Suggests running renku clean to remove dry-run builds

Example output:

Builds in current project:

  ✓ movie-abc123 (has artifacts)
  ○ movie-def456 (dry-run, no artifacts)
  ○ movie-ghi789 (dry-run, no artifacts)

Run `renku clean` to remove 2 dry-run build(s).

---

renku clean

Remove build artifacts from the current project. By default, only removes dry-run builds (builds without artifacts).

Usage:

renku clean [--movie-id=<id>] [--all] [--dry-run]

Options:

Option	Required	Description
--movie-id, --id	No	Clean a specific movie by ID
--all	No	Clean all builds including those with artifacts
--dry-run	No	Show what would be cleaned without deleting
--non-interactive	No	Skip confirmation prompts

Behavior:

• Without options: Removes all dry-run builds (builds without corresponding artifacts/ folder)
• With --movie-id: Removes only the specified build
• With --all: Removes all builds including those with artifacts

Examples:

# Clean only dry-run builds (safe default)
renku clean

# Preview what would be cleaned
renku clean --dry-run

# Clean a specific movie
renku clean --movie-id=movie-a1b2c3d4

# Clean everything including completed builds
renku clean --all

---

renku export

Export a generated movie to MP4/MP3 format.

Usage:

renku export --movie-id=<id> [options]
renku export --last [options]
renku export --last --inputs=<config.yaml>

CLI Options:

Option	Default	Description
--movie-id, --id	-	Movie ID to export
--last	-	Export the most recent movie
--inputs, --in	-	Path to export config YAML file
--width	1920	Video width in pixels
--height	1080	Video height in pixels
--fps	30	Frames per second
--exporter	remotion	Exporter backend: remotion or ffmpeg

Exporter Backends:

Exporter	Description	Requirements
remotion	Docker-based Remotion renderer (default)	Docker Desktop
ffmpeg	Native FFmpeg renderer	FFmpeg installed

The FFmpeg exporter is faster and requires no Docker, while the Remotion exporter offers more advanced video effects. For audio-only timelines, the FFmpeg exporter produces MP3 files.

Export Config File:

For advanced settings (especially FFmpeg-specific options and subtitles), use a YAML config file:

# Basic settings (can also be set via CLI flags)
width: 1920
height: 1080
fps: 30
exporter: ffmpeg

# FFmpeg-specific encoding settings
preset: medium # x264 preset: ultrafast, fast, medium, slow
crf: 23 # Quality (0-51, lower = better quality)
audioBitrate: 192k # Audio bitrate

# Subtitle settings (requires TranscriptionProducer in blueprint)
subtitles:
  font: Arial # Font name (system fonts)
  fontSize: 48 # Font size in pixels
  fontBaseColor: '#FFFFFF' # Default text color (hex)
  fontHighlightColor: '#FFD700' # Karaoke highlight color (hex)
  backgroundColor: '#000000' # Background box color (hex)
  backgroundOpacity: 0 # Background opacity (0-1, 0 = no box)
  position: bottom-center # Anchor position
  edgePaddingPercent: 8 # Distance from frame edges (% of height)
  maxWordsPerLine: 4 # Words displayed at once
  highlightEffect: true # Enable karaoke-style highlighting

Requirements:

• Blueprint must include a TimelineComposer producer
• Movie must have a Timeline artifact
• For remotion: Docker Desktop running
• For ffmpeg: FFmpeg installed and in PATH
• For subtitles: Blueprint must include a TranscriptionProducer

Output:

• Video: builds/{movieId}/FinalVideo.mp4 and artifacts/{movieId}/FinalVideo.mp4 (symlink)
• Audio-only (FFmpeg): builds/{movieId}/FinalAudio.mp3 and artifacts/{movieId}/FinalAudio.mp3 (symlink)

Examples:

# Export with defaults (1920x1080 @ 30fps, remotion exporter)
renku export --movie-id=movie-a1b2c3d4

# Export most recent movie
renku export --last

# Export with custom resolution
renku export --last --width=3840 --height=2160 --fps=24

# Use FFmpeg exporter (faster, no Docker required)
renku export --last --exporter=ffmpeg

# Use FFmpeg with custom settings via CLI
renku export --last --exporter=ffmpeg --width=1280 --height=720 --fps=24

# Use config file for advanced settings (subtitles, encoding)
renku export --last --inputs=./export-config.yaml

---

renku export:davinci

Export a generated movie timeline to OpenTimelineIO (OTIO) format for import into DaVinci Resolve, Premiere Pro, and other professional NLE applications.

Usage:

renku export:davinci --movie-id=<id> [options]
renku export:davinci --last [options]

Options:

Option	Default	Description
--movie-id, --id	-	Movie ID to export
--last	-	Export the most recent movie
--fps	30	Frames per second for timeline

Requirements:

• Blueprint must include a TimelineComposer producer
• Movie must have a Timeline artifact

Output:

• builds/{movieId}/DaVinciProject.otio - Main OTIO file
• artifacts/{movieId}/DaVinciProject.otio - Symlink for easy access

Examples:

# Export most recent movie
renku export:davinci --last

# Export specific movie
renku export:davinci --movie-id=movie-a1b2c3d4

# Export with custom frame rate
renku export:davinci --last --fps=24

Importing into DaVinci Resolve:

1. Open DaVinci Resolve, go to the Edit page
2. File → Import → Timeline (or right-click in Media Pool → Timelines → Import → select OTIO)
3. Select the .otio file
4. If media paths don’t match, DaVinci prompts to locate the media folder
5. Check “Ignore file extensions when matching” if relinking to different quality media

Track Mapping:

Renku Track	OTIO Track
VideoTrack	Video
ImageTrack	Video
AudioTrack	Audio
MusicTrack	Audio
CaptionsTrack	Markers

Notes:

• OTIO is a snapshot format - no live sync with Renku
• Re-export generates a new timeline state
• DaVinci will auto-link to existing media in your Media Pool when re-importing
• For iterative workflows, enable “Automatically conform missing clips” in DaVinci Project Settings

---

renku producers:list

List available models for producers in a blueprint.

Usage:

renku producers:list --blueprint=<path>

Options:

Option	Required	Description
--blueprint, --bp	Yes	Path to blueprint YAML file

Output:

• Lists all producers with their available models
• Shows pricing information where available
• Warns about missing API tokens

Example:

renku producers:list --blueprint=./video-only.yaml

Output:

Producer model configurations:

VideoProducer (4 video models)
  Provider    Model                          Price
  replicate   bytedance/seedance-1-pro-fast  480p: $0.015/s
  replicate   google/veo-3.1-fast            $0.10/s
  fal-ai      veo3-1                         -

AudioProducer (2 audio models)
  Provider    Model                 Price
  replicate   minimax/speech-2.6-hd $0.0001/token

⚠️  Missing API tokens:
  - fal-ai: FAL_KEY not set

---

renku blueprints:validate

Validate blueprint structure and references.

This command performs static validation only (wiring/schema/graph). For simulated execution coverage, use renku generate --dry-run.

Usage:

renku blueprints:validate <path-to-blueprint.yaml>

Validates:

• YAML syntax
• Required fields
• Module/producer references
• Connection validity
• Loop definitions

Example:

renku blueprints:validate ./my-blueprint.yaml

---

renku blueprints:dry-run-profile

Generate a reusable dry-run profile file for simulation coverage.

Usage:

renku blueprints:dry-run-profile <path-to-blueprint.yaml> [--output=<path>]

Options:

Option	Required	Description
--output	No	Output profile path (defaults to <blueprint>.dry-run-profile.yaml)

Behavior:

• Analyzes blueprint conditions
• Generates deterministic dry-run simulation cases
• Writes a profile YAML that can be reused with renku generate --dry-run --profile=<path>

Example:

renku blueprints:dry-run-profile ./my-blueprint.yaml
renku generate --inputs=./inputs.yaml --blueprint=./my-blueprint.yaml --dry-run --profile=./my-blueprint.dry-run-profile.yaml

---

Dry-Run Profile File Format

A dry-run profile is a reusable simulation recipe for renku generate --dry-run.

It controls the case matrix used in simulation so you can get deterministic and repeatable coverage checks, especially for condition-driven blueprints.

Why use it:

• Keep dry-run behavior stable across machines and CI runs
• Make condition coverage explicit (instead of relying on implicit auto-generation)
• Review and version-control the simulation plan next to your blueprint

How it is used by generate --dry-run:

1. The CLI loads the profile file (if --dry-run-profile / --profile is provided)
2. It validates that the profile is structurally valid
3. If blueprint is set in the profile, it must match the --blueprint target
4. If inputs is set in the profile, it must match the --inputs target
5. The dry-run executes all profile cases and reports coverage/failures

If you do not provide a profile file, the CLI auto-derives cases in memory from blueprint conditions.

Schema (version 1):

Field	Type	Required	Description
version	number	Yes	Must be 1
blueprint	string	No	Blueprint path for sanity-checking profile usage
inputs	string	No	Inputs path for sanity-checking profile usage
generator	object	No	Metadata (cases, seed) for generated profiles
cases	array	No	Explicit simulation cases (generated profiles include this)

Case object:

Field	Type	Required	Description
id	string	Yes	Case label shown in dry-run summary
conditionHints	object	No	Per-case simulation overrides

conditionHints object:

Field	Type	Required	Description
mode	enum	Yes	One of first-value, alternating, comprehensive
varyingFields	array	Yes	Condition-driven fields to vary

varyingFields[] object:

Field	Type	Required	Description
artifactId	string	Yes	Canonical field artifact ID (for example Artifact:StoryProducer.Storyboard.Scenes[scene].CharacterPresent[character])
values	array	Yes	Candidate values used by simulation
dimension	string	No	Preferred varying dimension when relevant

Example profile:

version: 1
blueprint: ./scene-character-presence.yaml
inputs: ./input-template.yaml
generator:
  cases: 3
  seed: 0
cases:
  - id: case-1
    conditionHints:
      mode: alternating
      varyingFields:
        - artifactId: Artifact:StoryProducer.Storyboard.Scenes[scene].CharacterPresent[character]
          values: [true, false]
          dimension: scene
  - id: case-2
    conditionHints:
      mode: alternating
      varyingFields:
        - artifactId: Artifact:StoryProducer.Storyboard.Scenes[scene].CharacterPresent[character]
          values: [false, true]
          dimension: scene

Recommended workflow:

# 1) Generate a profile next to your blueprint
renku blueprints:dry-run-profile ./my-blueprint.yaml

# 2) Reuse it for deterministic dry-runs
renku generate --inputs=./inputs.yaml --blueprint=./my-blueprint.yaml --dry-run --profile=./my-blueprint.dry-run-profile.yaml

---

renku viewer

Open the blueprint viewer.

Usage:

renku viewer [path/to/blueprint.yaml]

Arguments:

Argument	Required	Description
[path]	No	Path to blueprint YAML file. If not provided, auto-detects in current directory.

Options:

Option	Description
--viewerHost	Override viewer host (optional)
--viewerPort	Override viewer port (optional)

Behavior:

• Auto-detects blueprints in the current directory if no path is provided
• Starts the viewer server in background if not running
• If --viewerHost / --viewerPort are provided, they take precedence and a mismatched running server is not reused
• Opens the blueprint viewer in your browser

Examples:

# Auto-detect blueprint in current directory
renku viewer

# Open a specific blueprint
renku viewer ./my-blueprint.yaml

# Force a specific viewer port
renku viewer --viewerPort=4321

---

renku launch

Open Renku home without requiring a pre-initialized workspace.

Usage:

renku launch

Options:

Option	Description
--viewerHost	Override viewer host (optional)
--viewerPort	Override viewer port (optional)

Behavior:

• Starts the viewer server in background if not running
• Opens the Renku home page (/)
• Shows onboarding automatically when workspace setup is incomplete
• Uses the bundled catalog for onboarding setup

Examples:

# Open Renku home
renku launch

# Open on a specific host/port
renku launch --viewerHost=127.0.0.1 --viewerPort=4321

---

renku viewer:stop

Stop the background viewer server.

Usage:

renku viewer:stop

---

Provider Configuration

Environment Variables

Renku reads credentials from environment variables or .env files:

# OpenAI (required for script generation)
OPENAI_API_KEY=sk-...

# Replicate (required for most media generation)
REPLICATE_API_TOKEN=r8_...

# Optional providers
FAL_KEY=...
ELEVENLABS_API_KEY=...

.env File Locations

The CLI checks for .env files in:

1. Current working directory
2. CLI installation directory
3. ~/.config/renku/.env

Provider-Specific Notes

OpenAI:

• Used for script generation and prompt creation
• Requires gpt-4o or similar model access

Replicate:

• Used for video, audio, and image generation
• Supports many model variants
• Pay-per-use pricing

fal.ai:

• Alternative provider for video/image models
• Some unique model offerings

Renku (built-in):

• OrderedTimeline - Timeline composition
• No API key required

---

Storage Structure

Configuration

Fixed location for CLI configuration:

~/.config/renku/cli-config.json

Contents:

{
  "storage": {
    "root": "/path/to/workspace",
    "basePath": "builds"
  }
}

Workspace Layout

Workspace root (initialized with renku init):

{workspace}/
├── .gitignore               # Auto-generated: ignores **/builds/ and **/artifacts/
└── catalog/
    └── blueprints/
        └── *.yaml           # Blueprint files

Project directory (current working directory when running renku generate):

{project}/
├── builds/                  # GITIGNORED - build data
│   └── movie-{id}/
│       ├── blobs/           # Content-addressed blob storage
│       │   └── {hash-prefix}/
│       ├── events/
│       │   ├── inputs.log   # Input events (JSONL)
│       │   └── artefacts.log # Artifact events (JSONL)
│       ├── manifests/
│       │   └── {revision}.json
│       ├── runs/
│       │   └── {rev}-plan.json
│       └── current.json
└── artifacts/               # GITIGNORED - symlinks to build outputs
    └── movie-{id}/
        └── *.mp3, *.mp4, etc.

Key Concepts:

• Workspace root: Contains catalog/blueprints (tracked in git)
• Project directory: Where you run renku generate - contains builds/ and artifacts/ (gitignored)
• artifacts/: Human-friendly symlinks - presence indicates a completed build (not dry-run)

Movie ID Format

Movie IDs are 8-character prefixes of UUIDs:

• Generated: a1b2c3d4-5678-9abc-def0-123456789abc
• Stored as: movie-a1b2c3d4

---

Troubleshooting

Common Errors

Missing API Credentials:

Error: OPENAI_API_KEY not found

Solution: Export the environment variable or add to .env file.

Invalid Blueprint Path:

Error: Blueprint file not found: /path/to/blueprint.yaml

Solution: Use absolute path or path relative to current directory.

Missing Required Input:

Error: Required input 'InquiryPrompt' not found in inputs.yaml

Solution: Add all required inputs from the blueprint to your inputs file.

Module Reference Error:

Error: Module not found: ./modules/missing-module.yaml

Solution: Check that module paths are relative to the blueprint file location.

Provider Configuration Error:

Error: Invalid sdkMapping for Replicate producer

Solution: Ensure all required fields are mapped in the producer’s sdkMapping.

Debug Mode

Enable verbose logging:

DEBUG=renku:* renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml

Validation Commands

# Validate blueprint structure
renku blueprints:validate ./my-blueprint.yaml

# Check available models and missing tokens
renku producers:list --blueprint=./my-blueprint.yaml

# Test without API calls
renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml --dry-run

# Generate a reusable dry-run profile
renku blueprints:dry-run-profile ./blueprint.yaml

# Dry-run with an explicit profile
renku generate --inputs=./inputs.yaml --blueprint=./blueprint.yaml --dry-run --profile=./blueprint.dry-run-profile.yaml

---

Appendix

Supported File Types

Category	Extensions
Blueprints	.yaml
Inputs	.yaml
Prompts	.md, .txt
Artifacts	.txt, .json, .png, .jpg, .mp3, .wav, .mp4

Default Values

Setting	Default
Config path	~/.config/renku/
Storage base	builds/
Environment	local
Export width	1920
Export height	1080
Export FPS	30