The formats command line

#What it is

formats is the command line every Formats agent uses. Installed in your terminal, it lets you, your scripts and agents outside the app (Claude Code or Codex in a terminal, for example) do the same: work on the project open in Formats, where every edit is one step you can undo, or on a project file with no window open at all.

#Install it

1. 1In the menu bar, choose Formats Studio > Install formats Command Line….
2. 2Confirm Install. Formats links formats into /usr/local/bin when that folder is writable, or else into ~/.local/bin, without asking for a password.
3. 3Open a new terminal window and run formats --version.

Or install it from a terminal: "/Applications/Formats Studio.app/Contents/Resources/agents/cli/formats" --install. Set FORMATS_BIN_DIR first to choose the folder. If the folder is not on your PATH yet, the install says so and gives the line to add.

#First commands

Answers are JSON, and pictures are saved as files whose paths are printed. Exit codes: 0 done, 1 refused or failed, 2 a mistake in the command, 3 no project open, 4 the plan or credits fall short, 75 still waiting (finish with formats wait).

#Work on a project file without the app

Add --project <file> (or set FORMATS_PROJECT) and the command runs on that project file, edited in place, with no window. Formats renders it with the same engine as the editor, so a picture or an export from the command line matches the app's.

• Read it: formats project read --project video.json.
• Look at it: formats look layout --frame 30 --project video.json, or a frame, a filmstrip or single layers.
• Check it: formats verify --project video.json.
• Export it: formats render --file-name cut.mp4 --format mp4 --range @range.json --project video.json, written to exports/ beside the project.
• Also captions, music, placed sound, shaders, code layer inputs and imports of named files.

#Import fonts

Embed a TTF, OTF, WOFF or WOFF2 file so the project's text can use it: formats media fonts --project-files authoring/Brand.otf, attached or with --project. The font is checked as the editor checks it (a damaged file, a collection or a font whose licence forbids embedding is refused) and stored in a fonts folder beside the project, so previews and exports draw it everywhere the project goes. The answer names the family to use as the text's font.

#Faster repeated commands

The first command on a project file starts a render service that keeps the engine ready, so the next looks, checks and exports start in about a second. It runs one command at a time, so several terminals or agents can share it, and quits after 10 minutes with nothing to do.

#Agents, MCP and sandboxes

• An agent with a shell runs formats like you do. Point it at formats docs for the guides.
• A host without a shell can use formats mcp, a server with two tools, search and execute. Add --project <file> to work on a file.
• Codex's sandbox on a Mac lets nothing start a browser or open a socket without network access. Open the project in Formats and run Codex with -c sandbox_workspace_write.network_access=true, or run formats --serve in a terminal outside the sandbox first; commands inside then reach it.
• In a sandbox the home folder may be read-only: formats writes only to the project's folder and the temporary folder.