---
name: video-cli
description: Use this skill to operate the Mere Video CLI for authenticated room, meeting, artifact, diagnostics, and agent-join workflows.
---

# Video CLI

Use this skill for requests touching the standalone `mere-video`/`meets` CLI and the underlying internal API that it calls.

## Scope

- CLI command surface in `video/cli/*`, especially `video/cli/meets.ts`, `video/cli/client.ts`, `video/cli/auth.ts`, and `video/cli/session.ts`.
- Internal API route usage under:
  - `video/src/routes/api/cli/v1`
  - `video/src/routes/api/internal/mere`
- Operator workflows for room inventory, meeting inspection, transcript/recording artifacts, client diagnostics, and agent joins in the ZeroSMB context.

## Base commands and environment

1. Set base URL:
   - `--base-url` flag or `MEETS_BASE_URL`.
2. Set workspace context for room/meeting list and create commands:
   - `--workspace` flag or `MEETS_DEFAULT_WORKSPACE_ID`/`MEETS_WORKSPACE_ID`.
3. Use a token directly for automation:
   - `--token TOKEN` or `MEETS_INTERNAL_TOKEN`.
4. Add `--json` when scripting.
5. Use `completion [bash|zsh|fish]` for shell setup.
6. Use `--yes --confirm <exact-id>` for `rooms archive`.

## Immediate runbook

1. Build the CLI:
   - `cd video && pnpm build:cli`.
2. Authenticate:
   - `./dist/run.js --base-url https://mere.video auth login`
   - `./dist/run.js --base-url https://mere.video auth whoami`
3. Validate health:
   - `./dist/run.js health --base-url https://mere.video --token <MEETS_INTERNAL_TOKEN>`
4. Manage rooms:
   - list/show/create/update/archive/invite.
5. Inspect meetings:
   - `meetings list --workspace <workspace-id>`.
   - `meetings show <meeting-id>`.
   - `participants list <meeting-id>`.
6. Inspect artifacts and diagnostics:
   - `recordings list --workspace <workspace-id> [--meeting <meeting-id>]`.
   - `recordings start <meeting-id> --workspace <workspace-id>` to run the browser recorder participant.
   - `recordings start <meeting-id> --workspace <workspace-id> --no-run --json` for non-blocking lifecycle setup.
   - `recordings stop <meeting-id> --workspace <workspace-id>` to ask the active recorder to finalize.
   - `recordings download <recording-id> --workspace <workspace-id> --output recording.webm`.
   - `transcripts export <meeting-id> --workspace <workspace-id> --output transcript.json`.
   - `diagnostics client-errors --workspace <workspace-id>`.

## Reference documents

- [command-reference.md](references/command-reference.md): complete command surface, flags, and handler mappings.
- [route-map.md](references/route-map.md): internal route targets and source files.

## Authentication workflow

1. `auth login`:
   - starts local callback listener at `127.0.0.1:<ephemeral>`.
   - opens an authorization URL from `/api/cli/v1/auth/start`.
2. Login completion triggers `/api/cli/v1/auth/exchange`.
3. Saved sessions keep refresh-token state and renew CLI access through `/api/cli/v1/auth/refresh` when needed.
4. Session is written to:
   - `~/.local/state/mere-video/session.json`.
5. `auth whoami` reads the cached session.
6. `auth logout` clears local session and calls `/api/cli/v1/auth/logout`.

## Room workflows

1. `rooms list --workspace <id>` to get room inventory.
2. `rooms create --workspace <id> --name "<..." [--slug ...] [--persistent]`.
3. `rooms show <room-id>` to inspect a single room.
4. `rooms update <room-id> --name/--slug` (at least one required).
5. `rooms archive <room-id> --yes --confirm <room-id>` to archive.
6. `rooms invite <slug>` to build a join URL (`room URL only; no API call`).

## Meetings workflow

1. `meetings list --workspace <id>` to retrieve recent meeting summaries for the workspace.
2. `meetings show <meeting-id>` to retrieve meeting detail plus participants.
3. `participants list <meeting-id>` when you only need participant rows.
4. `transcripts list <meeting-id>` or `transcripts export <meeting-id> --format txt|json` for stored transcript segments.
5. `recordings start <meeting-id>` creates a DB recording row and runs the trusted browser recorder participant.
6. `recordings stop <meeting-id>` flips the active row to `stopping`; the recorder runtime polls this and uploads/finalizes.
7. `recordings list --meeting <meeting-id>` and `recordings show <recording-id>` inspect stored artifacts.
8. The recorder is an audio-mix WebM recorder MVP, not composited video-grid recording.
9. Use `--json` for automation and joins into reporting scripts.

## Diagnostics workflow

1. `diagnostics health` checks D1 and the room worker.
2. `diagnostics room-worker` aliases health for operator muscle memory.
3. `diagnostics client-errors --workspace <id>` lists room client error reports.
4. `diagnostics client-error <error-id> --workspace <id>` inspects one report.

## Validation notes

- Health and internal room/meeting routes require a valid internal token.
- `rooms create` and `rooms list` require workspace ID resolution.
- `rooms update` requires at least one of `--name` or `--slug`.
- `rooms show`, `rooms update`, and `rooms archive` require exactly one room id argument.
- `recordings download` and `transcripts export --output` create parent directories before writing files.
- `meetings`, `participants`, `recordings`, `transcripts`, and diagnostic reads do not mutate state; they only read workspace-scoped route-backed data.

## Safe edits

For CLI behavior changes edit:
- `video/cli/meets.ts` (parser, command dispatch, validation messages)
- `video/cli/client.ts` (HTTP route targets, response parsers)
- `video/cli/auth.ts` (browser login flow)
- `video/cli/session.ts` (session persistence)

For server-side behavior changes edit:
- `video/src/routes/api/cli/v1/auth/*`
- `video/src/routes/api/internal/mere/[...path]/+server.ts`
- `video/src/routes/api/internal/zerosmb/health/+server.ts`
- `video/src/routes/api/internal/zerosmb/rooms*`
- `video/src/routes/api/internal/zerosmb/meetings*`
- `video/src/routes/api/internal/zerosmb/recordings*`
- `video/src/routes/api/internal/zerosmb/client-errors*`
- `video/src/routes/api/room/[slug]/transcripts/+server.ts`