--json NDJSON Event Schema

bcmr --json emits newline-delimited JSON in the foreground without changing execution mode. Explicit --background --json jobs write the same event stream to a platform data directory; use the submitted event's log field rather than constructing the path. This page is the contract for consumers — CI scripts, agent tools, and dashboards reading bcmr status.

Event types

Every operation-stream line carries a type field. Background submission and the first log line use type="submitted", so consumers can dispatch uniformly.

The current taxonomy:

Foreground non-operation commands (bcmr check --json) emit a single result-shaped object on stdout instead — see the bcmr check section below.

submitted event

Emitted only when copy, move, or remove is invoked with both --background and --json. Foreground --json runs do not emit it.

{"type":"submitted","job_id":"d912cf1b2c4","pid":45766,"log":"/Users/.../jobs/d912cf1b2c4.jsonl"}

The same object is also written to <job_id>.jsonl on disk and printed to stdout when the parent process detaches.

progress events

Rate-limited to at most one event every 200 ms during operations. Very short operations can finish before the first progress event.

{"type":"progress","operation":"Uploading (serve)","bytes_done":1048576,"bytes_total":5242880,"percent":20.0,"speed_bps":4194304,"eta_secs":1,"file":"data.bin","file_size":5242880,"file_progress":1048576,"items_done":0,"items_total":1,"scanning":false}

Notes for consumers:

• For very short transfers, no progress event may fire at all — only submitted (if backgrounded) and the terminal result event. Don't wait for at least one progress before declaring "started".
• speed_bps is bytes per second despite the suffix; the unit is fixed for backwards compatibility.
• Field order is not guaranteed; always parse by name.
• Unknown fields may appear in future versions — ignore them.

result events

Exactly one terminal event per run.

Success:

{"type":"result","status":"success","operation":"Uploading (serve)","bytes_total":5242880,"duration_secs":1.247,"avg_speed_bps":4205937}

Error:

{"type":"result","status":"error","operation":"Uploading (serve)","bytes_total":1048576,"duration_secs":0.521,"error":"connection closed by peer","error_kind":"io_error"}

bcmr check --json

bcmr check runs in the foreground (no background job, no submitted event). It emits a single JSON object — not an NDJSON stream:

{
  "command": "check",
  "status": "success",
  "in_sync": false,
  "added": [{"path":"new.txt","size":42,"src_size":42,"is_dir":false}],
  "modified": [{"path":"changed.bin","src_size":100,"dst_size":100,"is_dir":false}],
  "missing": [{"path":"old.txt","size":10,"dst_size":10,"is_dir":false}],
  "summary": {"added":1,"modified":1,"missing":1,"total_bytes":52}
}

FileDiff entries always carry path (relative) and is_dir. The size fields are situational: src_size for added entries, dst_size for missing entries, both for modified entries when they differ. size is a legacy convenience that mirrors the active size field.

Exit code is 0 when in_sync=true, 1 when not, 2 on error.

bcmr doctor --json

bcmr doctor is foreground and synchronous; under --json it emits a single object on stdout — no NDJSON, no submitted, no progress events:

{
  "bcmr_version": "0.6.0",
  "local": [
    {"status":"ok","label":"config file","detail":"/Users/.../config.toml (valid TOML)"},
    {"status":"warn","label":"jobs dir","detail":"... (62 jobs, 1.4 MiB)","recommend":"consider 'bcmr status --gc' ..."}
  ],
  "hosts": [
    {
      "host": "user@host1",
      "checks": [
        {"status":"ok","label":"ssh","detail":"reachable as user@host1"},
        {"status":"ok","label":"remote bcmr","detail":"/home/u/.cargo/bin/bcmr v0.6.0 (matches local)"}
      ]
    }
  ],
  "ok": true
}

Each Check entry carries:

Exit code is 0 when ok=true, 1 otherwise. Per-host probes run concurrently but the output preserves input order so scripts can index by position.

Error events on a stream

When a background job fails, the log file ends with a single result event whose status="error" and error carries the message. Consumers should treat the absence of a terminal result as "process killed before reporting" and fall back to checking bcmr status <job_id> — the status command reads the on-disk JobInfo and the log tail.

What is not yet specified

• Schema versioning. No version field today. Treat the schema as v0; assume best-effort backwards compat within a minor release.
• phase events. A consumer wanting to know "scan phase finished, transfer phase started" today infers it from scanning: true → false between two progress events. A future explicit {"type":"phase","name":"scan_complete"} would beat the heuristic.
• Dedup / compress counters. dedup_count and compress_ratio are not yet emitted. Treat absent fields as unknown.
• Operation-string enum. operation is freeform today. Don't pattern-match; if you need to know the phase, use scanning or upcoming phase events.

See also

• bcmr status [job_id] — query status and tail logs of a background job.
• The submitted.log path — per-job log file in the platform data directory (auto-cleaned after 7 days).