blixel blixel

What a command receives

The event

Blixel never puts an event's data into the command itself, so nothing in an
event can change what runs. Your command gets the event two ways:

  • On standard input, as one line of JSON, the way blixel event watch prints
    it. See What an event looks like.
  • As environment variables.

Every run gets these:

Variable Value
BLIXEL_EVENT_TYPE The event type, such as transcript.ended.
BLIXEL_EVENT_ID The event's id, a whole number.
BLIXEL_EVENT_SUBJECT The event's subject.
BLIXEL_ROOM_ID The room's id, or empty when the event has none.
BLIXEL_ATTEMPT 1 for the first try, 2 for the first retry, and so on.
BLIXEL_HOME Blixel's folder, usually ~/.blixel.

And these, for the event's type:

Events Variables
transcript.started, transcript.ended BLIXEL_TRANSCRIPT_ID
meeting.joined, meeting.left BLIXEL_MEETING_ID
participant.joined, participant.left BLIXEL_MEETING_ID, BLIXEL_PARTICIPANT_SID, BLIXEL_PARTICIPANT_IDENTITY (empty when there is none)
handoff.sent BLIXEL_MEETING_ID, BLIXEL_TARGET_IDENTITY, BLIXEL_HANDOFF_SOURCE
handoff.received BLIXEL_MEETING_ID, BLIXEL_SENDER_IDENTITY, BLIXEL_CONNECTION_ID, BLIXEL_AGENT_PROVIDER, BLIXEL_HANDOFF_SOURCE

Each one holds the field of the same name in the event's data. The command
also gets the rest of Blixel's environment.

How it runs

  • It runs in your login shell, as $SHELL -lc '<command>'. So PATH is the
    one your login files set, such as Homebrew's in ~/.zprofile. ~/.zshrc
    isn't read; set PATH in ~/.zprofile.
  • A hook runs one event at a time, in order. Different hooks run side by side.
  • Exit status 0 is success. Any other status is a failure.
  • Past its timeout, the command and everything it started are stopped.
  • A failed run is tried again as many times as the hook's retries, 1 minute
    after the first failure, then 2, then 4, and so on. After the last, Blixel
    gives up on that event, notifies you, and goes on to the next.
  • macOS treats what the command does as Blixel doing it. A command that reads
    ~/Documents can make macOS ask whether Blixel may, and a permission Blixel
    already has, such as the microphone, applies to the command too.

When Blixel quits

A command keeps running if Blixel quits or crashes. Blixel can't tell how that
run ended, so when it opens again it runs that event again, possibly while the
first run is still going. Make your commands safe to run twice.

Quitting during a call ends it. Its transcript.ended and meeting.left run
their hooks when Blixel opens again. Once Blixel is quitting, no new run
starts.

Output and logs

  • What a command prints, and its errors, go to
    ~/.blixel/hooks/<id>/runs/<event-id>-<attempt>.log. Open Log on the
    Hooks page opens it.
  • Blixel's own log, ~/Library/Logs/Blixel/blixel.log, has a line for each
    finished run and says why a hook can't run.
  • Where each hook is up to, and its runs of the last 100 events, are kept in
    ~/.blixel/hooks/state.json. Only Blixel writes it.

Check and run again from the command line

blixel hook list
blixel hook show standup
blixel hook rerun standup <event-id> --wait
blixel hook test standup --wait
  • hook list shows each hook and how its last run went.
  • hook show lists a hook's runs, newest first, with each run's event id and
    log.
  • hook rerun runs a failed event once more, like Run Again.
  • hook test runs the hook for the newest matching event, like Test with
    Latest Matching Event    .

hook rerun and hook test need Blixel open. With --wait, they answer when
the run ends.

To run something whether or not Blixel is open, write a script around
blixel event watch that saves its own place. See
Watch events.