/setup

description: First-time toolkit setup - cloud GPU, file transfer, voice, and prerequisites

Setup

Interactive setup wizard for new users. Checks prerequisites, guides cloud GPU and storage configuration, deploys AI tools, and verifies everything works. Idempotent — safe to run again to add features or verify configuration.

Key Principles

• **Progressive disclosure** — one phase at a time, explain before asking
• **Cost transparency** — always state what's free and what costs money before any action
• **Idempotent** — check what's already configured, skip completed steps
• **Test after each step** — don't just save keys, verify they work
• **Skippable** — every phase can be skipped, user can return later
• **Claude Code native** — use bash tools to check, configure, and verify. This IS the setup wizard.

Entry Point

On invocation, assess current state and adapt:

Step 1: Detect Current State

1. Check .env exists — if not, create from .env.example
2. Read current .env values (which keys are set vs placeholder)
3. Check prerequisites: node --version, uv --version, ffmpeg -version
   (verify_setup.py also reports optional components: Blender)
4. Check Python deps: uv run python -c "import dotenv; import requests"
5. Check Modal CLI: uv run modal --version (if installed)
6. Check for existing Modal apps: uv run modal app list (if authenticated)
7. Summarize what's ready vs what needs setup

Step 2: Present Current State

Show a clear status overview before asking anything:

Toolkit Setup

Prerequisites:
  [check] Node.js 24.x
  [check] Python 3.12
  [check] FFmpeg 7.1
  [check] Python deps installed (uv)

Cloud GPU:      Not configured
File transfer:  Not configured (using free fallback services)
Voice:          Not configured
ElevenLabs:     Not configured (optional, paid)
3D (Blender):   Not installed (optional)

Let's get you set up! We'll go through each feature one at a time.
You can skip any step and come back later with /setup.

**If everything is already configured**, show status and offer to verify/test:

Toolkit Setup — All Configured

Cloud GPU:      Modal (7 tools deployed)
File transfer:  Cloudflare R2 (bucket: video-toolkit)
Voice:          Qwen3-TTS (speaker: Ryan)
ElevenLabs:     Configured

Everything looks good! Want me to run a quick verification test?

---

Phase 1: Prerequisites

Check and report. Don't install anything automatically — just tell the user what's needed and how to get it.

Required

• **Node.js 22+ (24 LTS recommended)**: `node --version`. If missing: "Install from https://nodejs.org/ — needed to render videos". If it is 18 or 20, it still works, but both are end of life: suggest `nvm install 24 && nvm alias default 24`
• **Claude Code**: Already running if they're seeing this command

Recommended

• **uv**: `uv --version`. If missing: "Install with `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"` (Windows) — manages Python and all toolkit dependencies; needed for AI voiceover, image editing, and all cloud GPU tools"
• **Python deps**: `uv run python -c "import dotenv; import requests"`. If missing: run `uv sync` from the toolkit root (uv installs a compatible Python automatically if needed)
• **FFmpeg**: `ffmpeg -version`. If missing: "Install with `brew install ffmpeg` (macOS) or see https://ffmpeg.org/ — needed for media conversion"

Optional

• **Blender 4.2+**: reported by `verify_setup.py` under "Optional" (or `uv run tools/blender_render.py doctor

--no-bench`). Only `tools/blender_render.py` uses it (3D character shots, reveals and product shots from a shot spec), and it is experimental. If it's found, say so in the status and that `/video` will suggest 3D shots where they fit. If it isn't, show one line ("3D (Blender): not installed, optional") and move on: don't count it as missing, and install nothing. `docs/blender.md` has the install command per platform.

Windows only

**Export `PYTHONIOENCODING=utf-8` before running any deploy command in this wizard.** On Windows, a piped/captured stdout defaults to the `cp1252` codec. Modal's deploy progress output contains box-drawing characters it cannot encode, so `modal deploy` aborts partway through the image build with:

'charmap' codec can't encode characters in position 3-42: character maps to <undefined>

The build itself is fine — only the *printing* fails, which makes this look like a broken deploy or a network problem rather than an encoding one. Every deploy in Phase 4 fails identically without it.

Set it for the shell you run the deploys in:

export PYTHONIOENCODING=utf-8   # Git Bash
$env:PYTHONIOENCODING = 'utf-8' # PowerShell

Offer to make it permanent so the user does not hit this again outside this wizard:

[Environment]::SetEnvironmentVariable('PYTHONIOENCODING','utf-8','User')

See `docs/modal-setup.md` for the rest of the Windows prerequisites (notably the Microsoft Store `python3` stub).

Output

Prerequisites: 4/4 ready

Moving on to cloud GPU setup...

If anything critical is missing, explain what features require it and ask if user wants to continue or fix first.

---

Phase 2: Cloud GPU Provider

This is the biggest unlock. Frame it properly.

Explanation (deliver conversationally, not as a wall of text)

Explain what cloud GPU enables:

• AI voiceovers (Qwen3-TTS) — free, self-hosted text-to-speech
• AI image generation (FLUX.2) — title backgrounds, thumbnails
• AI image editing (Qwen-Edit) — transform photos, add effects
• AI upscaling (RealESRGAN) — enhance image quality
• AI music generation (ACE-Step) — background music, jingles
• Talking heads (SoulX-FlashHead, SadTalker) — animated presenters from a photo
• Watermark removal (ProPainter) — clean up stock footage

Then present the choice:

Option A: Modal (Recommended)

Frame the pitch:

• **$30/month free co