Commands

If no command is specified, record is used by default. Record flags (-c, --paste, -o, -p, -m, --param) can be used without explicitly typing record.

Default: Record

bash

ostt                    # Record with real-time visualization, print to stdout
ostt record             # Explicit record command
ostt -c                 # Record and copy to clipboard
ostt --paste            # Record and paste into the focused app
ostt -o notes.txt       # Record and write to file
ostt -p clean           # Record and process with "clean" action
ostt -p clean -c        # Record, process, copy result
ostt -m deepgram/nova-3 # Override model for this run
ostt --param language=sv # Override a transcription param for this run

Alias: ostt r.

Flags

Flag	Description
`-c` / `--clipboard`	Copy transcription to clipboard
`--paste`	Paste transcription into the focused app using `[output.paste]` settings
`-o FILE` / `--output FILE`	Write transcription to file
`-p [ACTION]` / `--process [ACTION]`	Enable processing. Optionally specify action ID to skip picker.
`--attach FILE`	Send an image to the processing action too (needs `-p`)
`-m PROVIDER/MODEL` / `--model PROVIDER/MODEL`	Override transcription model for this run.
`--param KEY=VALUE`	Override one supported transcription param for this run. Repeat for multiple params.

Recording Controls

Key	Action
`Enter`	Stop recording and transcribe
`Space`	Pause or resume recording
`Esc`, `q`, `Ctrl+C`	Cancel without saving

The screen shows the live visualization (spectrum or waveform, see visualization) and a footer with the duration and peak level (the highest in the last 3 seconds). The footer turns red when the signal clips in auto mode, or passes peak_volume_threshold with a fixed reference level. See reference_level_db.

bash

ostt launch -c              # Open popup, record, copy to clipboard
ostt launch --paste         # Open popup, record, paste into focused app
ostt launch --paste -p clean # Popup, process with "clean", paste
ostt launch -c -p clean     # Popup, record, process with "clean", copy
ostt launch -m whisper/turbo -c # Popup, override model, copy
ostt launch -m whisper/turbo --param language=sv -c
ostt launch -- -c -p cmd    # Pass flags through to the instance

launch spawns a popup terminal with ostt running inside. If a recording process is already running, pressing the hotkey again sends SIGUSR1, which stops recording and triggers transcription.

With --paste, the popup closes before OSTT sends the configured paste shortcut. This lets the desktop return focus to the previous app first.

Configure popup window settings in ~/.config/ostt/ostt.toml under [popup].

Alias: ostt l.

Transcribe

Transcribe pre-recorded audio files using the configured provider/model.

bash

ostt transcribe recording.ogg              # Transcribe to stdout
ostt transcribe voice-memo.mp3 -c          # Transcribe and copy to clipboard
ostt transcribe voice-memo.mp3 --paste     # Transcribe and paste into focused app
ostt transcribe meeting.wav -o transcript.txt   # Transcribe to file
ostt transcribe audio.ogg -p clean -c      # Transcribe, process, copy
ostt transcribe audio.ogg -m openai/whisper-1 # Override model for this run
ostt transcribe audio.ogg -m deepgram/nova-3 --param diarize=true
ostt transcribe audio.ogg | grep keyword   # Pipe to other commands

Flags

Same as record: -c, --paste, -o, -p, --attach, -m, --param.

Alias: ostt t.

Retry

Re-transcribe a previous recording using the current model/provider settings. Useful when transcription failed or you want to try a different model.

bash

ostt retry              # Re-transcribe most recent recording
ostt retry 3            # Re-transcribe recording #3
ostt retry -c           # Re-transcribe and copy to clipboard
ostt retry --paste      # Re-transcribe and paste into focused app
ostt retry -p clean     # Re-transcribe and process
ostt retry -m groq/whisper-large-v3 # Override model for this run
ostt retry -m openai/gpt-4o-transcribe --param prompt=ProjectName -c

Recording indexes are 1-based, with 1 being the most recent.

Flags

Flag	Description
`N`	Recording index (1 = most recent)
`-c` / `--clipboard`	Copy to clipboard
`--paste`	Paste into the focused app
`-o FILE` / `--output FILE`	Write to file
`-p [ACTION]` / `--process [ACTION]`	Enable processing
`--attach FILE`	Send an image to the processing action too (needs `-p`)
`-m PROVIDER/MODEL` / `--model PROVIDER/MODEL`	Override transcription model for this run
`--param KEY=VALUE`	Override one supported transcription param for this run. Repeat for multiple params.

Replay

Play back the audio of a previous recording without transcribing.

bash

ostt replay             # Play most recent recording
ostt replay 2           # Play recording #2

On Linux, uses the first available of mpv, cvlc, ffplay, or paplay, falling back to xdg-open. On macOS, uses afplay.

Alias: ostt rp.

Process

Run a processing action on an existing transcription from history. The first argument is the history index (if numeric) or the action ID (if non-numeric). Provide both to target a specific item.

bash

ostt process                    # Process most recent, show action picker
ostt process clean              # Process most recent with "clean" action
ostt process 3                  # Process #3, show picker
ostt process 3 clean -c         # Process #3 with "clean", copy to clipboard
ostt process 3 clean --paste    # Process #3 with "clean", paste into focused app
ostt process list               # List configured actions
ostt process list --format json # List configured actions as JSON

Alias: ostt p.

Flags

Flag	Description
`N`	History index (1 = most recent)
`ACTION`	Action ID to run directly, skip picker
`list`	List all configured actions
`-c` / `--clipboard`	Copy result to clipboard
`--paste`	Paste result into the focused app
`-o FILE` / `--output FILE`	Write result to file
`--attach FILE`	Send an image to the action too
`--format table\|json`	Output format for `ostt process list`

If a processing action fails while recording (ostt, launch), transcribing or retrying, the unprocessed transcription is output instead. ostt, transcribe and retry then exit with status 3; ostt launch exits as soon as the popup opens. ostt process reports the failure and outputs nothing.

Agent

List the agents AI processing actions can run, whether each is installed, and whether it takes images. See Agents.

bash

ostt agent list                 # Agents, installed or not
ostt agent list --format json   # The same as JSON
ostt agent models claude-code   # Models an agent offers, one per line

Auth

Add or remove cloud provider credentials.

bash

ostt auth login       # Add or update a cloud provider API key
ostt auth logout      # Remove a cloud provider API key
ostt auth list        # List authenticated providers
ostt auth status      # Show authentication status

ostt auth without a subcommand defaults to ostt auth login. API keys are stored securely outside the main config file.

Alias: ostt a.

Model

Choose and manage the active transcription model.

bash

ostt model                              # Interactive model picker
ostt model list                         # List available models
ostt model list --provider openai       # Filter by provider
ostt model list --installed             # Show downloaded local models
ostt model current                      # Show active model
ostt model params                       # List params for active model
ostt model params openai/gpt-4o-transcribe --format json
ostt model select deepgram/nova-3       # Select active cloud model
ostt model select http/cohere-transcribe # Select configured HTTP engine
ostt model local download turbo         # Download local model
ostt model local download whisper/turbo # Download local model by full ID
ostt model local remove turbo           # Remove local model

The model picker lets you choose between cloud, built-in local, and configured external providers. Cloud models are shown for providers with saved credentials. Local models can be downloaded, activated, deleted, inspected, or added from a custom Hugging Face/direct model URL. Configured command/* and http/* external profiles are selectable too.

ostt model params [PROVIDER/MODEL] lists supported --param keys for a model. If no model is passed, it uses the active model. It supports the same list formatting flag as other list commands: --format table|json.

Param Overrides

--param KEY=VALUE is a per-invocation transcription param override. It applies to the selected model for that command, whether the model comes from saved config or -m PROVIDER/MODEL.

bash

ostt -m openai/gpt-4o-transcribe --param language=sv --param prompt=OSTT -c
ostt transcribe meeting.mp3 -m deepgram/nova-3 --param diarize=true --param keyterm=OSTT,VitePress
ostt retry 2 -m whisper/turbo --param language=en --param temperature=0.0

Rules:

--param can be repeated.
Each value must use KEY=VALUE.
Duplicate keys fail before transcription starts.
Unknown keys fail and show the valid params for the selected model.
Values are validated against the selected provider/model, including type, ranges, and provider-specific conflicts.
For list params on the CLI, separate values with commas, for example --param keyterm=OSTT,VitePress.

--param overrides apply only to the current command. They do not change ostt.toml and they take precedence over persistent params for the selected model.

Use ostt model params PROVIDER/MODEL to list supported keys, and use persistent [provider.params] or [provider."model".params] config for defaults that should apply every run. Unlike --param, an unknown param in ostt.toml does not fail: OSTT skips it and notes it in the log.

See Local Models for offline model setup.

Daemon

Keep the active local model (Whisper or Parakeet) loaded in memory so transcriptions start without loading the model each time.

bash

ostt daemon start      # Start the daemon for the active local model
ostt daemon stop       # Stop the running daemon
ostt daemon restart    # Restart with the current active local model
ostt daemon status     # Show status, model, PID, backend, and service
ostt daemon install    # Install as a login service (auto-start)
ostt daemon uninstall  # Remove the login service

See Daemon Mode. Alias: ostt d.

History

Browse previous transcriptions. Use arrow keys to navigate, Enter to copy, Esc to exit.

bash

ostt history                 # Interactive history browser
ostt history list            # List history
ostt history list --limit 10 # List recent entries
ostt history list --format json # List history as JSON
ostt history show 3          # Print history item #3
ostt history copy 3          # Copy history item #3

Alias: ostt h.

Keyword

Manage keywords for improved transcription accuracy. Add technical terms, names, or domain-specific vocabulary. Keywords are stored in ostt.toml under [transcription].keywords, so you can also edit them there.

bash

ostt keyword                 # Interactive keyword manager
ostt keyword list            # List keywords
ostt keyword list --format json # List keywords as JSON
ostt keyword add Kubernetes Rödeby # Add one or more keywords
ostt keyword remove Kubernetes # Remove one or more keywords

Alias: ostt k.

Replace

Manage deterministic, non-AI text replace rules for final transcript cleanup. Use replace for casing, acronyms, product names, and common misrecognitions after the model has already transcribed the audio.

bash

ostt replace # Interactive replace manager

Rules live under [text.replace] in ostt.toml and are applied before processing actions, output, and history saves. ostt keyword helps the model recognize terms; ostt replace fixes the final text. See Text Replace for matching rules.

Paste Output

Paste mode is an explicit output mode for sending the final transcript directly into the currently focused app:

bash

ostt --paste
ostt launch --paste
ostt launch --paste -p clean
ostt transcribe voice.ogg --paste
ostt retry 2 --paste
ostt process clean --paste

It is mutually exclusive with clipboard and file output:

bash

ostt --paste -c           # error: choose one output mode
ostt --paste -o notes.txt # error: choose one output mode

Paste uses the clipboard as transport and sends the configured paste shortcut. See Paste Output for [output.paste] settings, default shortcuts, and the Linux and macOS requirements.

Config

Open ~/.config/ostt/ostt.toml in your preferred editor.

bash

ostt config              # Open config in editor
ostt config path         # Print config file path
ostt config list-devices # List audio input devices

Uses $EDITOR, falling back to nano, then vi.

Alias: ostt c.

Logs

Show the last 50 lines of the most recent log file. Useful for troubleshooting.

bash

ostt logs        # Show recent logs
ostt logs path   # Print latest log file path
ostt logs follow # Follow latest log file

Shell Completions

Generate shell completion scripts for tab completion of commands and options.

Install directly to the standard location for your shell:

bash

sudo ostt completions install bash       # writes /etc/bash_completion.d/ostt
sudo ostt completions install zsh        # writes _ostt to /usr/share/zsh/site-functions (Linux)
                                         # or /usr/local/share/zsh/site-functions (macOS)
ostt completions install fish            # writes ~/.config/fish/completions/ostt.fish

Or generate and place the file manually:

bash

ostt completions bash > ostt.bash
ostt completions zsh > _ostt
ostt completions fish > ostt.fish

Bash

bash

sudo cp ostt.bash /etc/bash_completion.d/

Zsh

bash

sudo cp _ostt /usr/local/share/zsh/site-functions/
# Linux: /usr/share/zsh/site-functions/

Fish

bash

cp ostt.fish ~/.config/fish/completions/

After installation, restart your shell or source the completion file to enable completions.

Version and Help

bash

ostt --version        # Show version information
ostt --help           # Detailed help with examples
ostt -h               # Quick help

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Usage error (invalid arguments)

Command Aliases

Alias	Command
`r`	record
`t`	transcribe
`l`	launch
`p`	process
`a`	auth
`h`	history
`k`	keyword
`c`	config
`rp`	replay
`d`	daemon

bash

ostt r -c            # Same as: ostt record -c
ostt l -c            # Same as: ostt launch -c
ostt a               # Same as: ostt auth login

Commands ​

Default: Record ​

Flags ​

Recording Controls ​

Launch (Popup) ​

Transcribe ​

Flags ​

Retry ​

Flags ​

Replay ​

Process ​

Flags ​

Agent ​

Auth ​

Model ​

Param Overrides ​

Daemon ​

History ​

Keyword ​

Replace ​

Paste Output ​

Config ​

Logs ​

Shell Completions ​

Bash ​

Zsh ​

Fish ​

Version and Help ​

Exit Codes ​

Command Aliases ​

Commands

Default: Record

Flags

Recording Controls

Launch (Popup)

Transcribe

Flags

Retry

Flags

Replay

Process

Flags

Agent

Auth

Model

Param Overrides

Daemon

History

Keyword

Replace

Paste Output

Config

Logs

Shell Completions

Bash

Zsh

Fish

Version and Help

Exit Codes

Command Aliases