# 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.