Command-line guide

The Manic CLI follows one short loop: check → preview → export.

manic check story.manic
manic story.manic
manic story.manic --record out

The last command writes out/out.mp4 and timing markers under out/.

Everyday commands

The Workbench UI

manic ui opens the Manic Workbench — a local, browser-based studio for your .manic projects. It’s a friendlier front-end to the same engine you drive from the command line:

• Files — browse, create, rename, duplicate, and delete stories, edited in a Monaco editor with syntax help, live diagnostics, and autosave.
• Preview & render — one-click preview, and MP4 / animated GIF / PNG-frame exports with live progress and a render history under the project’s .manic-output folder.
• AI drafting (optional) — describe a story and get a draft, with diff-before-apply and a built-in manic check. Nothing leaves your machine unless you enable a provider and add your own key.

manic ui                     # open the current folder
manic ui path/to/project     # open a specific project folder

It runs entirely on your machine, on a loopback-only address with a session token, and points the Workbench at this manic binary and its bundled assets automatically — no flags needed. Use Open folder… in the UI to switch projects without restarting.

Requirements. The Workbench is fetched and run with npx, so it needs Node.js 22 or newer (npm and npx come with it); FFmpeg on your PATH is needed for MP4/GIF export. Verify with:

node -v    # v22.x or newer
npm -v
npx -v

If Node is missing or too old, manic ui prints a short install guide for your operating system instead of launching — install Node.js 22+, reopen your terminal, and run it again.

Render one part of a story

Named stages make long explainers fast to review:

manic stages lesson.manic
manic lesson.manic --stage proof
manic lesson.manic --from-stage setup --to-stage result --record review

You can also select a time range:

manic lesson.manic --from 4.0 --to 9.5 --record excerpt

Canvas and quality

manic story.manic --canvas portrait
manic story.manic --record out --fps 30
manic story.manic --record out --scale 1.25

The default studio preset records at 60 FPS. Useful presets are:

• studio — full-quality branded MP4, the default;
• reel — full-quality social/vertical output;
• test — fast 30 FPS verification;
• farm — 30 FPS headless/software-rendering output.

Choose one explicitly:

manic story.manic --record out --preset reel
xvfb-run -a manic story.manic --record out --preset farm

xvfb-run provides a virtual display; it does not change Manic’s FPS.

Account and offline commands

manic login
manic status
manic sync
manic logout

• status shows the authoritative online balance when connected and reachable.
• sync refreshes grants and reconciles completed offline work.
• logout uses browser confirmation before disconnecting the installation.

Preview runs and successful exports are separate allowances. manic check, validation failures, and failed display setup consume neither.

Deterministic variations

Generated scenes use deterministic seeds by default. Reproduce or vary them:

manic story.manic --seed 42
manic story.manic --seed random

Where files and assets live

The standard runtime asset catalogue ships beside the executable. Ordinary installs do not need MANIC_ASSETS_DIR. Set it only when intentionally replacing the entire bundled asset root:

export MANIC_ASSETS_DIR=/absolute/path/to/custom/assets

Now create the first scene: Getting started →