Run long operations asynchronously¶

Start a define, build, deploy or block operation without waiting, re-attach to it later, check its state, read its logs, and cancel a build.

Prerequisites¶

A signed-in CLI in, or pointed at, the service's folder.
Familiarity with the output contract.

Steps¶

Start the operation with --async. The command returns as soon as the operation exists:

❯ alis build --json --branch main --async

JSON

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

Keep name. next is the exact wait command, including --cwd when you passed one.

Re-attach and stream to completion when you are ready:
```
❯ alis operations wait operations/<id> --json
```
Progress streams on stderr; the final operation lands on stdout. --timeout <duration> gives up waiting after a while; the operation keeps running server-side and the last stderr event carries the next command to resume. --quiet hides progress. --poll-interval <duration> changes the polling rate (default 2s).
Poll once instead of waiting:
```
❯ alis operations describe operations/<id> --json
```
done, status (running, succeeded, failed), version, notes and logsUri are at the top level.
Find operations you started earlier on this machine:
```
❯ alis operations list --active --json
```
JSON
```
{"operations": [{"name": "operations/<id>", "type": "build", "target": "acme.shop.orders.v1", "startedAt": "<timestamp>", "next": "alis operations wait operations/<id> --json"}]}
```
Only operations started by this CLI on this machine appear. With --active, a row that cannot be read keeps status: "unknown" and inspectionError; an unreadable operation is not evidence that it stopped.
Read the execution log when something fails:
Shell
```
alis logs build operations/<id> --json
alis logs deploy operations/<id> --json
```
Add --package <pkg> when the operation is not in the local record.
Cancel a build that should not continue:
```
❯ alis operations cancel operations/<id> --json
```
Only builds can be cancelled. Wait for stopped: true in the result before starting replacement work.

Interrupts and timeouts¶

Ctrl-C or a --timeout never cancels the server-side operation. It ends the stream with a warning event on stderr that names the resume command:

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

Run that next to re-attach. Do not pass the time with sleep loops or git ls-remote polling: wait blocks efficiently.