---
title: "alpacon event wait"
description: "Wait for an Alpacon event outcome and branch on the exit code. Set a timeout, select a target, and replace built-in success or failure conditions with --until."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# alpacon event wait

Wait for an event outcome, print it, and exit with the result.

## Usage

`alpacon event wait [flags]`

## Key facts

- `--type` is required; a work session also needs its ID in `--target`.
- Exit `0` means success, `6` means refusal, `4` means the outcome is still undecided, and `2` means the command line was rejected.
- Use `--until` for types without a built-in end condition; it replaces any built-in success and failure sets.
- The default timeout is 5 minutes.

## Flags

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `-h, --help` | `bool` | help for wait | `false` |
| `--target` | `string` | Target resource ID; omit where the server allows a subscription without one | — |
| `--timeout` | `duration` | How long to wait before giving up | `5m0s` |
| `--type` | `string` | Event type to subscribe to, e.g. work_session (required) | — |
| `--until` | `strings` | Sub types that end the wait (comma-separated). Overrides the built-in condition, and is required for a type this CLI has none for | — |
| `--output` | `string` | Output format: table or json | `table` |

## Examples

Wait for a work session

```bash
alpacon event wait --type work_session --target a1b2c3d4-5678-abcd-ef01-234567890abc
```

Wait up to 30 minutes

```bash
alpacon event wait --type work_session --target a1b2c3d4-5678-abcd-ef01-234567890abc --timeout 30m
```

Wait for approval only

```bash
alpacon event wait --type work_session --target a1b2c3d4-5678-abcd-ef01-234567890abc --until approved
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | An event in the success set arrived |
| 1 | The wait could not run: you are not logged in or your login expired and could not be refreshed, the event channel did not connect within 15 seconds, or the subscription was rejected. A flag or argument the CLI cannot parse, such as an unknown flag, an extra argument, or a `--timeout` that is not a duration, also exits 1 |
| 2 | The command line was rejected: `--type` is missing, `--target` is not a valid ID, `--until` is empty, `--timeout` is zero or negative, or the type has no built-in end condition and `--until` is not given |
| 4 | Timed out or interrupted—the outcome is still open |
| 6 | An event in the failure set arrived |

Exit code 4 means the outcome is still undecided, not that it failed. With `--output json`, the CLI emits `{"status": "pending_approval", ...}` on stdout, the same shape [`alpacon exec`](/reference/cli/exec/#exit-codes) uses.

## End conditions

`work_session` is the only type with a built-in end condition:

| Set | Sub types | Exit code |
|-----|-----------|-----------|
| Success | `approved`, `activated` | 0 |
| Failure | `rejected`, `expired`, `revoked`, `cancelled`, `completed` | 6 |

For any other type, name the sub types that end the wait with `--until`. Passing `--until` also replaces a built-in condition: the failure set goes with it, so exit code 6 cannot occur.

`--until` is matched against the event's sub type, so it can only end a wait for an event type that publishes one. Against a type that does not, the wait runs to its timeout and exits 4.

## Not missing an outcome

For a type with a built-in end condition, passing `--target` also reads the current state once right after subscribing, so an outcome that landed between the subscription and the first event is not missed. The read is repeated after every reconnect, since events published while disconnected are lost. No other type gets that read.

## Output

One line goes to stdout, in the same shape [`alpacon event watch`](/reference/cli/event/watch/#output) uses. Everything else goes to stderr.

## Finding a target ID

Run [`alpacon work-session ls`](/reference/cli/work-session/ls/) or open the Alpacon console.

Source: https://docs.alpacax.com/reference/cli/event/wait/