Script the CLI

Every blixel command answers in JSON, so scripts and agents can rely on its
output. blixel schema describes each command's options, results and errors.

Output

A result is one line of JSON on standard output:

{"data":{"state":"idle"},"schema_version":1}

Read what you need from data, for example with jq:

meeting=$(blixel room current | jq -r '.data.meeting_id // empty')

• Keys are sorted and in snake_case. A key that is absent means none or not
  applicable.
• Ids are strings. Treat them as opaque.
• Times are ISO 8601, in UTC.
• schema_version changes only when a field changes meaning or is removed.
  Expect new fields.
• Add --human for text meant for people. Its wording may change.

transcript follow, chat follow and event watch print one JSON object per
line as things happen. Each line carries a cursor; pass the last one you
finished processing as --after to resume without missing anything.

Errors and exit statuses

A failure goes to standard error as JSON:

{"error":{"category":"unavailable","code":"app_unavailable","exit_status":5,"message":"…"},"schema_version":1}

Branch on the exit status, then on code. message and hint are for people.

blixel schema <group> <command> lists the codes each command can fail with.

Request ids

chat send and agent connect take --request-id <uuid>. Without one, the
CLI makes one and writes it to standard error before it asks the app.

If the command fails with an unknown outcome (send_outcome_unknown,
connect_outcome_unknown) or is interrupted, run it again with the same
--request-id, never a new one. A repeat in the same meeting does not send a
second message: it returns the first one with "replayed": true.

Describe the commands

blixel schema                  # every command in brief
blixel schema chat             # one group
blixel schema chat send        # one command in full

blixel schema reads and contacts nothing. For each command it gives what the
command changes, what it needs, its options, result fields and error codes, and
example command lines.