alpacon event
Subscribe to the Alpacon event channel and react to changes as they happen.
alpacon event [command] [flags]Aliases: event, events
What the event channel is
Some things in Alpacon take a while: a work session waits for a reviewer, a long command keeps producing output, a cloud integration works through a queue of servers. Without the event channel, the only way to learn the result is to keep asking—run a command, read the status, sleep, run it again.
The event channel turns that around. You subscribe once, and Alpacon sends you each change as it happens. A person watching a terminal sees new lines appear; a script or an AI agent gets one line per event on stdout, or a single exit code once the outcome is decided.
Every event has three parts:
| Part | What it means | Example |
|---|---|---|
| Event type | The kind of thing you are subscribing to. You choose it with --type. | work_session |
| Sub type | What actually happened to it, for an event type that publishes one | approved |
| Target | Which specific resource it happened to. You choose it with --target. | The work session’s ID |
So a single line of output like this:
14:32:07 work_session approved a1b2c3d4-5678-abcd-ef01-234567890abcreads as: at 14:32:07, the work session a1b2c3d4-… was approved.
Event types you can subscribe to
Alpacon defines the list of event types, so --type accepts more than the CLI knows names for. These are the ones you are most likely to use:
| Event type | What it reports | --target |
|---|---|---|
work_session | A work session moving through its lifecycle: approved, activated, rejected, expired, revoked, cancelled, completed | Required: the work session ID |
notification | Your own notification feed | Optional: defaults to you, and another user’s ID is rejected |
command_output | Output produced by one running command | Required: the command ID |
sudo | Sudo approval requests raised during a terminal session | Required: the session ID |
cloud_discovery, cloud_install, cloud_reconcile, cloud_account | Progress of cloud integration jobs | Optional |
metric_threshold_crossed, metric_threshold_resolved | A metric alert rule crossing its threshold, or clearing back below it. Only available when the workspace has the metrics extension. | Optional: a server ID scopes it to that server; omitting it (admin only) matches every server |
A rule that stops receiving data entirely is reported the same way, as metric_threshold_crossed with a reason of no_data, rather than as a separate event type.
A subscription you are not allowed to make—someone else’s notifications, a work session you cannot see, a metric threshold event on a workspace without the metrics extension—is rejected, and the command exits with an error instead of waiting.
What to expect from a subscription
- No history. You receive only what is published after you subscribe. Nothing that happened earlier is replayed.
- Gaps are possible. If the connection drops, it is re-established automatically, but events published while it was down are lost. Both the drop and the recovery are reported on stderr.
- An outcome can slip past. If you subscribe just after the thing you were waiting for happened, no event will ever arrive.
waithandles this for you: with--target, it reads the current state once right after subscribing, and again after every reconnect.
Which subcommand to use
| What you want | Use |
|---|---|
| Follow everything of one type as it happens, until you stop it | watch |
| Block until one outcome is decided, then continue or fail a script | wait |
watch never exits on its own—it streams until interrupted. wait exits as soon as one event decides the result, and its exit code tells you which result it was, so a script or an agent can branch without reading any text.
Running alpacon event with no subcommand still lists recent remote command executions, but that use is deprecated. It has moved to alpacon exec ls and will be removed in a future release.
Deprecated: listing command executions
alpacon event with no subcommand lists recent remote command executions, most recent first, and prints a deprecation warning. Use alpacon exec ls instead—it takes the same flags and produces the same output.
alpacon event [flags]Options
-h, --help help for event
-s, --server string Filter by server name
-t, --tail int Number of command entries to show, newest first (default 25)
-u, --user string Filter by requesting userExamples
# Deprecated
alpacon event --tail 10 --server my-server --user admin
# Use this instead
alpacon exec ls --tail 10 --server my-server --user admin