sora-cli

A terminal-first workflow for the Sora 2 video API. sora-cli combines a rich Ink-based TUI for iterative prompting with a one-liner CLI that can render, poll, and download videos straight from your shell.

walkthrough

Features

• Launch the full terminal UI with sora to iterate on prompts, monitor jobs, and download assets.
• Fire-and-forget renders with sora "prompt text" – the command blocks until the video finishes and prints the signed download URL.
• Persist job history locally, auto-download videos/thumbnails/sprite sheets, and open assets from the UI.
• Build animated WebP/APNG references from completed jobs (or upload your own file) to improve continuity, powered by bundled ffmpeg/ffprobe binaries.
• First-run setup flow that stores your OpenAI API key in ~/.config/sora-cli/.env (override with SORA_CLI_CONFIG_DIR).
• JSON output mode and no-download mode for scripting scenarios.

Installation

pnpm install -g @brennanmceachran/sora-cli
# or
npm install -g @brennanmceachran/sora-cli

Note: Sora 2 currently limits renders to 4, 8, or 12 seconds per the public docs. The CLI enforces those values for --seconds.

Quick Start

1. sora login sk-... (or just run sora and paste the key when prompted).
2. sora "A dolly shot of a sunlit forest canopy with drifting pollen"
3. Watch progress update in place; when it finishes you’ll see the local file path and a signed URL.
4. Run sora with no arguments to open the full Ink interface. Arrow keys navigate the job list; press Enter on a job for details, c copies the prompt, f force-refreshes status, and o/t/p open downloaded assets.

CLI Options

sora --model sora-2-pro --seconds 12 --size 1920x1080 "Prompt here"

• --model <name> – sora-2 (default) or sora-2-pro.
• --seconds <4|8|12> – enforce Sora’s current runtime limits.
• --size <WIDTHxHEIGHT> – e.g. 1280x720 or 1920x1080.
• --input-reference <path> – attach a still/animated image (WebP/APNG recommended) to seed the generation.
• --output <file> – override the date-stamped file name.
• --output-dir <dir> – change the directory for downloads (default videos/).
• --poll-interval <ms> – tune the status polling cadence (default 5000ms).
• --json – emit a structured JSON summary instead of human-readable logs.
• --no-download – skip saving the MP4 locally; still prints the signed URL.

Animated References

• In the TUI, move to the new Reference row to toggle between None, Upload file, and Auto from job. Auto builds an animated WebP/APNG from the tail frames of the selected completed job so the next render starts exactly where the last one ended.
• For manual continuity, supply --input-reference ./reference.webp (or .png) when running the CLI. The file is uploaded with your render request and also copied into the job’s output folder for reuse.
• sora-cli bundles ffmpeg and ffprobe, so the auto-builder works out of the box on macOS and Linux without additional setup. Set SORA_CLI_FFMPEG_PATH / SORA_CLI_FFPROBE_PATH if you prefer your own binaries.

Config & Storage

• API key: stored at ~/.config/sora-cli/.env as OPENAI_API_KEY.
• Local jobs DB: data/jobs.json inside your current working directory.
• Downloads: by default videos (plus thumbnail/spritesheet) live under videos/<job-id>/.

Set SORA_CLI_CONFIG_DIR if you want the config in a different location.

Development

pnpm install
pnpm typecheck
pnpm build
pnpm sora --help

• pnpm start launches the TUI (requires a TTY).
• pnpm sora runs the CLI entry point through tsx for local development.
• pnpm build emits ESM bundles + declarations to dist/ (used by the published package).

Pull requests are welcome! See CONTRIBUTING for guidelines.

License

MIT