CLI automation contract

--json
--yes
schema_version: 1

--jsonEmit exactly one schema-version-1 envelope on stdout.

--yesUse deterministic defaults and approve charges, reviewed syncs, replacements, and overwrites. Missing choices fail with input_required.

stdout and stderrMachine results go to stdout. Diagnostics and progress go to stderr.

CredentialsTokens are never returned in JSON and should be supplied through protected environment variables.

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

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

Reference

Automation status at a glance

Exit 0successThe command completed successfully or an interactive choice was cancelled before work.

Exit 4input_requiredRequired input was unavailable in noninteractive execution.

Exit 8operation_failedThe operation reached a failed or aborted terminal state.

Reference

Stable exit and error codes

Use the process exit status for broad handling and the JSON error code for specific recovery.

Exit	Stable code	Meaning
`0`	`success`	The command completed successfully or an interactive choice was cancelled before work.
`1`	`internal_failure / command_failed`	An unexpected failure or a command-level failure occurred.
`2`	`invalid_usage`	Arguments or command usage are invalid.
`3`	`authentication_failed`	Authentication is missing, expired, or rejected.
`4`	`input_required`	Required input was unavailable in noninteractive execution.
`5`	`local_failure`	A local file, tool, configuration, or filesystem action failed.
`6`	`gateway_failure`	The gateway could not be reached or returned an invalid response.
`7`	`remote_rejection`	The remote service rejected a valid request.
`8`	`operation_failed`	The operation reached a failed or aborted terminal state.
`130`	`interrupted`	The process was interrupted; accepted server work is not automatically aborted.

Command results

Fields returned by each command

Fields are additive within schema version 1. Consumers should ignore fields they do not recognize.

Command	Result fields	Notes
`login / status`	`api_url, user_id, credential_source`	Authentication metadata without exposing the token.
`logout`	`api_url, stored_token_removed, environment_authentication_active`	Reports stored-token removal and remaining environment authentication.
`project.bind`	`binding \| cancelled, path`	Returns the binding or a user-cancelled result.
`project.forget`	`path, removed[], cancelled`	Identifies removed bindings and cancellation.
`project.bindings`	`bindings[]`	Returns all matching local bindings.
`project.sync`	`binding, mode, path, preview, applied, summary, media[], cancelled`	Includes preview/apply mode, summary, media changes, and cancellation.
`operation.start`	`cancelled, path, project_id, operation_id, status, lifecycle_status, detached, output_target, remove_track, sources_accepted, required_credits, available_credits, outputs[], applied_tracks, skipped_tracks, removed_tracks`	Identifies the operation and whether execution detached.
`operation.watch`	`operation_id, project_id, status, lifecycle_status, progress_status, failures[], local_output_pending`	Reports lifecycle/progress state, failures, and pending local output.
`operation.apply`	`cancelled, path, operation_id, project_id, status, output_target, remove_track, partial, outputs[], applied_tracks, skipped_tracks, removed_tracks`	Reports written outputs, track actions, and partial-result state.

Deterministic input

--json may still prompt on stderr. Add --yes to disable prompts, then supply every nondeterministic choice through flags, configuration, or protected environment variables.

subft --json --yes operation start PATH --lang de --project-id PROJECT_ID --detach

Cancellation and partial results

Interactive cancellation exits 0 with cancelled: true before work is committed. Ctrl-C exits 130 without aborting accepted server work. With --yes, incomplete output requires --allow-partial and the command still exits nonzero after applying available tracks.

subft --json --yes operation apply OPERATION_ID PATH --allow-partial