oxframe

oxframe-cli

Status: oxframe is under very active development. The API is not stable yet and may change from version to version. Pin the exact version in your Cargo.toml and check the changelog before upgrading.

The oxframe command for oxframe projects: create, preview with hot reload, render, check.

cargo install oxframe-cli          # or a prebuilt binary:

Linux, macOS: curl -fsSL https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.sh | sh

Homebrew: brew install oxygenframe/tap/oxframe

Windows: powershell -ExecutionPolicy Bypass -c "irm https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.ps1 | iex"

oxframe init hello && cd hello oxframe dev --open # editor on http://127.0.0.1:3000/?token=… oxframe render # out/hello.mp4 oxframe publish --title "Hello" # upload to oxframe.dev, print a link with a player oxframe check # compile, then storyboard + report.json oxframe inspect --at 2.5 # scene tree at that time, as JSON (--graph adds passes) oxframe snapshot --at 1.5 # one frame as PNG in out/snapshots/ oxframe agents # refresh AGENTS.md and the Claude Code skill oxframe upgrade # move the project to this CLI's SDK version oxframe doctor # Rust, a C linker, ffmpeg: what is missing and how to fix it oxframe transcribe vo/intro.wav # word times of a recorded voice-over (whisper.cpp, local)

Updating

cargo install oxframe-cli --force  # the CLI

oxframe upgrade # then, in each project: SDK pin, Cargo.lock, agent files

Projects pin the SDK (oxframe = "=0.22.0"), so a new release never changes an existing project by itself. Once a day the CLI checks crates.io in the background (cargo search) and mentions a newer version; set OXFRAME_NO_UPDATE_CHECK=1 to turn that off (it is off on CI).

Full reference: https://oxframe.dev/docs/cli.

AI coding agents

oxframe init writes AGENTS.md, CLAUDE.md (@AGENTS.md) and a skill in .claude/skills/oxframe/ (workflow + API cheat sheet). They tell agents to verify visual changes with oxframe check (storyboard and report.json) and never to run oxframe dev. oxframe agents refreshes them after an upgrade; files without the oxframe-agents marker (edited by you) are kept unless --force.

oxframe mcp is an MCP server over stdio with check, inspect, render_graph, render_frame, render, list_components and docs_search:

{ "mcpServers": { "oxframe": { "command": "oxframe", "args": ["mcp"] } } }

• MCP Registry name: mcp-name: io.github.oxygenframe/oxframe

How oxframe dev works

browser ──WS──▶ oxframe dev (127.0.0.1:3000) ──WS──▶ <project> preview --port 0

serves the embedded editor restarted on every change watches src/, assets/, Cargo.toml → cargo build

• Changes (debounced 200 ms) trigger cargo build; the editor shows *Building…*, then either *Reloaded* (it re-seeks to the same frame) or the compiler errors with file and line — while the previous build keeps running.
• The old process gets Shutdown, 2 s grace, then is killed (process tree on Windows). Crashes restart the project up to three times.
• Security: loopback only, Origin check, one-time token in the URL; the CLI runs only cargo and your project and makes no network requests.

Exit codes: 0 ok, 1 build error, 2 environment (ffmpeg, port), 3 version mismatch.

The embedded editor

ui/dist is the editor-ui release pinned in ui.lock, packed into the binary with rust-embed (no network access in build.rs or cargo install).

./scripts/fetch-ui.sh             # download the pinned release

just build-ui ../oxframe-web # or build it from a sibling checkout oxframe dev --ui-dir ../oxframe-web/packages/editor-ui/dist # develop the editor

ui/debug-client/ is a minimal single-file protocol client kept for debugging.

Development

cargo test                                          # unit tests, ui.lock check

cargo test --test e2e -- --ignored --nocapture # init → dev → reload → render (needs ../oxframe-sdk)

Licensed under MIT or Apache-2.0.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.