The CLI is the editorbrain program. It can work with local files and talk to the API. The full reference reproduces the help of the reviewed code; use the help of your install to check what is available.
Conventions
--dirselects the portable folder; it does not change the account by itself.- Commands return JSON, except help. Login information can go to stderr.
- In recent versions the JSON is one compact line when the output goes to another program (such as an agent) and is indented in a terminal.
--prettyorEDITORBRAIN_PRETTY=1force indentation; keys stay sorted. - Brand and project IDs are not visible titles. Discover them before you operate.
- An error ends with a non-zero exit code. Do not treat partial stdout as success.
--user-confirmed,--confirmand--share-authorizedrecord real user decisions; they are not options to "make it happen."
Work across several workspaces
From CLI 0.50.0 and a compatible API, a new login allows account consent. Choose the workspace for the job with --workspace ID or EDITORBRAIN_WORKSPACE, without changing a global selection. Folders that already pulled keep their workspace in .editorbrain/.sync.json; use a separate folder for each workspace. resume finds the registered folder first and respects that link. An explicit disagreement fails before it calls the API.
Older credentials do not gain these permissions by editing the configuration: they may need you to sign in again. MCP keeps its own consent; compare workspace_info with status if you use both in one edit.
Prepare a project's destinations
This operation is a candidate for the next version; it is not in CLI 0.53.0. Check editorbrain projects --help. On the compatible version, init, setup and projects create prepare destinations when they create or materialize a local project. For a project whose documents are already in the workspace folder:
editorbrain projects prepare --project my-project --dir ./EditorBrain --dry-run
editorbrain projects prepare --project my-project --dir ./EditorBrain
editorbrain where my-project --dir ./EditorBrain
prepare works offline, with no login and no spend. Repeating it creates only missing destinations and fills missing role links; it keeps files, manual paths, context and checkpoints. --dry-run does not write. It does not move or copy originals, download media or delete files. If a registered location is on a disconnected disk, it is reported without redirecting the work to another folder.
Choose one folder per workspace, open it in Claude Code or Codex and ask it to "prepare my project." Destinations per video are in projects. The root and the registry are private; the MCP map only contains relative paths. Saving a milestone still uses checkpoint and hashes of real files; where locates the links and resume checks the artifacts when you continue. Preparing folders does not create a review and does not change storage preferences.
Task map
| Group | Use |
|---|---|
setup, login, status, doctor | Connection and diagnosis |
init, onboarding, brain, questions, workflow | Context and preferences |
brands, projects, batches, team | Organization and collaboration |
documents, pull, push, resolve, validate, export | Files and portable context |
library, search, narrative, styles | References and editing methods |
motion, media styles, sfx | Visual and sound resources |
resources, assets, storage | Your own material and storage |
studio, integrations, billing | Tools, access and balance |
production, media inventory/sample/preview/search | Local preparation and verification |
memory, learning, feedback, improvements, review | Corrections, learning and links |
skill, update, keys | Installation and maintenance |
Sync without overwriting
editorbrain pull --project my-project --dir ./my-videos --dry-run
editorbrain pull --project my-project --dir ./my-videos
editorbrain push --dir ./my-videos --dry-run
Review the plan before you run push without --dry-run. Conflicts keep both changes; do not resolve them by forcing the last copy. pull --all widens what is downloaded: use it only if you need all of those documents. Media is not synced by these commands.
From CLI 0.45.1, a confirmed type or schema rejection lets the other documents be saved. Read status: "partial", synced: false, uploaded, skipped (path, code, hint and HTTP status), warnings and next. Exit code 2 means action is still required: the skipped documents stay local and unsynced. Update the API according to the hint and retry; saved revisions are not duplicated. Other errors stop the push and keep the confirmed successes. --dry-run checks local validity and conflicts, but it does not probe the server's write compatibility.
Resolve is not render
editorbrain validate --dir ./my-videos
editorbrain resolve my-project --dir ./my-videos
editorbrain export my-project --adapter neutral --dir ./my-videos
validate checks documents; resolve computes effective preferences and hashes; export prepares a handoff for an engine. None of them claims there is a finished video.
Automate
Save the JSON output, check the exit code and use the IDs and revisions it returns. Do not parse messages meant for people. For remote operations, use the same context until the operation finishes and check it again before a new expensive phase.
Do not put the API key in brand files, visible process arguments or repositories. For systems without a browser, login --key-stdin accepts a key supplied by your secret manager. EDITORBRAIN_URL and EDITORBRAIN_API_KEY allow configuration through the environment.
See diagnosis and errors and versions before you automate updates.
Resume a project without depending on the chat
This path requires CLI 0.45.0 or later; remote search and continuity require API 0.45.0 or later. Check availability, editorbrain projects --help and editorbrain resume --help before you update or automate it.
editorbrain projects find "launch" --brand my-brand
editorbrain projects list --brand my-brand --sort recent --limit 20
editorbrain resume my-project --dir ./my-videos
editorbrain checkpoint --project my-project --status in_progress --dir ./my-videos --expected-checkpoint HASH_FROM_RESUME --next "Review captions"
Search compares ID, name and topic. Recent order uses real document and progress activity recorded by the server. For "yesterday," the agent computes the interval in your time zone and sends --since / --before as UTC dates. If there are several candidates, it must resolve the ambiguity. Continue with --after and the returned nextCursor, keeping the filters; deduplicate IDs because the list stays live. Restart without a cursor if you change the query or want a fresh read.
projects find "topic" --local queries, with no network, only the private registry of this computer; it accepts --brand, but not dates or remote pagination. From CLI 0.45.1, --local --dir ./my-videos validates the folder and limits results to that registered canonical root, without exploring or registering projects. It does not walk the whole disk. projects link --project my-project --path ./work --role work --dir ./my-videos registers an existing folder; where my-project checks its locations. Compatible CLI preparations also register technical locations without replacing manual links. The registry ~/.editorbrain/registry.json keeps the folder, workspace and brand identity; it is not synced and it does not let you access the files from another computer.
resume recovers documents and checks files; it presents the saved version, pending items, context changes, reviews and available jobs. It does not start a render, upload or download videos, or spend. --rehash forces the bytes to be read again; by default it can reuse a hash when the file data did not change.
The expected hash avoids overwriting the milestone another agent saved after your read. On a conflict, keep both contributions and read again before you save. Use none as the expected hash only when the read confirmed there is no checkpoint. A checkpoint completed status does not approve the video. Reviews remain the source of approval. Sync the text with the usual push; absolute paths and caches stay private on the device.
From CLI 0.45.1, --primary-artifact work=scene.html and each explicit --dependency role=file also register the file and compute SHA-256 and bytes. With --artifact, its list replaces the base and those references are added; without it, previous artifacts are kept. Omitted references keep their hashes without reading the files again. Absolute paths, symlinks and folders are not accepted as artifacts. If the API returns CHECKPOINT_UNSUPPORTED, update the API and keep the complete v2 checkpoint.
Archiving or losing a conversation does not delete the project's saved documents. Older projects, or ones with a completed milestone, stay readable while you keep their documents and permissions. This release does not add commands to archive or unarchive projects; projects unlink removes only a local link, not files.
Find the right tool
editorbrain help --tasks shows a map by task. For example, editorbrain help sound, editorbrain help review or editorbrain help --tasks captions. They are options; do not run the whole list. Help for an existing command is still available.
To orient a user, the same command accepts a short question:
editorbrain help --tasks "how do I upload a video from my phone"
When it is not a task name, it returns up to three links to guides with video and an explanation. Offer only the one that answers the question; it is not a list of required steps. The query is local, with no login and no spend. If your version does not include those links, use the public index for agents.
editorbrain workflow check --project ID recovers the editorial context and adds nextActions: up to three optional suggestions for that project. Not registering a resource does not prove it was not used. You can use your own tools and adapt or skip techniques when they fit the video, while you respect explicit required rules and current approvals.
--summary asks only for orientation and keeps blocks, policies and review state. To edit, go straight to the compact context; you do not need to ask for a summary first. Reuse documents you already read while their hashes match, and check current comments, pending memory, permissions and approvals before actions that depend on them. With no flags, version 0.52.0 asks for compact (0.51.0 keeps its previous representation): the same contract without duplicates, with a complete editorialSnapshot and context.sameAs indicating which keys to read from the snapshot. --details returns the previous full response. The summary does not replace a snapshot for approving or spending. These additions require a CLI/API version that announces them.
Review, remember and update
- A private sample is prepared and registered with
production submit; see Studio for receipts, variants, comparison and comments. - A real correction is saved with
feedback add --capture-memory. Memory confirmation has another scope and revision; see Memory. updatecoordinates the CLI and existing skills. Installing with npm alone does not update local copies: see updates.
The redesigned Studio, preferences open and the cleanup-after-approval commands are published in 0.52.0. Check your version and install its skills before you use them; these commands do not appear just because the web was updated. Versions.