CLI Quick Start

This guide is for CLI users. It covers workspace setup, API keys, and your first generation run.

For installation instructions, see the Install Page.

Setup

Note

If you already completed onboarding through the UI using renku launch, you can skip this setup section and jump to Run Your First Blueprint.

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

Note

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

Configure API Keys

Renku uses multiple AI providers. You’ll need API keys for the providers used by your chosen blueprint.

Providers

Depending on the blueprint and the models you select, you may need keys for the following providers:

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

Set Environment Variables

For CLI and viewer workflows, Renku reads API 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.

Run Your First Blueprint

1. Create a Project from a Blueprint

First go to your workspace that you created earlier:

cd /path/to/your/workspace

Browse available blueprints in the catalog directory:

ls ./catalog/blueprints/

For this tutorial, we’ll use the ken-burns blueprint which generates a video with a Ken Burns effect, audio and background music. Create a new project based on this blueprint:

renku new:blueprint my-first-video --using=ken-burns

This creates a my-first-video/ folder with:

• my-first-video.yaml - Your blueprint file (copied and renamed from the catalog)
• input-template.yaml - Template for inputs configuration
• Any additional files (prompt producers, schemas, etc.)

Note: Always use new:blueprint to create your own copy of a blueprint. Never reference blueprints directly from the catalog - this ensures you can customize them and keeps your projects self-contained.

2. Configure Your Inputs

The input-template.yaml file is already included in your project. Edit it with your desired parameters:

cd my-first-video

Here’s an example configuration which will generate a 20-second video about the Eiffel Tower in a Ghibli style, each segment will have 1 image and there will be 2 segments in total. We are using the Replicate and OpenAI as providers, so you would need to have their API keys set in your environment.

inputs:
  InquiryPrompt: 'Tell me about the history of the Eiffel Tower.'
  Duration: 20
  NumOfSegments: 2
  NumOfImagesPerNarrative: 1
  Style: 'Ghibli'
  Resolution:
    width: 1280
    height: 720
  Audience: 'Adult'
  VoiceId: 'Wise_Woman'
  Emotion: neutral

models:
  - model: gpt-5-mini
    provider: openai
    producerId: ScriptProducer
  - model: gpt-5-mini
    provider: openai
    producerId: ImagePromptProducer
  - model: google/nano-banana
    provider: replicate
    producerId: ImageProducer
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer
  - model: timeline/ordered
    provider: renku
    producerId: TimelineComposer
    config:
      tracks: ['Image', 'Audio']
      masterTracks: ['Audio']
      numTracks: 2
      audioClip:
        artifact: AudioSegments
        volume: 0.9
      imageClip:
        artifact: ImageSegments[Image]

3. Validate with Dry Run

Before using real API credits, validate your setup with a dry run (from within your project directory):

renku generate \
  --inputs=./input-template.yaml \
  --blueprint=./my-first-video.yaml \
  --dry-run

The dry run:

• Validates your blueprint and inputs
• Shows the execution plan
• Creates mock artifacts (no API calls)

4. Run Full Generation

When you’re ready, run the full generation:

renku generate \
  --inputs=./input-template.yaml \
  --blueprint=./my-first-video.yaml

Watch as Renku:

1. Generates a narration script using OpenAI
2. Creates audio for each segment using your chosen voice
3. Saves all artifacts to the build director.

5. View the Results

Open the generated content in the viewer:

renku viewer

This auto-detects your blueprint, starts a local viewer server if needed, and opens your browser to preview the generated content.

Understanding the Output

After generation, your current working directory contains:

{project}/                       # Current working directory
├── builds/                      # GITIGNORED - build data
│   └── movie-{id}/
│       ├── blobs/               # Generated files (audio, images, etc.)
│       ├── manifests/           # Artifact metadata
│       ├── events/              # Execution logs
│       └── runs/                # Execution plans
└── artifacts/                   # GITIGNORED - symlinks to build outputs
    └── movie-{id}/
        ├── Script.txt           # Generated narration script
        ├── Segment_0.mp3        # Audio for segment 0
        ├── Segment_1.mp3        # Audio for segment 1
        └── Segment_2.mp3        # Audio for segment 2

The artifacts/ directory contains human-readable symlinks to your generated content. Use renku list to see all builds in the current project.

Next Steps

You’ve successfully generated your first AI video content with Renku!

Explore More Blueprints

Try other example blueprints by browsing the catalog and creating your own copies:

# See available blueprints
ls ./catalog/blueprints/

# Create a new project from any blueprint
renku new:blueprint my-documentary --using=documentary-talkinghead

Each blueprint you create contains an input-template.yaml that documents the required inputs.

Create a Blueprint from Scratch

You can also create a completely new blueprint without copying from the catalog:

renku new:blueprint my-custom-workflow

This creates a scaffold blueprint with all required sections that you can customize.

Using Claude Code for Blueprint Creation

If you’re using Claude Code or other AI coding agents that support skills, you can install the Renku plugin to get AI-assisted blueprint creation.

Install the Renku plugin:

/install-plugin https://github.com/keremk/renku/tree/main/renku-plugin

Once installed, you can use the create-blueprint skill to have Claude help you design and create blueprints through natural conversation:

/renku-plugin:create-blueprint

The skill guides you through:

• Understanding your video requirements
• Selecting appropriate producers and models
• Creating the blueprint YAML structure
• Setting up prompt producers for AI-driven content
• Validating and testing with dry runs

This is especially useful for complex blueprints with multiple producers and custom prompt logic.

Learn the Workflow

Read the Usage Guide to learn:

• How to edit and iterate on generated content
• Using layer-by-layer generation for cost control
• Browsing available models and producers

Deep Dive

For advanced users:

• CLI Reference - Complete command documentation
• Blueprint Authoring - Create custom workflows

Troubleshooting

Missing API Credentials

Error: OPENAI_API_KEY not found

Solution: Export your API key, or add it to ~/.config/renku/.env (or a project-local .env in your current working directory).

Blueprint Not Found

Error: Blueprint file not found

Solution: Use the full path to the blueprint file. After renku init, blueprints are in {workspace}/catalog/blueprints/.

Provider Rate Limits

The providers have rate limits that may depend on your tier or how much you loaded your account with. Setting —concurrency to a higher value than 1 will likely trigger these limits. Concurrency will allow you to parallelize requests, but if you hit rate limits, try lowering the concurrency or upgrading your plan with the provider.

Dry Run Works, Real Run Fails

Check that:

1. All required API keys are set
2. Check your provider logs to diagnose issues. Sometimes you may be hitting rate limits or safety filters.
3. Your API accounts have sufficient credits
4. The model names in the inputs file are valid and currently available.

Run renku producers:list --blueprint=<path> to see available models and check for missing tokens.