StoryForge

Local bridge for the Forge video production web app.

Zero runtime dependencies. Single-file bundled output, no transitive installs.

Quick start

cd your-video-project
npx storyforge

That's it. storyforge auto-detects the folder, links it to a project in your dashboard, starts a local server, and opens your browser.

What it does

1. Auto-detects the current folder as a project (name from folder name)
2. Links to an existing project in the dashboard, or creates a new one
3. Saves forge.json in the folder so next time it's instant
4. Starts a local HTTP server at http://localhost:4444
5. Opens https://forge.algo-thinker.com/forge/p/{id}/assets in your browser

The web UI then reads local files directly from your disk — no upload/download cycle needed for audio, images, or rendered clips.

Folder structure

StoryForge expects any of these subfolders (all optional):

your-project/
├── audio/                    # Narration audio files
├── images-horizontal/        # 16:9 images  
├── images-vertical/          # 9:16 images
├── clips/                    # Rendered video clips
├── scripts/                  # Narration text files
├── gemini-prompts/           # AI image prompts
├── word-timings/             # Word-level timestamp JSON
└── brand/                    # Brand assets (logos, intros, etc.)

Installation

# One-time use (recommended)
npx storyforge

# Global install
npm install -g storyforge
storyforge

Commands

storyforge                    Start dev server + open browser (default)
storyforge login              Log in to the Forge API
storyforge --help             Show help
storyforge --version          Show version

Options

--port <port>     HTTP server port (default: 4444)
--dir <dir>       Project directory (default: current)
--no-open         Do not open browser automatically

Security

• Zero runtime dependencies — the entire CLI is one bundled 14KB file
• No telemetry — makes outbound calls only to the Forge API you configure
• Local-first — your files never leave your disk unless you explicitly push them

License

MIT