/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, python3 --version, ffmpeg -version
4. Check pip packages: python3 -c "import dotenv; import requests"
5. Check Modal CLI: modal --version (if installed)
6. Check for existing Modal apps: 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] pip packages installed

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

• **Python 3.9+**: `python3 --version`. If missing: "Install from https://python.org/ — needed for AI voiceover, image editing, and all cloud GPU tools"
• **pip packages**: `python3 -c "import dotenv; import requests"`. If missing: guide through `pip install -r tools/requirements.txt` (or venv setup)
• **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: `modal deploy docker/modal-xxx/app.py`

Setup flow:

1. pip install modal
2. python3 -m modal setup
   → Opens browser for authentication
   → Creates ~/.modal.toml with credentials
3. Verify: 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) which are slower and less reliable."

Setup Flow

Guide the user step by step. They'll need to do some of this in their browser:

1. Go to https://dash.cloudflare.com/
   → Create a free account if you don