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, a coding agent, or a workflow run 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, the hash of the tool manifest the build was generated from, and the config file paths.

Most tools take a projectId, many a canvasId, the workflow tools a runId. When a tool takes one 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 the config file. Set the project once and stop repeating it.

Results are JSON on stdout — compact when piped, indented on a terminal. --fields a,b.c keeps only those dotted paths, applied on the server, so a large listing never crosses the wire when three fields are wanted; arrays are traversed element-wise (nodes.id), and martini <tool> --help lists the result fields of tools that declare them, as paths. --out <path> writes the result to a file and prints one summary line; --raw --out <path> writes the media bytes of tools such as view_asset or render_timeline_frame. --quiet prints nothing on success.

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; martini wait prints the same object. 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. 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; push compares each file's server version with the one pulled and answers PROJECT_FILE_CHANGED for a file changed since — pull again, merge, push. --force overwrites.

martini init prints the section that teaches a repository's agents to use the CLI — when to prefer it over MCP tool calls, the commands, the output contract, the exit codes. martini init --write appends it to AGENTS.md (or the path you give) once. 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, a workflow run), 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, when the estimated total is over the cap.

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.

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.