JSON events
Use generate --json or resume --json to stream newline-delimited JSON on stdout. Each line is a complete object with schema_version: 1 and a type. Human diagnostics remain on stderr.
Event types
| Type | Meaning and fields |
|---|---|
started |
Run identified. Includes job_id, clip_id, clip_url, run_directory, and status. |
progress |
Stage update. Includes stage; cloud updates also include status. |
submitted |
Report handoff succeeded. Includes job and clip IDs, URL, and run directory. |
complete |
Video ready. Includes job and clip IDs, URL, and elapsed_seconds. |
recovery |
A saved run exists after a failure. Includes run_directory. |
error |
Runtime failure. Includes code and message; the process exits nonzero. |
Follow the lifecycle
Share clip_url from started immediately. Retain the absolute run_directory for recovery. Neither started nor submitted means the video is complete.
With --wait, keep reading until complete or failure. Without it, the command exits after local handoff. Resuming an already-submitted run without --wait can exit after started; query jobs --json to follow it.
Progress records are stage updates, not heartbeats. Silence alone does not indicate failure. elapsed_seconds measures the current CLI session, not the entire lifetime of a resumed run.
Errors and compatibility
Runtime failures produce an error record with code command_failed. CLI syntax errors use normal stderr diagnostics instead. Always check the process exit status; a killed process may not emit a final event.
Parse each line independently and tolerate additional fields. Do not parse human stderr text as the structured event stream.
Other JSON commands
account --json and jobs --json return a single JSON response, which may span multiple lines. They are not event streams.
agents --json returns agent_setup_required with supported agents and instructions. With --agent, successful installation returns setup_complete and the installed paths.