alpacon event wait

Block until one event decides the wait, print it, and exit. The outcome is carried by the exit code, so a script never has to parse prose.

This is the command to reach for in automation: put it between “ask for something” and “act on it”, and the step in the middle finishes exactly when the answer arrives. An AI agent that requested a work session can run wait, then branch on the exit code alone—0 means go ahead, 6 means it was refused, 4 means still undecided. See what the event channel is for the concepts behind --type and --target.

alpacon event wait --type TYPE [--target TARGET_ID] [--until SUB_TYPE...] [--timeout DURATION]

Options

  -h, --help                 help for wait
      --target string        Target resource ID; omit where the server allows a subscription without one
      --timeout duration     How long to wait before giving up (default 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

The global --output flag (table or json) selects the line format.

Exit codes

CodeMeaning
0An event in the success set arrived
1The wait could not run: the connection failed, the subscription was rejected, or the command was used incorrectly
4Timed out or interrupted—the outcome is still open
6An 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 uses.

End conditions

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

SetSub typesExit code
Successapproved, activated0
Failurerejected, expired, revoked, cancelled, completed6

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 uses. Everything else goes to stderr.

Examples

Wait for a work session to be approved, then branch on the result:

alpacon event wait --type work_session --target a1b2c3d4-5678-abcd-ef01-234567890abc
case $? in
  0) echo "approved" ;;
  4) echo "still pending" ;;
  6) echo "not approved" ;;
  *) echo "could not wait" ;;
esac

Wait up to 30 minutes:

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

End the wait on approval only, ignoring the built-in failure set:

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

Finding a target ID

Run alpacon work-session ls or open the Alpacon console.

Last updated: