# RecordCue CLI reference

Always use the skill's `scripts/recordcue` wrapper rather than assuming a
particular app path. It honors `RECORDCUE_APP`, delegates to a `recordcue`
command-line tool when one is installed (while skipping the wrapper itself),
checks the standard application locations, then asks macOS Launch Services for
bundle identifier `com.frontmind.recordcue`. Set `RECORDCUE_APP` to either
`RecordCue.app` or its `Contents/MacOS/RecordCue` executable only when
overriding discovery.

## Commands

```sh
scripts/recordcue latest --json
scripts/recordcue list [--since 7d] --json
scripts/recordcue inspect <recording-path|latest> --json
```

All commands are read-only. They return only finished recordings, never start
or stop capture, and never analyze or upload media.

`list --since` accepts a positive duration such as `7d`, `24h`, or `30m`.
Use `inspect` with an exact media path returned by `latest` or `list`.

## JSON

`latest` and `inspect` return one recording. `list` returns:

```json
{ "schemaVersion": 1, "recordings": [] }
```

Each recording includes `media.path`, capture details, timestamps, duration,
and, when it exists, `transcript.path`. The transcript field is absent rather
than null until a transcript is available. `speakerActivity`, when present,
describes microphone/system-audio activity; it does not identify people.

Version 1.2.2 adds optional `transcription` metadata: `state` is `queued`,
`running`, `completed`, `failed`, `interrupted`, or `cancelled`; `updatedAt`
and an optional `reason` describe its last transition. Completed results may
include `totalPassages`, `recognisedPassages`, and `failedPassages`. These count
recognition passages, not words or a measured accuracy rate. Older recordings
can omit this metadata. A ready recording can still be waiting for its text.
Recordings being written or left interrupted are excluded from CLI results.

`transcript.path` is the source for transcript-based work. `media.path` is the
original audio or video and should be used only for explicitly requested direct
media analysis. The CLI itself never opens or uploads either file.

## Exit codes

- `0`: command succeeded.
- `2`: invalid arguments.
- `3`: no recording found or the requested path is unavailable. Treat this as
  "not ready or not present", not as an empty transcript.
- `4`: RecordCue could not complete its recording scan. Do not use a partial
  result; tell the user to narrow the request or inspect the recordings folder.
- `127`: the Skill wrapper could not find a runnable RecordCue app or CLI. This
  is not the same as "no recordings". Ask the user to install and open
  RecordCue, or to correct `RECORDCUE_APP` when they set it explicitly.