Martini CLI

The martini command reaches the same tools as the MCP connector, with the same names and the same arguments. What differs is the transport: a tool call is one HTTPS request with a key, so a shell script or a coding agent can use Martini without holding an MCP session open, and can pipe results, submit JSON it computed, and block until work settles.

Requires Node.js 20.10 or later; the package has no runtime dependencies. For environments without Node, a single-file Linux binary is attached to each release.martini version prints the version, which tool list commands run with (the one the build carries, or the server's cached one) with both hashes, and the config file paths.

Most tools take a projectId, many a canvasId, the workflow tools a runId. Choose the project once with martini use, by name or id, and stop repeating it:

martini use checks the project with one read and writes .martini/context.json in the working directory; every later command run in that directory tree takes its project and canvas from it. An agent's shell is new on every command, so an exported variable does not last from one step to the next, and a file beside the work does. With one canvas in the project that canvas is chosen; with several, name one with --canvas. The file holds no credential and is ignored under another --api-url; martini use --clear removes it and martini whoami shows what is in effect.

When a tool takes one of the three ids and you did not pass it, the CLI fills it from --project / --canvas / --run, else MARTINI_PROJECT_ID / MARTINI_CANVAS_ID / MARTINI_RUN_ID, else what martini use set, else the config file. A flag or variable that names another project replaces the directory's context whole, so its canvas is never sent with a different project.

Results are JSON on stdout — compact when piped, indented on a terminal; the text commands (guide, init without --write, files cat, --help) print text. Warnings are JSON on stderr and change neither stdout nor the exit code. --quiet prints nothing on success.

--fields a,b.c keeps only those dotted paths; arrays are traversed element-wise (nodes.id), a map keyed by id is stepped into for you (assets.status), and martini <tool> --help lists the result fields of tools that declare them, as paths. A path that matches nothing beside ones that do is named in a warning. When no path matches, a read exits 2 (NO_FIELDS_MATCHED, with the nearest paths the result or the tool's result schema has) so you fix the paths and read again, and a command that wrote something prints its whole result with that warning, so it is never run twice for a typo.

Nothing is shown to an agent until it opens a file, so looking at a result is two steps: save, then open. --out <path> writes the result to a file and prints a one-line JSON receipt. With a media extension (.jpg, .png, .webp) it writes the media bytes of tools such as view_asset or render_timeline_frame, and the receipt carries the tool's metadata; --raw asks for the bytes whatever the file is called. Only the path the flag names is written, and the receipt names it whole, resolved from the working directory. A name whose extension contradicts the bytes (still.png for WebP bytes) would make a reader that trusts the extension refuse the file: from a read, nothing is written and the command exits 2 naming the right extension, since running it again costs nothing; from a tool that already did its work, the file is written as named with an EXTENSION_MISMATCH warning. JSON is never saved under an image name. Printed to stdout, a media block is a stub (mime type, byte size, a hint), never base64.

--out-dir <dir> (read-only tools) writes every media block to its own file, in the order the tool wrote them, and prints { dir, files: [{ path, mimeType, bytes, about }], notes? }. A file is named by the asset the text block beside it names: <i>-<id>.jpg from a batch's Asset <id> (i/n) header, <id>.png from a JSON text block's assetId, else block-<n>; about is that text block parsed — asset id, shot number, duration — so which file is which needs no second call. A batch item that failed writes no file and appears under notes. Without the flag, inspect_video prints its ordered blocks, each asset's text before the contact sheet it describes, a JSON text parsed, the sheets as stubs, and a MEDIA_NOT_PRINTED note on stderr.

Errors are one JSON object on stderr, never mixed into stdout:

code is the tool's own MCP error code (ASSET_NOT_READY, NODE_NOT_FOUND, INSUFFICIENT_CREDITS, …), or USAGE for a flag problem. Branch on code and the exit code; the message may change.

Generation and rendering are asynchronous. --wait blocks until the produced assets (or the render) settle and adds waited to the result — one shape whatever was waited on: { kind, status, assets? | job? | run? | delivery? }, where status is the terminal status and the settled records sit under the key that names them (a settled asset carries its media url); martini wait prints the same object. Exit 0 means what was waited for completed: a shot that settles on failed or cancelled prints the same object and exits 1 (ASSET_FAILED, JOB_FAILED). It is on by default for single-item generation and rendering tools — create_node_and_generate, generate, render_timeline, enhance_draft, upscale_assets, render_blender_take — and off for batch tools, where you fan out and then wait once. --no-wait turns it off. --timeout <seconds> (default MARTINI_WAIT_TIMEOUT_SECONDS when set, else 50) ends a wait with exit 4: the result the command produced is still printed on stdout, with pending (and settled) ids, and the error names the martini wait that resumes it, project included, so it runs as written in a new shell. Size --timeout to what your shell step allows — a video generation takes minutes.

upload is the three-call upload (upload_assets_prepare, the PUT to storage, upload_assets_complete) in one step, from files on disk, so nothing rides through the agent's context as base64. download follows the presigned URL and writes the bytes. probe needs ffprobe on PATH.

Project memory files are the notes and instructions a project keeps for its agents (read_project_file, write_project_file). files pull and files push edit them as a directory, and neither loses an edit silently. push compares each file's server version with the one pulled and answers PROJECT_FILE_CHANGED for a file changed since: the file is listed under skipped and the push exits 1. pull never overwrites a file edited here; when the server's copy changed too it is written to .martini/conflicts/ and the pull exits 1 (PULL_CONFLICT) — merge, delete the copy, push. --force overwrites, in either direction.

martini guide prints the operator rules an MCP agent receives when it connects — orienting on a board, the library, the timeline, generating and reviewing shots, uploads and downloads, support — worded for the CLI, with a topic on working from the shell. martini guide <topic> prints one topic, --list names them with their sizes. The CLI asks the server for its current guide on each run (GET /v1/guide, conditional) and keeps it beside the cached tool list, so a rule changed after your build still reaches the agent; offline it prints the copy the build carries. Every answer carries the hash of the current guide, so a command run with a stale copy prints one GUIDE_CHANGED warning that says to read it again.

martini init --write sets a repository up for agents: a short skill at .agents/skills/martini/SKILL.md (Codex, Cursor, and other agents) and .claude/skills/martini/SKILL.md (Claude Code; one file when one directory links to the other), plus a three-line pointer in AGENTS.md. The skill routes the agent to the CLI and sends it to martini guide and martini <tool> --help for the detail, so a session pays for neither until it needs them. Without --write it prints both and writes nothing; an edited skill file is kept unless --force; --dir names another repository. The same rule reaches agents already connected over MCP: the connector's server instructions state it, and get_board_overview repeats it to callers it recognizes as a terminal or IDE agent.

Every call names the CLI and its version in X-Martini-Client, and the User-Agent carries the host agent it runs inside when the host's environment says (Claude Code, Cursor, Codex, Gemini CLI, opencode, Windsurf), so a call from the CLI under Claude Code is distinguishable from one Claude Code made over MCP. MARTINI_HOST_AGENT names the host explicitly; nothing is guessed. In Martini the call shows up as the CLI in the collaborator strip and in analytics.

Generations cost olives and cannot be undone. An agent should lay out the plan — model, prompts, count, rough cost — and get the user's approval before a batch, exactly as over MCP. The tools that quote first (generate_nodes, upscale_assets, enhance_draft) start nothing until called again with the quote's planHash and an approval; --approve --max-olives <n> does both in one command and refuses, with nothing started and exit 5, when the estimated total is over the cap — the one refusal to take back to the person.

The CLI is a client of two routes any language can call with a Martini API key: GET /v1/tools, the manifest (every tool with its JSON Schema, annotations, and profile; the response ETag is its hash), and POST /v1/tools/{name}, which runs one tool with the JSON body as its arguments and answers the result with the MCP envelope removed. ?select=a,b.c is the server-side projection behind --fields; ?format=raw answers a single media result as its bytes; ?format=blocks answers the tool's content blocks in order (&media=stub for sizes instead of bytes), behind --out-dir and inspect_video.

Errors are { "error": "<copy>", "code": "<STABLE_CODE>", "tool": "<name>" } with the tool's own code where it has one; a name that is not in the manifest answers TOOL_NOT_FOUND. @martini-film/client exposes the pair as martini.tools.list() and martini.tools.call(name, args, { select }); martini-client (Python) as martini.tools.list() and martini.tools.call(name, arguments, select=…). The full /v1 surface is described at api.martini.film/v1/openapi.json.

• A local mirror of a canvas as a file tree (martini mirror pull). Read with get_board_overview and --fields for now.
• Compiled binaries for macOS and Windows. The npm package runs wherever Node.js 20.10 or later does; the single-file binary is Linux x64.
• Streaming progress while waiting. --wait returns once, with the settled result.