Automation response reference

Versioned envelopes

With --json, an ordinary command invocation emits one schema_version 1 document on stdout. Help/version output is Click output, so do not parse those invocations as command envelopes. Prompts and diagnostics use stderr; progress is suppressed. --json can still prompt. The complete unattended script also supplies --yes and explicit nondeterministic choices.

Success has schema_version (integer), ok (true), command (string) and result (object). Failure has schema_version, ok (false), command and error; error contains code (machine-readable string), message (technical text) and details (object). Unknown codes need generic translated feedback in a public interface. Automation branches on code/details and exit status, not message wording. This envelope is independent of SRT/VTT/ASS subtitle serialization.

{
  "schema_version": 1,
  "ok": true,
  "command": "project.bindings",
  "result": {
    "bindings": []
  }
}

{
  "schema_version": 1,
  "ok": false,
  "command": "operation.start",
  "error": {
    "code": "input_required",
    "message": "",
    "details": {}
  }
}

The empty message above intentionally omits technical diagnostic wording; it is a shape example. Successful commands may be cancelled with exit 0 and result.cancelled=true. Error details are command/branch-specific.

Envelope field inventory

Fields are required in their stated success/failure branch. result and error.details are command-specific open objects; error.message is technical diagnostic text. The schema version in both examples is checked against the serializer.

Exit codes

Use the process status for broad handling and the stable error code for scoped recovery. Nonzero does not imply that no operation was committed or no file was written.

Stable error mappings

These machine codes map to the process exits above. Handle unknown codes with a translated generic error; details may retain accepted operation IDs or written partial results.

Command result fields

These inventories are unions of actual result branches, not a list of fields required on every response. Types describe the documented serialized values; dictionaries remain open where source declares Any. The default successful final stage is used for export unless explicit artifact selectors change it.

login

Verify and store an API token for its gateway. Use the hidden prompt or protected environment.

logout

Remove only the locally stored token. Environment authentication remains active; server revocation is separate.

operation.apply

Wait if needed, select saved successful artifacts, and write/register local outputs. Failed inputs are unavailable; partial export needs explicit approval.

operation.start

Preflight synchronized media, prepare selected sources, estimate, confirm charges, commit and supply. Wait or detach after acceptance; export is separate.

operation.supply

Resume eligible awaiting_client/awaiting_retry sources on the existing committed operation. Terminal processing recovery starts a new operation instead.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "preparation_failures[]": [
    "content_id",
    "failure_code",
    "path"
  ]
}

operation.watch

Reattach to canonical operation state with realtime hints and HTTP polling. Ctrl-C detaches without aborting accepted work.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "failures[]": [
    "content_id",
    "media_path",
    "reason"
  ]
}

project.bind

Bind a local file or directory to a matching durable project. Bindings are a disposable cache, not inventory synchronization.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "binding": [
    "api_url",
    "path",
    "path_kind",
    "project_id",
    "project_mode",
    "project_name",
    "user_id"
  ]
}

project.bindings

Read cached associations without backend validation or authentication. Optional PATH filters the local list.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "bindings[]": [
    "api_url",
    "bound_at",
    "path",
    "path_kind",
    "project_id",
    "project_mode",
    "project_name",
    "user_id",
    "validated_at"
  ]
}

project.forget

Remove local associations scoped to gateway/account; accept missing paths and never archive/delete backend projects.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "removed[]": [
    "api_url",
    "project_id",
    "project_name",
    "user_id"
  ]
}

project.sync

Inspect the entire local input and reconcile project inventory. Local scan/probe failures prevent partial submission; stale apply needs a fresh preview.

The following checked inventory lists fields inside object/array branches. It is an inventory, not a response envelope. Array items use []. Cancellation may omit the entire object. Types and meanings follow the field descriptions above; counters use the nested lifecycle schemas.

{
  "binding": [
    "api_url",
    "path",
    "path_kind",
    "project_id",
    "project_mode",
    "project_name",
    "user_id"
  ],
  "confirmed_moves[]": [
    "new_path",
    "old_path"
  ],
  "media": [
    "id",
    "path",
    "status"
  ],
  "media[]": [
    "id",
    "path",
    "status"
  ]
}

status

Verify the effective credential and gateway; environment overrides are not persisted.

Preparation and partial-output branches

Incomplete start/supply uses exit 7, error.code=remote_rejection and error.details with operation_id, preparation_incomplete=true and preparation_failures. Each preparation failure names path, content_id and failure_code; watch failures instead use media_path, content_id and reason. Keep that operation ID and use eligible source preparation recovery.

Watch failures use exit 8 and details.operation_id, status and failures. Partial apply can write successful files and still return exit 8; details.result retains outputs, written_outputs, unchanged_outputs and selected_artifact_ids plus lifecycle fields. Preserve that nested result before reporting failure. Failed source items themselves cannot be exported. --yes --allow-partial explicitly approves this branch; --allow-partial alone does not grant unattended approval.

Terminal failed work requires a new independently estimated operation. Do not replay operation start as a generic response to every nonzero exit.