Skip to content

Operations and output

The machine-readable contract of the CLI's long-running commands: what stdout and stderr carry, the fields of an operation, error envelopes and exit codes.

Streams

Stream Content
stdout Exactly one result. For alis define, alis build, alis deploy, alis blocks install|upgrade and alis operations wait it is the final operation as JSON under --json, even when the operation failed. Without --json, a human summary.
stderr Progress. Under --json, one NDJSON event per new progress line; no final event. The completion signal is stdout.
exit code Non-zero on failure.

Under --json a streamed result is pruned to what is actionable: an absent field means zero or empty; completed build steps and Terraform resources are dropped; failed and running steps, diagnostics, failure (the last 60 errorLines) and define errorDetails (the first 40 lines) remain. --verbose keeps every field and streams full progress snapshots.

Operation fields

Field Type Meaning
schemaVersion number 1.
name string operations/<id>.
done boolean Whether the operation has finished.
status string running, succeeded or failed.
version string The version defined or built, for example 1.0.1.
notes string Progress notes.
logsUri string The execution log page.
buildLogsUri string The build log page, on a build with an attached deploy.
error string The failure, when status is failed.
images[] array Per image: path (., worker) and, while building or on failure, progress with failure.errorLines.
deployments[] array Per deployment: name, state, logsUri, progress (a Terraform changeSummary with operation and change counts) and error.
next string On --async: the exact alis operations wait command, including --cwd.
metadata object Legacy: the raw operation metadata on a start result.

Stderr events

JSON
{"elapsed":"0:42","operation":"operations/…","progress":"Building image ."}

A timeout or CtrlC ends the stream with:

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

Error envelope

Failures before an operation exists, and refusals, print a structured envelope on stdout under --json:

JSON
{"error": {"code": "…", "message": "…", "retry": "…", "retryArgv": ["…"], "retryCwd": "…", "agent": "…", "details": {}}}
Field Meaning
code The error code (below). ERROR for unclassified failures.
message The readable message.
retry The readable recovery command, when there is one.
retryArgv, retryCwd The recovery command's arguments and working directory.
agent An instruction for a coding agent to follow.
details Structured data, for example the deployment environments to choose between.
Code Exit Meaning
PRODUCTION_CONFIRMATION_REQUIRED 3 A production deploy or variable change needs --confirm-production.
APPROVAL_REQUIRED 3 The user's automation tier gates this command; retry carries --approve.
ACTIVE_BUILD_ACCOUNT_REQUIRED 1 No active account: run alis accounts list, then alis accounts select accounts/<id>.
ENVIRONMENT_SELECTION_REQUIRED 1 Several deployment environments; details lists them.
ENV_NOT_FOUND 1 alis run found no <product>/.alis/.env.
NOT_FOUND 1 The resource does not exist, for example a service not deployed in the deployment environment.
NETWORK_UNAVAILABLE 1 The platform is unreachable from a restricted sandbox.
TIMEOUT 1 A headless invocation overran its budget; details.phase names the step. ALIS_COMMAND_TIMEOUT=<duration> overrides the budget.

Exit codes

Code Meaning Response
0 Success. Parse the result on stdout.
1 Failure: invalid usage, or the remote operation failed. Under --json a structured failure is still on stdout.
3 Confirmation required (PRODUCTION_CONFIRMATION_REQUIRED or APPROVAL_REQUIRED). Ask a person, then run the envelope's retry.
4 Unauthenticated. Run alis login, then retry.
5 No change: a wait reached its --timeout with nothing new. Not a failure; wait again.
other An external kill, or the exit status of the program alis run started (130 when interrupted). Treat as 1.

Waiting flags

Flag Type Default Meaning
--async bool false Start the operation and print its name and next without waiting.
--timeout duration 0 Give up waiting after this duration; the operation keeps running.
--poll-interval duration 2s How often to poll the operation.
--quiet bool false Suppress progress on stderr.
--verbose bool false With --json, keep every field and stream full snapshots.

Global flags

Flag Meaning
--json Output as JSON.
--cwd <dir> Run in this directory without changing the shell.
--approve Record that a person pre-approved this command. Never satisfies the production gate.
--verbose See above.
Command Fields
alis operations list --json operations[]: name, type, target, startedAt, next. With --active, running rows carry status, unreadable ones status: "unknown" and inspectionError.
alis operations cancel --json stopped: whether the build execution stopped.
alis logs build|deploy --json operation, kind, logs[] with target, text, truncated.
alis logs runtime --json projectId, services[], entries[].
alis define --dry-run --json package, folder, files[], valid, compiled, diagnostics[] (severity, file, line, column, message), git (uncommittedFiles, unpushedCommits, defineCommit), next.
alis context view --json organisation, product, packageId, serviceFolder, defineFolder, environments[] (id, displayName, status, production, projectId), notes.
alis environment list --json environments[]: id, displayName, production, status, allowedBranches.
alis environment variables --json environments[]: environmentId, displayName, canUpdate, envs[] (name, set); revealed.
alis service new --json packageId, name, organisation, product, serviceId, created, buildFolder, defineFolder, warning, next[].
alis run --dry-run --json dir, productRoot, envFile, envKeys[], runner, command[], reason.