Skip to content
Yapwing

CLI reference

Markdown · Agent index

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

Section titled “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

Section titled “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. --project sends calls to the Yapwing that has PROJECT open, and --socket to that agent socket.

Import placement

Section titled “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

Section titled “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

Section titled “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.

The project and command format defines all editing commands, time units, validation and structured failures. Agent requests and recovery supplies complete command examples.