# CLI Reference

The `stt-daemon` CLI provisions the virtual sink, runs the daemon, and lists devices. Every subcommand accepts the common overrides `--config`, `--device`, `--backend`, `--model`, `--language`, and `-v/--verbose`.

## Subcommands

The `stt-daemon` CLI supports these subcommands. Every subcommand also accepts the
common overrides `--config`, `--device`, `--backend`, `--model`, `--language`, and
`-v/--verbose` (for example `stt-daemon setup --device ...`).

### `setup` — Create virtual sink and loopbacks

Interactive setup (shows device picker):

```bash
uv run stt-daemon setup
```

Non-interactive setup (specify sources directly):

```bash
uv run stt-daemon setup --sources "alsa_input.usb-Foo,alsa_output.pci-0000.monitor"
```

This creates:
- A null sink (by default `VirtualMicSink`)
- A remap-source to expose the sink's monitor as a microphone (by default `VirtualMic`)
- Loopback modules routing each selected source into the sink
- A state file tracking all module IDs for later cleanup

### `run` — Start the daemon (auto-provisions if needed)

```bash
uv run stt-daemon run
```

If no saved provisioning exists and the sink is missing, the daemon will:
1. Show the interactive device picker
2. Create the sink and loopbacks (if sources are selected)
3. Start listening and transcribing

You can also override settings:

```bash
uv run stt-daemon run --device "alsa_input.usb-..." --language es --model base
uv run stt-daemon run -v  # Verbose logging
uv run stt-daemon run --check  # Test audio capture + model, then exit
```

### `list` — Show devices and provisioning status

```bash
uv run stt-daemon list
```

Output shows:
- Input devices (real microphones)
- Output devices (speakers/headphones; captured via their `.monitor` source)
- Current provisioning state (if a sink has been created)

### `clear` — Remove virtual sink and loopbacks

```bash
uv run stt-daemon clear
# or without confirmation prompt:
uv run stt-daemon clear --yes
```

This unloads all tracked modules and removes the state file. If
`audio/audio.json` is already gone (reboot, manual
delete, crash), `clear --yes` still finds orphaned modules by name
(`VirtualMicSink`/`VirtualMic` via `pactl list short modules`) and unloads
them in reverse order (loopbacks → remap-source → null-sink), so the
command is idempotent — safe to re-run and to recover from
`Sink 'VirtualMicSink' already exists but is not tracked`.

### `up` — Launch daemon, assistant, and optionally TUI

```bash
uv run stt-daemon up              # Start daemon + assistant (separate processes)
uv run stt-daemon up --with-tui   # Also launch the interactive TUI viewer
```

This subcommand runs the entire system as a supervised set of child processes:

- **daemon** — transcription engine (listens to audio, publishes transcriptions)
- **assistant** — controller (subscribes to transcriptions, serves the control socket)
- **TUI** (optional) — viewer/controller UI (connects to the assistant via control socket)

The supervisor manages their lifetimes: if any child exits or Ctrl+C is pressed, all
remaining children are cleanly shut down. Without `--with-tui`, you can still run
a separate `uv run stt-tui` in another terminal to view and control the assistant.

With `--with-tui`, the daemon and assistant output is discarded so it cannot corrupt
the screen, while the TUI keeps the terminal. Without `--with-tui`, all output goes to
the terminal. The supervisor writes nothing to disk.

Like all subcommands, `up` also accepts `--config`, `--device`, `--backend`,
`--model`, `--language`, and `-v` (verbose) flags.

Example workflow:

```bash
# One-command startup with TUI (everything stops when you quit the TUI)
uv run stt-daemon up --with-tui

# Or, start daemon + assistant only
uv run stt-daemon up

# Then in another terminal, launch the TUI whenever you want
uv run stt-tui
```

### (Legacy) `--list-sources` flag

```bash
uv run stt-daemon --list-sources
# Equivalent to: uv run stt-daemon list
```

### (Legacy) `--check` flag

```bash
uv run stt-daemon --check
# Equivalent to: uv run stt-daemon run --check
```

## Interactive Device Picker

When you run `setup` or `run` without `--sources`, the daemon shows an interactive picker:

- **TTY mode** (terminal): Uses `questionary` to show a checkbox UI. Pre-checked items are from the previously saved selection.
- **Non-TTY mode** (piped input): Shows a numbered menu; enter space/comma-separated indices, `all`, `none`, or blank (to keep previous selection).

Device labels:
- `[IN] <description> (<name>)` — Input device (real microphone)
- `[OUT] <description> (<name>)` — Output device (monitor of a sink)

## Running the daemon

The simplest workflow:

```bash
# Create/setup the sink (interactive)
uv run stt-daemon setup

# Start the daemon in another terminal
# (auto-uses the provisioned sink)
uv run stt-daemon run

# Stop and remove the sink when done
uv run stt-daemon clear --yes
```