CLI commands

This page is the command-line reference. The macOS app does these tasks through its own menus, Settings, and drag-and-drop instead — see the How-to guides.

bristlenose <folder> is shorthand for bristlenose run <folder> — if the first argument is an existing folder, run is assumed.

Commands

Command	What it does
bristlenose run <folder>	Transcribe, analyse, and open the report in your browser.
bristlenose serve <folder>	Open a previously analysed report in the browser. No analysis is run. Also prints the details for connecting an AI agent.
bristlenose transcribe <folder>	Transcription only — no analysis, no API key required.
bristlenose analyze <folder>	Run the analysis on existing transcripts; skip transcription.
bristlenose status <folder>	Show which pipeline stages have completed. Read-only; no network.
bristlenose doctor	Check dependencies, API keys, and configuration.
bristlenose configure <provider>	Store credentials for a provider: claude, chatgpt, gemini, azure, local, or miro. Also makes that provider current for analysis.
bristlenose use <provider>	Switch the current analysis provider: claude, chatgpt, gemini, azure, or local. Keys stay stored.
bristlenose codebooks	List the codebook frameworks available to AutoCode.
bristlenose pipeline	Show which models each pipeline stage currently uses. Read-only.
bristlenose help [topic]	Detailed help. Topics: commands, config, workflows.

Common options

These apply to run (and analyze where relevant) unless noted.

Option	Effect
--llm, -l	Provider for the analysis pass, for this run only: claude, chatgpt, gemini, azure, local. If not given, the provider you last set with configure or use is used — or your sole configured provider.
--output, -o	Output directory. Defaults to bristlenose-output/ inside the input folder.
--project, -p	Project name shown in the report. (On serve, -p sets the port instead.)
--whisper-model, -w	Transcription model: tiny, base, small, medium, large-v3, large-v3-turbo. Default large-v3-turbo.
--whisper-backend, -b	auto, mlx, or faster-whisper. Default auto.
--redact-pii	Detect and remove personal data from transcripts before analysis. Off by default.
--codebook	Apply a codebook framework during analysis.
--skip-transcription	Skip transcription (transcripts already present).
--clean	Delete the output directory before running.
--no-fetch	Abort rather than download a missing model.
-v	Verbose output.
--version	Print the version and exit.

--lang is a root option, not a command one — it goes before the command: bristlenose --lang de run interviews. Putting it after the command fails with No such option: --lang.

Options specific to other commands:

Option	Command	Effect
--port, -p	serve	Port for the local server. Default 8150.
--palette	serve	Colour palette for the report: default or edo. See Appearance.
--fetch	doctor	Pre-download the transcription model (~1.5 GB) for offline use.
--self-test	doctor	Verify a bundled installation's data files.
--key, -k	configure	Provide the key non-interactively.
--stage	pipeline	Show one stage only, by id — for example quote_extraction.
--json	pipeline	Machine-readable output, for scripting.

Exit codes

Code	Meaning
0	Success.
1	Error during the run.
2	A pre-run check failed — a missing dependency, an uncached model with --no-fetch, or a rejected API key.