# Use the CLI

The CLI is the `editorbrain` program. It can work with local files and talk to the API. The [full reference](https://editorbrain.com/en/docs/cli-commands) reproduces the help of the reviewed code; use the help of your install to check what is available.

## Conventions

- `--dir` selects 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. `--pretty` or `EDITORBRAIN_PRETTY=1` force 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`, `--confirm` and `--share-authorized` record 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:

```sh
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](https://editorbrain.com/en/docs/proyectos-equipos#keep-each-video-s-files). 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

```sh
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

```sh
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](https://editorbrain.com/en/docs/errores) and [versions](https://editorbrain.com/en/docs/versiones) 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](https://editorbrain.com/en/docs/versiones), `editorbrain projects --help` and `editorbrain resume --help` before you update or automate it.

```sh
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:

```sh
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](/docs/user-guides.json).

`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](https://editorbrain.com/en/docs/revision) 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](https://editorbrain.com/en/docs/memoria).
- `update` coordinates the CLI and existing skills. Installing with npm alone does not update local copies: see [updates](https://editorbrain.com/en/docs/actualizar).

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](https://editorbrain.com/en/docs/versiones).
