# CLI reference

The `yapwing` command is bundled with the Mac app. Use
**Help → Use with Coding Agents…** to put it on your path. Commands read and
write local project folders through the same core as the app.

`PROJECT` is the absolute path to a saved Yapwing project folder. Inspection
returns its ID and revision. Commands that change a project accept
`--project-id ID`; agents should supply the identity they inspected. Without
it the command inspects first, and a refused inspect fails the command with
inspect's own error code and message.
`yapwing --help` and `yapwing help` print the command list.

## Commands

| Command | Result |
| --- | --- |
| `init PROJECT` | Create a project folder. |
| `inspect PROJECT` | Read the current snapshot and job statuses. |
| `view PROJECT [--outline]` | Print the readable `.yapwing.ts` representation or its outline. |
| `edit PROJECT --file FILE [--ops] [--dry-run] [--operation-id ID]` | Validate or apply a readable edit as one undo step. `--file -` reads standard input. The file is UTF-8 text of at most 8 MiB. |
| `check PROJECT --request FILE` | Validate a JSON command request without committing it. |
| `apply PROJECT --request FILE` | Validate and commit that request atomically. |
| `import PROJECT FILE... --expected-revision N --operation-id ID` | Link recordings and wait for local transcription. |
| `collect PROJECT --expected-revision N --operation-id ID` | Copy and verify assets inside the project, leaving originals intact. |
| `transcribe PROJECT --asset-id ID --expected-revision N` | Retry local transcription for an imported source. |
| `library PROJECT [--query TEXT] [--offset N] [--limit N]` | Read a page of source-library results. |
| `analyze PROJECT --expected-revision N [--asset-id ID] [--no-wait]` | Retry derived source analysis. |
| `link-prepared PROJECT --asset-id ORIGINAL --prepared-asset-id PREPARED --expected-revision N` | Associate a raw source with its prepared video. |
| `export PROJECT --output NEW.mp4 --expected-revision N` | Render the inspected project revision to a new file. |

## Search, preview and MCP

| Command | Result |
| --- | --- |
| `search PROJECT --query TEXT [--limit N] [--shows]` | Find spoken sentences in library videos. `--shows` adds picture matches once the person has downloaded the optional picture model. Read-only. |
| `preview PROJECT [--range s3-s5\|START-END] [--frames N] [--audio] [--expected-revision N] [--project-id ID]` | Render one to eight stills (default four) and an optional audio snippet of the current edit into a new temporary folder. Read-only. |
| `mcp [--project PROJECT \| --socket PATH]` | Serve MCP over standard input and output for the project open in the app; see [Connect over MCP](/docs/agent-requests#connect-over-mcp). `--project` sends calls to the Yapwing that has PROJECT open, and `--socket` to that agent socket. |

## Import placement

Import adds main clips by default. `--index N` selects a main insertion point.
`--library` imports a source without placing it; `--projection equirectangular`
is accepted only with library import. `--overlay-parent ID --at NUM/DEN`
places one child overlay at an exact source time. `--no-wait` requires the
project to be open in the app, which then runs the transcription.

## Requests and replies

Check and apply accept `--request -` for standard input. A request contains
`projectId`, `expectedRevision`, `operationId` and `commands`. The usual limit
is 128 commands and 32 MiB per request. A batch containing only distinct-asset
`relink_asset` commands may reach the project's 10,000-asset limit.

Replies are JSON on standard output: `ok: true` with `value`, or `ok: false`
with an error code and message.

| Exit status | Meaning |
| --- | --- |
| 0 | The command succeeded. |
| 1 | The command failed. The reply names the error. |
| 2 | `import` or `transcribe` kept the media, and a transcription failed. Inspect the statuses before retrying speech. |

| Error | Meaning | Recovery |
| --- | --- | --- |
| `stale_revision` | The project changed after it was inspected. | Inspect again and reconsider the edit. |
| `app_not_open` | An MCP call found Yapwing closed. | Open Yapwing, or use the CLI on the project folder. |
| `project_not_open` | `mcp --project` or `--socket` found nothing listening. | Open the project in Yapwing, then retry. |
| `no_project` | An MCP call found Yapwing with no project open. | Open a project in Yapwing, then retry. |

After an uncertain result from a command that changes the project, send the
same complete request and operation ID, not a new operation. Other failures
carry their own code and a message that says what to change.

## Export

Export never overwrites an existing destination. If it is interrupted, inspect
the destination and choose a fresh output name before retrying. A CLI export
uses the free first export or the subscription, as an export from the app
does.

Export levels the sound to −14 LUFS and
writes progress to standard error as JSON lines:

- `{"fraction":0.42,"stage":"render","type":"progress"}` for a closed project.
  The stages are `loudness`, then `render`. A line appears when a stage starts,
  then at most every half second after an advance of at least 1 %. The last
  line is render 1.0.
- `{"stage":"waiting","type":"progress"}` every two seconds while the open app
  renders.

Standard output stays the one JSON reply; parse it alone. See
[Import, collect, export](/docs/agent-requests#import-collect-export).

The [project and command format](/docs/project-format) defines all editing
commands, time units, validation and structured failures.
[Agent requests and recovery](/docs/agent-requests) supplies complete command examples.