Usage Guide

This guide covers the day-to-day workflows for using Renku: specifying inputs, discovering blueprints and models, testing with dry runs, generating content, and iterating on your creations.

Setup (CLI Alternative to UI Onboarding)

If you use the UI onboarding flow via renku launch, these setup steps are already handled. This section is for users who prefer configuring the CLI workspace manually.

Create a Workspace

Initialize a new Renku workspace:

renku init --root=/path/to/your/workspace

For example:

renku init --root=~/my-creations

This creates:

• ~/.config/renku/cli-config.json - Configuration file
• {workspace}/.gitignore - Ignores **/builds/ and **/artifacts/
• {workspace}/catalog/ containing:
  • models/ - Supported model configurations
  • producers/ - Supported producer definitions
  • blueprints/ - Example blueprints to get started

Configure API Keys

Renku uses multiple AI providers. Depending on the blueprint and model selections, you may need keys for:

Provider	What it does	Key name
fal.ai	Audio, Image, Video generation	FAL_KEY
Replicate	Audio, Image, Video generation	REPLICATE_API_TOKEN
ElevenLabs	AI voice and audio generation	ELEVENLABS_API_KEY
OpenAI	LLM models for story board and prompt generation	OPENAI_API_KEY
Vercel AI Gateway	Unified gateway to Claude, Gemini, and open-source models	AI_GATEWAY_API_KEY

For CLI and viewer workflows, Renku reads keys from ~/.config/renku/.env.

Create or edit this file and add your keys:

REPLICATE_API_TOKEN=your-replicate-api-token-here
FAL_KEY=your-fal-api-key-here
OPENAI_API_KEY=your-openai-api-key-here

You can also provide keys through exported shell variables or a project-local .env in your current working directory.

Specifying Inputs

Every blueprint requires an inputs file that provides the configuration for your video generation.

Input File Format

Inputs are specified in YAML with two main sections:

inputs:
  InquiryPrompt: 'Your topic or prompt here'
  Duration: 60
  NumOfSegments: 3
  # ... other blueprint-specific inputs

models:
  # Optional: override default model selections
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer

Input Types

Type	YAML Syntax	Example
string	Quoted or unquoted text	"Hello world" or Hello world
int	Number without quotes	42
array	YAML list	["item1", "item2"]

Using Input Templates

Every blueprint includes an input-template.yaml with all available inputs and their defaults:

# Copy the template
cp {blueprint-dir}/input-template.yaml ./my-inputs.yaml

# Edit with your values
nano ./my-inputs.yaml

Model Selection

Select which AI model to use for each producer:

models:
  # Use a specific video model
  - model: google/veo-3.1-fast
    provider: replicate
    producerId: VideoProducer

  # Use a specific voice model with custom config
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer

  # LLM producer with structured output
  - model: gpt-5-mini
    provider: openai
    producerId: ScriptProducer

The config field allows you to pass provider-specific configuration options.

Note: Input-to-provider field mappings (transforms) are defined in the producer YAML files, not in the input template. This keeps the input file simple - you only need to specify what model to use, not how inputs map to provider fields.

Discovering Content

Browsing Blueprints

Browse available blueprints in your workspace catalog:

ls ./catalog/blueprints/

Each blueprint directory contains:

• The blueprint YAML file with the workflow definition
• An input-template.yaml documenting required inputs and their types

Browsing Models

See available models for a blueprint’s producers:

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
  replicate   elevenlabs/v3         $0.0001/token

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

Testing with Dry Run

Before spending API credits, validate your configuration with a dry run:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --dry-run

What Dry Run Does

• Validates blueprint YAML structure
• Checks all required inputs are provided
• Verifies producer paths exist
• Creates the execution plan
• Generates placeholder artifacts

What Dry Run Doesn’t Do

• Call any AI provider APIs
• Consume API credits
• Generate real content

Inspecting the Plan

After a dry run, examine the execution plan:

cat {workspace}/builds/movie-{id}/runs/rev-0001-plan.json

The plan shows:

• Execution layers (parallel groups)
• Jobs in each layer
• Input/output connections
• Canonical IDs for all nodes

Running Generation

Full Generation

Run the complete workflow:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml

Renku will:

1. Create a new movie directory
2. Execute producers layer by layer
3. Store artifacts in the blob store
4. Create symlinks in artifacts/
5. Log all events for future reference

Continue an Existing Movie

Resume or regenerate an existing movie:

# By movie ID
renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml

# Another existing movie
renku generate --movie-id=movie-q123456 --inputs=./inputs.yaml

Note: The --inputs flag is always required, even when continuing an existing movie. This ensures model selections are available for any jobs that need to run.

Non-Interactive Mode

Skip confirmation prompts for automation:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --non-interactive

Finding Your Outputs

Generated content is in two locations within your current working directory:

Build directory (builds/movie-{id}/):

• blobs/ - Raw generated files
• manifests/ - Artifact metadata
• events/ - Execution logs

Artifacts view (artifacts/movie-{id}/):

• Human-readable filenames
• Symlinks to blob storage
• Easy to browse and share

Use renku list to see all builds in the current project.

Editing Workflow

Renku’s incremental build system makes iteration efficient.

Changing Inputs

1. Edit your inputs file
2. Re-run generation on the same movie:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./my-inputs.yaml

Renku detects which inputs changed and only regenerates affected artifacts.

Editing Generated Prompts

You can manually edit generated text artifacts:

1. Find the artifact in artifacts/movie-{id}/
2. Edit the file directly (it’s a symlink to the blob)
3. Re-run generation:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml

Renku will:

• Detect your manual edits
• Keep your changes
• Only regenerate downstream artifacts that depend on the edited file

Replacing Artifacts

If an AI-generated image or video isn’t satisfactory:

1. Replace the file in artifacts/movie-{id}/
2. Re-run generation

Your replacement will be used for downstream processing (like timeline composition).

Layer-by-Layer Generation

For cost control and quality review, generate content in stages.

What Are Layers?

Renku groups independent jobs into execution layers:

• Layer 0: Script generation (depends only on inputs)
• Layer 1: Prompt generation, audio synthesis (depends on script)
• Layer 2: Video/image generation (depends on prompts)
• Layer 3: Timeline composition (depends on all media)

Generate Up to a Specific Layer

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --up-to-layer=1

This stops after layer 1, so you can:

• Review the generated script
• Check audio quality
• Make edits before generating expensive video content

Continue to Next Layers

After reviewing, continue generation:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml --up-to-layer=2

Targeted Regeneration

When you need precise control, use --regen to explicitly target artifacts or producer families.

--regen requires canonical IDs:

• Artifact:... targets one concrete artifact lineage
• Producer:... targets one producer family lineage

# Regenerate only segment 2's audio (not segments 0, 1, 3, 4)
renku generate --movie-id=<id> --regen="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

# Regenerate multiple specific segments
renku generate --movie-id=<id> --regen="Artifact:AudioProducer.GeneratedAudio[0]" --regen="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

# Regenerate all selected jobs in a producer family and required dependencies
renku generate --movie-id=<id> --regen="Producer:AudioProducer" --inputs=./inputs.yaml

With --regen:

• Only the specified artifact(s) and their downstream dependencies are regenerated
• Sibling artifacts in the same layer are untouched
• Can be specified multiple times to target multiple artifacts
• IDs must be canonical (Artifact:... or Producer:...) or the command fails fast
• You can combine with --up-to-layer to limit how far downstream propagation goes

Producer Scope Overrides (--pid)

Use --pid when you want to scope planning by producer family with an explicit first-dimension count.

# Keep only first segment for AudioProducer family
renku generate --movie-id=<id> --pid="Producer:AudioProducer:1" --inputs=./inputs.yaml

Important details:

• Format is Producer:Alias:<count> (count is required)
• Scope always includes required upstream dependencies automatically
• --up-to-layer remains active when --pid is present (both constraints apply)
• Directives outside active layer scope are ignored with planning warnings

Pinning Existing Outputs

Use --pin to keep specific existing outputs and skip regenerating jobs whose outputs are fully pinned.

Pin IDs are canonical IDs and can be either:

• Artifact:... to pin one concrete output
• Producer:... to pin all reusable outputs from that producer

# Pin one artifact
renku generate --movie-id=<id> --inputs=./inputs.yaml --pin="Artifact:ScriptProducer.NarrationScript[0]"

# Pin all reusable outputs from a producer
renku generate --movie-id=<id> --inputs=./inputs.yaml --pin="Producer:ScriptProducer"

# Mix artifact and producer pins (repeat --pin)
renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml \
  --pin="Artifact:AudioProducer.GeneratedAudio[0]" \
  --pin="Producer:ImageProducer"

Pinning rules:

• Pinning is for existing movies (--movie-id/--id), not brand new runs
• Pin IDs must be canonical (Artifact:... or Producer:...)
• If the same target appears in both --pin and --regen, the command fails with a conflict error
• Pinned outputs must already exist as reusable successful outputs

Finding artifact IDs:

# List all artifact IDs in a movie
cat builds/movie-{id}/manifests/rev-XXXX.json | jq '.artefacts | keys'

The keys in .artefacts are canonical artifact IDs. Use those values directly with --regen and --pin.

Note: Quote the artifact ID when using zsh to prevent bracket expansion:

renku generate --movie-id=<id> --regen="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

Cost-Saving Strategies

1. Review scripts first - Script generation is cheap; video generation is expensive
2. Use layer limits - Generate expensive content only when you’re happy with cheaper precursors
3. Iterate on prompts - Edit video prompts before generating videos
4. Leverage caching - Re-running generation only rebuilds changed artifacts
5. Use --regen for surgical fixes - If specific segments need work, regenerate just those artifacts instead of broad reruns (e.g., --regen=Artifact:AudioProducer.GeneratedAudio[0] --regen=Artifact:AudioProducer.GeneratedAudio[2])
6. Use --pid for producer-level scope - Limit specific producer families while preserving dependency correctness
7. Use --pin to preserve good outputs - Keep known-good artifacts/producers and only regenerate what still needs work

Viewing Content

Open in Viewer

Open the blueprint viewer:

# Auto-detect blueprint in current directory
renku viewer

# Open a specific blueprint
renku viewer ./path/to/blueprint.yaml

This starts the viewer server in the background if not already running, and opens the blueprint viewer in your browser where you can see the workflow graph, browse builds, and preview timelines.

Stop the Viewer Server

Stop the background viewer server when done:

renku viewer:stop

Exporting Video

Export the final video as MP4:

renku export --movie-id=movie-a1b2c3d4

With custom settings:

renku export --movie-id=<id> \
  --width=1920 \
  --height=1080 \
  --fps=30

Choosing an Exporter

Renku supports two exporter backends:

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

Use the --exporter flag to choose:

# Use FFmpeg (faster, no Docker required)
renku export --movie-id=<id> --exporter=ffmpeg

# Use Remotion (default, requires Docker)
renku export --movie-id=<id> --exporter=remotion

FFmpeg exporter advantages:

• No Docker installation required
• Faster rendering for simple timelines
• Produces MP3 for audio-only timelines
• Supports karaoke-style subtitles

Remotion exporter advantages:

• More advanced video effects
• Better suited for complex compositions

Advanced Export Configuration

For fine-grained control over export settings, use a YAML config file:

renku export --movie-id=<id> --inputs=./export-config.yaml

Example config file with all available options:

# Video settings
width: 1920
height: 1080
fps: 30
exporter: ffmpeg

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

# Karaoke-style subtitles (requires TranscriptionProducer)
subtitles:
  font: Arial
  fontSize: 48
  fontBaseColor: '#FFFFFF'
  fontHighlightColor: '#FFD700'
  backgroundColor: '#000000'
  backgroundOpacity: 0.5
  position: bottom-center
  edgePaddingPercent: 8
  maxWordsPerLine: 4
  highlightEffect: true

Subtitles

If your blueprint includes a TranscriptionProducer, the FFmpeg exporter can add karaoke-style subtitles that highlight words as they’re spoken:

1. Ensure your blueprint has a TranscriptionProducer that generates word-level timestamps
2. Create an export config with subtitle settings
3. Run export with the config file

The exported video is saved to:

• builds/movie-{id}/FinalVideo.mp4
• artifacts/movie-{id}/FinalVideo.mp4 (symlink)

Cleaning Up

List builds in the current project:

renku list

This shows which builds have artifacts (completed runs) vs. dry-run only builds.

Remove dry-run builds (safe default):

renku clean

Remove a specific movie:

renku clean --movie-id=movie-a1b2c3d4

Remove all builds including completed ones:

renku clean --all

Tips and Best Practices

Start Small

For new blueprints, start with:

• Fewer segments (2-3 instead of 10)
• Dry run first
• Layer-by-layer generation

Review at Each Stage

Don’t generate everything at once:

1. Generate script → Review
2. Generate prompts → Review and edit
3. Generate media → Review
4. Compose timeline → Export

Use Version Control

Keep your inputs files in version control:

• Track changes to prompts and settings
• Reproduce past generations
• Share configurations with team members

Monitor Costs

Check provider dashboards regularly:

• Video generation is most expensive
• Audio generation is moderate
• Script generation is cheap

Use renku producers:list to see pricing information.