Ralphy: CLI for agent-made video and content
Ralphy Video CLI
Ralphy gives Claude Code, Cursor and Codex commands for making video: templates, frame generation with a cost preview, mp4 render
- 144 ★ on the repository
- Last commit
Extended access
Why this level
- Generation goes through paid APIs: without `--dry-run` the agent can spend money on your OpenRouter and ElevenLabs keys
- The `curl | sh` installer runs code from the network, so read it before running
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ralphy-video-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Generation goes through paid APIs: without `--dry-run` the agent can spend money on your OpenRouter and ElevenLabs keys
- The `curl | sh` installer runs code from the network, so read it before running
This is third-party code. Review the repository files before installing.
What it does
Ralphy is a desktop app for content work, and the repository also ships a standalone `ralphy` CLI. An agent drives it with commands: `ralphy new` creates a project, `ralphy template suggest` picks a template from a phrase, `ralphy template use` scaffolds it, `ralphy generate image` makes frames, and `ralphy render` assembles the mp4. Models are called through OpenRouter (Kling, Seedance, Veo, Sora, Nano-Banana), and ElevenLabs provides voice and music. The video is composed in HyperFrames, which is HTML with GSAP animation rendered by Puppeteer and FFmpeg. The `--dry-run` flag shows the generation cost before any money is spent. The single entry point is the `ralphy` verb: every model call lands in `generations.jsonl`, every price in the cost summary and every failure in a postmortem. If a scene fails the quality gates, the render refuses to run. After `ralphy setup` a skill is installed into the agent, which then runs the work itself.
Who it is for. Creators of short videos, ads and social content who hand video assembly to a local agent and want to see the price before it runs.
Good fit when
- An agent has to produce a 30-second ad from a short brief
- A video template has to be picked from a phrase like a talking-head rant about deadlines
- A cost estimate is needed before frames are generated so nothing is overspent
- Video assembly should live in git: the HTML composition is versioned and tested in CI
- Generation costs and failures need to go into a log for review
Not a fit when
- You need to edit footage you already shot on a timeline: Ralphy builds videos from generated frames and templates
- You have no OpenRouter or ElevenLabs keys: generation will not work without them
- The video is needed in minutes: a cold start takes about 8 minutes and a batch of 10 takes about 25
- The budget is zero: the README gives about 8 to 12 dollars for a typical 30-second video
Example request
Make a 30-second ad about a spring espresso. First pick a template and show the generation estimate with --dry-run.Limitations
Bun and ffmpeg are required, along with the `OPENROUTER_API_KEY` and `ELEVENLABS_API_KEY` keys. Generation is paid, and the README gives 8 to 12 dollars per 30-second video as a guide. The desktop app builds from source on macOS with Bun 1.4.2 or newer. The standalone CLI installs on macOS, Linux and Windows. Prompts go to third-party services, and every generation lands in the project's `generations.jsonl` log.
The project is young: the README shows version 0.3.0, so the command set may change.
How to disable. Remove the CLI with the same manager you installed it with, for example `npm uninstall -g @alecs5am/ralphy`. Delete the Ralphy skill from the agent's skills folder and remove the keys from your environment.
FAQ
How do I install Ralphy?
Run `npm install -g @alecs5am/ralphy`. Other routes exist: `brew install alecs5am/tap/ralphy` on macOS, the `install.sh` script on Linux and macOS, and `install.ps1` on Windows. All of them install the same binary.
What does ralphy setup do?
An interactive wizard asks for two API keys and installs the skill into the agent. Afterwards `ralphy doctor` checks the environment and shows green marks for bun, ffmpeg and the keys.
How much does a video cost?
The README gives 8 to 12 dollars for 30 seconds. The `--dry-run` flag shows the exact price of a given generation before it runs, so nothing extra is charged.
Which agents work with Ralphy?
The README diagram names Claude Code, Cursor and Codex: they follow playbooks and call the same `ralphy` commands. The `.agents/skills` folder in the repository holds dozens of skills for editing, captions and art direction.
How is Ralphy different from HyperFrames?
HyperFrames is a composition engine built on HTML and GSAP, and Ralphy uses it as one layer. On top come templates, a model router, cost estimates, a generation log and scene quality gates.
Discussion
No questions or reviews yet.
Related
CLI toolsVideo editing for agents: openreelio-cli with JSON output and an MCP server cuts, captions, renders and verifies a clip
Eleven Claude Code skills turn a talking-head clip into reels: titles, graphics behind you and split screen
A Claude Code skill that builds motion graphics in code: 21 ready looks, five questions, three approval stills and an MP4 render.
Skills and CLI from HeyGen: the agent writes HTML compositions and renders them into MP4 videos, captions, motion graphics and decks
A CLI for programmatic video from HTML: the agent assembles frames from templates and renders a finished MP4 on your machine
Skills, a CLI and an MCP server that let Claude Code or Codex make video from a brief: editing, graphics, voiceover, subtitles
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Ralphy: CLI for agent-made video and content (this card) | no | 144 | |
| HyperFrames | no | 83,283 | the HTML composition engine, without templates, estimates or a generation log |
| video-use | no | 30,939 | a skill for editing video from a prompt, without its own CLI or model router |
README in short
The README compares Ralphy with closed cloud services and one-off scripts on seven points: Apache-2.0 licence, any OpenRouter model, a `--dry-run` estimate, reproducibility, render refusal on a bad scene, the `ralphy research` engine and git-based composition. The full command list is in `docs/cli-surface.generated.md`.