---
title: "alpacon event watch"
description: "Stream Alpacon events until interrupted. Select an event type and target, output NDJSON for scripts, and understand what happens when the connection drops."
---

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

# alpacon event watch

Stream Alpacon events until you stop the command.

## Usage

`alpacon event watch [flags]`

## Key facts

- `--type` is required; `--target` selects a resource when the event type requires one.
- Each event is one line on stdout; status messages go to stderr.
- Use `--output json` for NDJSON and Ctrl+C to stop.

## Flags

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `-h, --help` | `bool` | help for watch | `false` |
| `--target` | `string` | Target resource ID; omit where the server allows a subscription without one | — |
| `--type` | `string` | Event type to subscribe to, e.g. work_session or notification (required) | — |
| `--output` | `string` | Output format: table or json | `table` |

## Examples

Watch one work session

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

Feed a script with NDJSON

```bash
alpacon event watch --type notification --output json
```

## Output

One line goes to stdout per event, and everything else—status messages and warnings—goes to stderr, so the stream stays machine-readable when piped.

The default `table` format prints four tab-separated fields: receive time, event type, sub type, and the target you passed to `--target`. The sub type and the target print as `-` when the event carries no value for them.

```
14:32:07	work_session	approved	a1b2c3d4-5678-abcd-ef01-234567890abc
```

That line reads as: at 14:32:07, the work session `a1b2c3d4-…` was approved.

With `--output json`, each line is the event compacted to a single line (NDJSON). Every field the server sends survives, including ones this CLI does not know about. One event per line means a consumer can read the stream incrementally instead of waiting for it to end:

```bash
alpacon event watch --type work_session --target a1b2c3d4-5678-abcd-ef01-234567890abc --output json | while read -r event; do
  echo "$event" | jq -r '.payload.sub_type'
done
```

## Reconnection

The connection is re-established automatically when it drops, and both reconnects and failing reconnects are reported on stderr. Events published while you were disconnected are lost—the channel has no history to replay.

If the connection does not come up within 15 seconds, the command exits with an error.

## 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/watch/