---
title: "Operations and output"
url: "https://docs.alisx.com/reference/dbd/operations-and-output/"
---
# 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 ++ctrl+c++ 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. |

## Related outputs

| 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`. |