# The formats command line

> Install formats in your terminal, work on the open project or on a project file without the app's window, import fonts, and run it from agents and sandboxes.

Formats Studio docs · Agents · https://formats.app/docs/command-line · Updated 2026-10-21

## 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. In the menu bar, choose **Formats Studio** > **Install formats Command Line…**.
2. Confirm **Install**. Formats links `formats` into `/usr/local/bin` when that folder is writable, or else into `~/.local/bin`, without asking for a password.
3. Open 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.

> **Tip:** The link points into the app, so updates of Formats update `formats` too. To remove it, choose **Uninstall formats Command Line…** in the same menu, or run `formats --uninstall`.

## First commands

| Command | What it does |
| --- | --- |
| `formats search trim clip` | Finds the commands that do something, with their flags |
| `formats help`, `formats clip --help` | Lists the command groups, or every command in one |
| `formats docs` | The guides your agent reads, one topic at a time |
| `formats project read` | Reads the project open in Formats |
| `formats --version` | The app's version and its command catalog's |

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.

> **Note:** Edits that need the editor itself, such as trimming clips or arranging tracks, say so: open the project in Formats and run them without `--project`. Work on a project open in Formats that way too: the app saves over changes made to its file from outside.

## 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.

| Setting | What it does |
| --- | --- |
| `FORMATS_PROJECT` | The project file to work on, as `--project` names it |
| `FORMATS_BIN_DIR` | Where `formats --install` puts the link |
| `FORMATS_RENDER_SERVICE=off` | Runs each command on its own, without the render service |
| `FORMATS_RENDER_SERVICE_IDLE` | Seconds the render service waits before it quits (600) |
| `FORMATS_RUNTIME_DIR` | The folder for the render service's socket and files, instead of the temporary folder |

## Related

- [Work with your agent](https://formats.app/docs/agent): Choose Claude Code, Codex or GitHub Copilot, ask for edits in plain words, and review, apply or undo what it does.
- [Skills](https://formats.app/docs/skills): The three skills that come with Formats, starting a request from the library, and using your own skills.
- [Export](https://formats.app/docs/export): Render video or audio on your Mac, choose the format and sequence, and clear any blocking checks.