/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
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 20.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)

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 18+**: `node --version`. If missing: "Install from https://nodejs.org/ — needed to render videos"
• **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"

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 (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 compute** on the Starter plan — just requires adding a payment method
• All 7 toolkit tools typically cost $0.50-2.00/month with normal use
• Faster cold starts than RunPod
• Scale to zero — no charges when idle
• Simple deployment: `uv run modal deploy docker/modal-xxx/app.py`

Setup flow:

1. uv sync --extra modal
2. uv run modal setup
   → Opens browser for authentication
   → Creates ~/.modal.toml with credentials
3. Verify: uv run modal app list

Option B: RunPod

Frame honestly:

• Pay-as-you-go, typically $0.44/hr for GPU time
• Each job usually costs $0.01-0.50 depending on the tool
• More GPU variety available
• `--setup` flag automates endpoint creation
• **Availability can be spotty** — GPUs may not be available in some regions

Setup flow:

1. Create account at https://runpod.io/
2. Get API key from https://runpod.io/console/user/settings
3. Add to .env: RUNPOD_API_KEY=your_key_here
4. Each tool has --setup to create its endpoint automatically

Option C: Both

Explain dual-provider benefits:

• Switch between providers with `--cloud modal` or `--cloud runpod`
• If one provider is down, use the other
• Modal for daily use (free tier), RunPod as fallback

Option D: Skip

"No problem — you can still create and render videos with just Node.js. Run /setup anytime to add cloud features later."

---

Phase 3: Cloudflare R2 (File Transfer)

**Only show this phase if user chose a cloud GPU provider.**

Explanation

"When you run a cloud GPU tool (like generating a voiceover or editing an image), the tool needs to send your file to the remote GPU and get the result back. Cloudflare R2 is the bridge.

**R2 is free** — 10GB storage, 10 million operations/month, and zero egress fees. That's more than enough for this toolkit. Without R2, tools fall back to free file hosting services (litterbox, 0x0.st) w