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 copying the latest bundled catalog files (models, producers, and example blueprints).

Usage:

renku update

Behavior:

• Reads the active workspace from the CLI config
• Copies bundled catalog files (models, producers, example blueprints), overwriting existing ones
• 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 [<inquiry-prompt>] \
  --inputs=<path> \
  --blueprint=<path> \
  [--dry-run] \
  [--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=<id> --inputs=<path> [--up-to-layer=<n>]

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)
--non-interactive	Skip confirmation prompts
--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	Regenerate only a specific artifact and its downstream dependencies (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. Loads existing manifest
2. Detects changed inputs (dirty tracking)
3. Regenerates only affected artifacts
4. Updates the artifacts view

Examples:

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

# New movie with inline prompt
renku generate "Explain black holes" --inputs=./inputs.yaml --blueprint=./audio.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 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="AudioProducer.GeneratedAudio[0]" --inputs=./inputs.yaml

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

Note: When using --artifact-id with zsh, quote the artifact ID to prevent bracket expansion.

---

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)
  bottomMarginPercent: 10        # Position from bottom (% 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 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.

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 viewer:view

Open the viewer for a movie.

Usage:

renku viewer:view --movie-id=<id>
renku viewer:view --last

Options:

Option	Description
--movie-id, --id	Movie ID to view
--last	View the most recent movie
--viewerHost	Override viewer host (optional)
--viewerPort	Override viewer port (optional)

Behavior:

• Starts the viewer server if not running
• Opens the movie page in your browser

Examples:

renku viewer:view --movie-id=movie-a1b2c3d4
renku viewer:view --last

---

renku viewer:start

Start the viewer server in the foreground.

Usage:

renku viewer:start

---

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

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

---

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