# The whinge command

`whinge` controls the Whinge app. Install the command from Settings or with
`/Applications/Whinge.app/Contents/Helpers/whinge install`.

```text
whinge [start] [--output DIR]
whinge attach
whinge stop | cancel | draw | clear | bug | status | last
whinge log [DIR] [--path]
whinge settings | install | version
```

`start` first listens for a start phrase, then records until Stop. `--output DIR` chooses the
parent folder for this recording; without it, Whinge uses the location in Settings, initially
**Documents/Whinges**.

`attach` waits for the active recording. `cancel` discards a recording or stops listening.
`last` prints the newest saved folder. Exit status is 0 on success, 1 on failure and 2 on
cancellation.

## Watching a recording happen

`start` and `attach` print one JSON object per line as things happen, so another program can
follow a recording without waiting for it to end. A reader should ignore any event or key it
doesn't recognise; more may be added.

```text
{"event":"listening","phrase":"let's whinge"}
{"event":"started","dir":"/Users/you/Documents/Whinges/2026-09-23-114500"}
{"event":"transcript","t":6.8,"text":"the login form loses focus"}
{"event":"snapshot","t":9.1,"file":"snapshots/00009.10-1-clear.png","reason":"clear"}
{"event":"topic","t":12.4,"topic":2}
{"event":"saving"}
{"event":"finished","dir":"/Users/you/Documents/Whinges/2026-09-23-114500"}
```

| Event | When | Keys |
| --- | --- | --- |
| `listening` | waiting for the start phrase | `phrase` |
| `started` | recording began | `dir` |
| `transcript` | a stretch of speech finished | `t`, `text` |
| `snapshot` | a still was grabbed | `t`, `file`, `reason` |
| `topic` | the drawing was cleared | `t`, `topic` |
| `saving` | Stop was pressed, writing the folder | — |
| `finished` | saved | `dir` |
| `cancelled` | discarded (exit 2) | — |
| `failed` | something went wrong (exit 1) | `error` |

`t` is seconds into the recording. `file` is relative to `dir`. The last line is always one of
`finished`, `cancelled` or `failed`.

Other apps, including Offsider, can launch `whinge start --output DIR` and read the `finished`
line for the saved folder.