Output contract¶

The exact shape of what alis writes to stdout and stderr under --json, and the fields of an operation result. For scripts and coding agents that parse the CLI.

Streams¶

Stream	Carries	Format
stdout	Exactly one machine-readable result: the command's result object, the final operation, or an error envelope.	One JSON document.
stderr	Progress while a long-running command waits. Never results.	NDJSON: one small JSON object per line.
exit code	Success or the class of failure.	See Exit codes.

Without --json, stdout is a human summary and stderr carries readable progress.

Invocation rules¶

Run one standalone command. Pass the working directory with the tool's workdir or alis --cwd /absolute/path <command>; no wrappers, chains, pipes or redirects.
Read stdout whole. A success result for a streamed operation is under 1 KB; never tail, grep or 2>/dev/null it.
stdout is the completion signal. There is no final stderr event.
Interrupts (Ctrl-C, SIGTERM) never cancel the server-side operation; re-attach with alis operations wait <name> --json.

Progress events (stderr)¶

One event per new progress line:

JSON

{"elapsed":"1:42","operation":"operations/<id>","progress":"Building image neurons/orders-v1"}

A timeout or interrupt ends the stream with a warning event that names the resume command:

JSON

{"elapsed":"10:00","warning":"…","next":"alis operations wait operations/<id> --json"}

--quiet suppresses progress. --verbose streams full progress snapshots instead of pruned lines.

Operation results (stdout)¶

define, build, deploy, blocks install|upgrade|publish|uninstall, product new and operations wait print the final operation as JSON, also when it failed. Always parse stdout before falling back to stderr.

Common fields¶

Start (--async), wait and describe share these top-level fields:

Field	Type	Meaning
`schemaVersion`	number	`1`.
`name`	string	`operations/<id>`. The handle for `operations wait\|describe\|cancel` and `logs build\|deploy`.
`done`	boolean	Explicit; `false` while running.
`status`	string	`running`, `succeeded` or `failed`.
`version`	string	The service version the operation produced or deployed, when known.
`notes`	string	A one-line summary of what the operation is doing.
`logsUri`	string	Link to the execution log, when available.
`error`	object	Present when the operation failed.

A start result also retains a legacy metadata object; read the common fields at the top level. Absent fields mean zero or empty.

Pruning¶

Streamed results are pruned to what is actionable:

completed build steps and applied Terraform resources are dropped;
failed and running steps, diagnostics, failure (the last 60 errorLines) and define errorDetails (the first 40 lines) remain;
images[] lists each built image by path; a failure appears under images[].progress.failure;
deployments[] lists each environment deployment with name, state, logsUri and progress (for example changeSummary with the Terraform operation and change count); a failure appears under deployments[].progress.failure;
buildLogsUri and logsUri link to the build and deploy execution logs.

--verbose keeps every field, including zero values.

Example: a finished build with deploy¶

JSON

{
  "schemaVersion": 1,
  "name": "operations/<id>",
  "done": true,
  "status": "succeeded",
  "version": "1.24.3",
  "notes": "Deploying infrastructure to 1 environment",
  "buildLogsUri": "https://…",
  "logsUri": "https://…",
  "images": [{"path": "."}, {"path": "worker"}],
  "deployments": [
    {
      "name": "organisations/acme/products/shop/environments/<env-id>/deployments/orders-v1",
      "state": "RUNNING",
      "logsUri": "https://…",
      "progress": {"changeSummary": {"operation": "apply", "change": 5}}
    }
  ]
}

Async start¶

--async returns as soon as the operation exists. next is the exact wait command, including --cwd when one was given:

JSON

{
  "schemaVersion": 1,
  "name": "operations/<id>",
  "done": false,
  "status": "running",
  "next": "alis operations wait operations/<id> --json"
}

Active list rows¶

alis operations list --json returns operations[], each with name, type (define, build, deploy), target (package ID), startedAt and next. With --active, rows that could not be read keep status: "unknown" and carry inspectionError; an unreadable operation is not evidence that it stopped.

Error envelope¶

Pre-flight failures and refusals print one envelope on stdout:

JSON

{"error": {"code": "…", "message": "…", "retry": "…", "retryArgv": ["…"], "retryCwd": "…", "agent": "…", "details": {}}}

Fields and codes: Exit codes.

Creation results¶

Creation commands include identifiers in their result; verify them with exit code 0. An envelope for something that already exists (product_exists, service_exists) carries an agent field describing what to do instead of repeating the mutation.

Dry runs¶

alis define --dry-run --json reports valid, diagnostics[] (severity, file, path, line, column, message) and git (uncommitted files, unpushed commits, the commit a define would use). Offline, only local checks run and the envelope carries them under error.details with compiled: false.

alis run --dry-run --json prints the plan as JSON without starting anything (alis preview --json starts nothing to begin with). alis specialist send-message --dry-run --json prints the prepared envelope and sends nothing.