STT-Assistant/docs/CLI.md

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):

uv run stt-daemon setup

Non-interactive setup (specify sources directly):

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)

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:

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

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

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

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:

# 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

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

(Legacy) --check flag

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:

# 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