CLI reference

Everything the oxframe command can do. You will use dev most of the time; the rest are for creating, checking and exporting.

The everyday loop

oxframe init my-video     # once: create a project
cd my-video
oxframe dev               # edit code, watch the preview update
oxframe render            # when you are happy: out/my-video.mp4

Commands

`oxframe init <name>`

Creates a folder with a ready-to-run project: Cargo.toml (SDK version pinned), src/main.rs with one scene, its meta.json, oxframe.toml, .gitignore and instructions for AI coding agents (see Working with AI agents).

--sdk-path <dir> Use a local oxframe-sdk checkout instead of crates.io (also OXFRAME_SDK_PATH).

`oxframe dev`

Builds the project, opens the editor in your browser and rebuilds every time you save. If the code does not compile, the error shows over the preview and the last good build keeps playing.

`--port <n>`	Editor port (default 3000).
`--open` / `--no-open`	Open the browser, or don't (overrides `oxframe.toml`).
`--release`	Optimized build: slower to compile, faster to play heavy scenes.
`--cpu`	Render the preview on the CPU — useful on machines without a working GPU.

`oxframe snapshot --at <seconds>`

Renders single frames as PNG without ffmpeg — handy to check a moment in the animation, to put a still in a README, or for an AI agent to look at its own work.

oxframe snapshot --at 1.5                       # out/snapshots/<project>-1.50.png
oxframe snapshot --at 0 --at 2 --at 4           # three frames
oxframe snapshot --at 1 --out cover.png         # exactly this file
oxframe snapshot --at 0.5 --scene outro         # time from the start of a scene

Each written file is printed on its own line (path frame=N t=T), so scripts can pick them up. Default size is 960×540; change it with --size 1920x1080.

`oxframe render`

Builds in release mode and renders a video. See Rendering video for examples.

`--out <path>`	Output file or folder (default `out/<project>.mp4`).
`--format <f>`	`mp4`, `webm`, `prores` or `png`; by default taken from the `--out` extension.
`--scene <name>`	Only this scene.
`--range a..b`	Only this time range, in seconds; either side can be left out (`2..`).
`--size WxH`	Output size, e.g. `3840x2160`.
`--cpu`	Use the CPU renderer, e.g. in CI without a GPU.
`--no-audio`	Leave the soundtrack out.

`oxframe check`

A quick health check: cargo check, validates every meta.json, compares the versions of the CLI, SDK and editor, and looks for ffmpeg. Run it when something behaves oddly.

`oxframe agents`

Writes or refreshes AGENTS.md, CLAUDE.md and .claude/skills/oxframe/ — run it after upgrading oxframe. Files you edited yourself are left alone unless you pass --force.

`oxframe upgrade`

Moves the project to the SDK version your CLI is made for: updates the oxframe pin in Cargo.toml (keeping your formatting), runs cargo update and refreshes the agent files. If the project already uses a newer SDK, it tells you to update the CLI instead.

Updating

cargo install oxframe-cli --force   # a new CLI
oxframe upgrade                     # then in each project

Projects pin the SDK version, so a release never changes an existing project on its own. Once a day the CLI checks crates.io in the background and mentions a newer version; set OXFRAME_NO_UPDATE_CHECK=1 to turn that off.

oxframe.toml

Project settings for the CLI. Every key is optional.

[dev]
port = 3000
open = true        # open the browser on "oxframe dev"
profile = "dev"    # or "release"

[render]
ffmpeg = "/opt/ffmpeg/bin/ffmpeg"   # default: ffmpeg from PATH

Exit codes

0	Success.
1	Your code does not compile, or the scene fails.
2	Environment: no ffmpeg, port in use, cannot write a file.
3	Version mismatch between the CLI, SDK and editor.

Add -v to any command for detailed logs.

Security

The editor server listens on 127.0.0.1 only, checks the Origin of every WebSocket connection and requires a one-time token. The CLI runs nothing but cargo and your own project.