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

# The most recent movie
renku generate --last --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

Re-Run From a Specific Layer

If you need to regenerate content from a specific layer onwards (e.g., after changing model settings or fixing an issue), use --re-run-from:

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

This is useful when:

• You want to try a different video model without regenerating scripts
• A later layer failed and you want to retry from that point
• You’ve manually edited artifacts at a specific layer

The --from flag:

• Takes a 0-indexed layer number
• Skips all layers before the specified layer (uses existing artifacts)
• Forces all jobs at the specified layer and above to re-run
• Requires --inputs to be specified (for model selections)

You can combine --from with --up-to-layer to re-run a specific range:

# Re-run only layers 2 and 3
renku generate --last --inputs=./inputs.yaml --from=2 --up-to-layer=3

Surgical Artifact Regeneration

When you need to regenerate just one or a few specific artifacts without affecting siblings, use --artifact-id or the shorter --aid alias.

--artifact-id / --aid requires canonical artifact IDs (Artifact:...).

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

# Regenerate multiple specific segments using --aid alias
renku generate --last --aid="Artifact:AudioProducer.GeneratedAudio[0]" --aid="Artifact:AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

This is different from --from which regenerates all jobs at a layer. With --artifact-id / --aid:

• 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 the command fails fast
• You can combine with --up-to-layer to limit how far downstream propagation goes

When to use each:

Scenario	Use
One segment sounds wrong, others are fine	--artifact-id or --aid
Multiple specific segments need work	--aid=Artifact:X --aid=Artifact:Y
Changed model settings, need to redo a layer	--from
Generated up to layer 1, now want to fix one image	--artifact-id + --up-to-layer
Need to retry all video generation	--from=N where N is the video layer

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 --last --inputs=./inputs.yaml --pin="Artifact:ScriptProducer.NarrationScript[0]"

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

# 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 (--last or --movie-id), not brand new runs
• Pin IDs must be canonical (Artifact:... or Producer:...)
• You cannot pin an artifact and target that same artifact with --artifact-id/--aid in the same command
• 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 --artifact-id, --aid, and --pin.

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

renku generate --last --aid="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 --from for retries - If a later layer fails, use --from=N to retry from that layer without regenerating earlier content
6. Use --aid for surgical fixes - If specific segments need work, regenerate just those artifacts instead of the whole layer (e.g., --aid=Artifact:AudioProducer.GeneratedAudio[0] --aid=Artifact:AudioProducer.GeneratedAudio[2])
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 --last \
  --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 --last --exporter=ffmpeg

# Use Remotion (default, requires Docker)
renku export --last --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 --last --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.