BitRaster for Windows installs a console companion, bitraster-cli, beside the app. It inspects, renders and exports project files without opening the editor, and while the editor is running it can drive it: list your documents, add a layer, draw, render, undo and save, each as an ordinary edit you can see and take back. An AI agent gets the same commands as MCP tools. API 1.1.
The installer puts it in the app folder, by default %LOCALAPPDATA%\BitRaster\bitraster-cli.exe, and adds that folder to your PATH, so a terminal opened after installing finds it by name:
bitraster-cli version
bitraster-cli helpTerminals that were already open keep their old PATH until reopened. If the name is not found, an older install or a machine where the installer could not write your PATH, run it once by its full path and it adds itself; path show says where it is and whether it is on PATH, and path remove takes it off. Uninstalling removes the entry. Nothing here needs Node, npm or a copy of the source: the executable carries its own runtime.
"%LOCALAPPDATA%\BitRaster\bitraster-cli.exe" path addEvery command accepts --json, which puts exactly one JSON object on stdout and nothing else, so a script can parse it whole. Without it you get a short human line. Diagnostics always go to stderr. An error is an object with a code from the table below, a sentence, whether repeating the same request could succeed (retryable), and whether the work may have happened anyway (outcome). That last field is the one to read after a lost reply: an outcome of unknown means check the document before sending an edit again.
inspect reads a project and prints its structure: canvas, color mode, layers with their ids, frames, tags, and a snapshot of the file's bytes. render writes one frame as a PNG through the editor's own compositor and lighting; export writes a spritesheet PNG and its Aseprite-format JSON together, or neither. Outputs are never overwritten unless you pass --overwrite, and are written whole or not at all. A build step in a shell:
bitraster-cli inspect hero.brpi --json > hero.inspect.json
bitraster-cli render hero.brpi --frame 0 --scale 4 --output preview.png --overwrite
bitraster-cli export hero.brpi --sheet out/hero.png --data out/hero.json --layout grid --padding 2 --trim --overwritePass the snapshot from inspect back with --snapshot and a frame index is checked against the bytes it came from: if the file changed in between, the command refuses with SNAPSHOT_MISMATCH rather than rendering a different frame under the same number. Older project files mint fresh layer and frame ids every time they are read, which is why file commands address frames by index and snapshot.
Live access is on whenever the desktop app is running. Settings ▸ Automation shows whether the bridge is listening and is the switch that turns it off: the connection closes, its record is removed, and every handle a script was holding stops meaning anything, which is the one-click stop for a script or agent that has run away. Turning it back on starts a new session. Access is local to your user account on that computer; nothing about it leaves the machine. One thing to know: a BitRaster started with “Run as administrator” can be reached only from an administrator prompt, and both the CLI and Settings say so; relaunch it normally. Documents in your BitRaster Cloud account, in a shared room or being broadcast are listed but accept reads only.
bitraster-cli live documents --jsonEach open document has a handle and a revision. The handle dies with the app session, so list again after a restart. Every edit names the revision it expects, and if the document moved on since, because you or another script drew, the edit is refused with REVISION_CONFLICT and nothing is applied: read the document again and decide with fresh eyes. A batch of actions is one undoable step, and a refusal in the middle of it leaves everything as it was.
# actions.json - a night sky and a crescent moon in five actions
[
{ "kind": "layer.create", "ref": "sky", "name": "Sky" },
{ "kind": "fill", "layer": { "created": "sky" }, "frame": { "index": 0 },
"at": { "x": 0, "y": 0 }, "color": { "kind": "rgba", "r": 16, "g": 20, "b": 48 } },
{ "kind": "layer.create", "ref": "moon", "name": "Moon" },
{ "kind": "shape.ellipse", "layer": { "created": "moon" }, "frame": { "index": 0 },
"from": { "x": 5, "y": 6 }, "to": { "x": 25, "y": 26 }, "filled": true,
"color": { "kind": "rgba", "r": 250, "g": 236, "b": 170 } },
{ "kind": "shape.ellipse", "layer": { "created": "moon" }, "frame": { "index": 0 },
"from": { "x": 11, "y": 4 }, "to": { "x": 29, "y": 22 }, "filled": true,
"color": { "kind": "transparent" } }
]
bitraster-cli live create --width 32 --height 32 --name scratch --json
bitraster-cli live apply --document doc:...:doc7 --revision 0 --actions actions.json --json
bitraster-cli live render --document doc:...:doc7 --output check.png
bitraster-cli live undo --document doc:...:doc7 --revision 1 --transaction tx:1
bitraster-cli live save --document doc:...:doc7 --revision 2 --output scratch.brpi
bitraster-cli live close --document doc:...:doc7 --revision 2apply returns the new revision and a transaction id. undo takes back that transaction only while it is still the latest thing that happened to the document; if you drew after it, the undo is refused rather than taking your stroke. Nothing is saved to disk until you say so: save writes the project at the revision you name, with its history and reference image, and marks it clean only if nothing changed while the file was being written. Rendering or exporting never marks a project saved. Points are document pixels from the top left; a stroke clips to the document's selection like a mouse stroke, and borrows nothing from the toolbar.
Every action is one of the editor's own tools or verbs, run the way a hand would run it. A paint color is RGBA in an RGBA document, a palette index in an indexed one, or transparent, which erases. mirror on a paint action runs the editor's symmetry about the canvas centre for that action alone. A layer is named by id, by index, or by the ref a layer.create or layer.group earlier in the same batch gave it; a frame by id or index.
layer.createlayer.setlayer.removelayer.movelayer.grouplayer.ungroupstroke.pencilfillshape.rectshape.ellipseregion.moveregion.copyframe.addframe.removeframe.moveframe.setcel.linkcel.unlinktag.settag.removecanvas.resizepalette.addpalette.setThree of these are applied directly rather than as recorded edits, exactly as the editor's own controls apply them: frame.set, tag.set and tag.remove. A rollback restores them, but the transaction's undo does not, and a watcher does not see them.
On the command line the file commands are inspect, render and export, and the live ones are live documents, live inspect, live open, live create, live apply, live render, live undo, live redo, live save, live close and live export. bitraster-cli help prints every flag.
bitraster-cli mcp serves every command above as a tool over stdio, with input and output schemas the agent can read. File tools work with the editor closed; live tools need it running with Automation on. A render without an output path comes back as an image the agent can look at.
The installer registers it for you with every AI client it finds on the machine: Claude Desktop, Claude Code, Cursor, VS Code and Windsurf. Restart a client that was open during the install, then ask it to drive BitRaster; the tools are already there. For a client installed later, Settings ▸ Automation has a Register button, or run bitraster-cli mcp register; mcp status says who is registered, and uninstalling removes the entries. Only clients that are present are touched, a backup is kept beside each file that is rewritten, and a config that does not parse is left alone and reported. For any other client, point it at the executable by its full path:
{
"mcpServers": {
"bitraster": {
"command": "%LOCALAPPDATA%\\BitRaster\\bitraster-cli.exe",
"args": ["mcp"]
}
}
}Replace %LOCALAPPDATA% with your actual folder if your client does not expand it, for example C:\\Users\\you\\AppData\\Local\\BitRaster\\bitraster-cli.exe. Tools take an optional requestId: an agent that mints one can repeat a call after a lost reply and get the outcome it already had instead of drawing twice. A tool call the editor has accepted is not undone by cancelling it; use live_undo.
The API version is 1.1 and is separate from the app version. Within a major version changes are additive: new commands, new optional fields. A request naming a higher minor than the host serves is refused rather than answered narrowly. The CLI and the app are installed together and refuse to work across versions (VERSION_MISMATCH); update both by updating the app. What this version does not do: headless JPG, BMP or GIF, index-map export, drawing tools other than the pencil, and editing documents that live in an account, a room or a broadcast. Each is a separate piece of work rather than a hidden option.