---
title: "Run long operations asynchronously"
url: "https://docs.alisx.com/how-to/cli/run-long-operations-asynchronously/"
---
# 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](https://docs.alisx.com/reference/cli/output-contract.md).

## Steps

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

    ```bash title="Terminal"
    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.

2. Re-attach and stream to completion when you are ready:

    ```bash title="Terminal"
    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`).

3. Poll once instead of waiting:

    ```bash title="Terminal"
    alis operations describe operations/<id> --json
    ```

    `done`, `status` (`running`, `succeeded`, `failed`), `version`, `notes` and `logsUri` are at the top level.

4. Find operations you started earlier on this machine:

    ```bash title="Terminal"
    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.

5. Read the execution log when something fails:

    ```bash title="Terminal"
    alis logs build operations/<id> --json
    alis logs deploy operations/<id> --json
    ```

    Add `--package <pkg>` when the operation is not in the local record.

6. Cancel a build that should not continue:

    ```bash title="Terminal"
    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:

```text
{"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.

Related: [alis operations](https://docs.alisx.com/reference/cli/operations.md), [alis logs](https://docs.alisx.com/reference/cli/logs.md), [Script the CLI with JSON](https://docs.alisx.com/how-to/cli/script-the-cli-with-json.md).