Documentation

Everything you need to use Golos.

Getting Started

Install Golos with a single command:

curl -fsSL https://raw.githubusercontent.com/basilysf1709/golos/main/install.sh | bash

Then configure your Deepgram API key:

golos setup

Grant Accessibility permission to your terminal in System Settings → Privacy & Security → Accessibility, then start Golos:

golos

Hold Right Option to record. Release to transcribe and paste.

Commands

golosRun in foreground
golos -dRun in background (detached)
golos stopStop the background process
golos setupConfigure your Deepgram API key
golos versionPrint version, commit, and build date
golos add "phrase" "replacement"Add a dictionary replacement
golos delete "phrase"Remove a dictionary entry
golos listList all dictionary entries
golos import file.tomlImport dictionary entries from a TOML file

Flags

Flags are passed when running Golos (not with subcommands like add or stop).

--output <mode>Output mode: "clipboard" (default) or "stdout"
--hotkey <key>Push-to-talk key (default: "right_option")
-d, --detachRun as a background daemon

Examples

golos --output stdout

Print transcription to the terminal instead of pasting to clipboard.

golos --hotkey right_command

Use Right Command as the push-to-talk key.

golos -d --output stdout

Run in background with stdout output.

Dictionary

The dictionary replaces spoken words with custom text. Say “period” and get . in your output. The dictionary file lives at ~/.config/golos/dictionary.toml.

Add entries

golos add "period" "."
golos add "new line" "\n"

Remove an entry

golos delete "period"

List all entries

golos list

Import from a file

golos import dictionary.example.toml

The TOML file should have a [words] table:

[words]
"period" = "."
"comma" = ","
"question mark" = "?"
"new line" = "\n"
"new paragraph" = "\n\n"
"open paren" = "("
"close paren" = ")"
"arrow" = "->"
"fat arrow" = "=>"

Configuration

Config lives at ~/.config/golos/config.toml. Run golos setup to create it, or edit directly:

deepgram_api_key = "your-key"
hotkey = "right_option"
output_mode = "clipboard"
sample_rate = 16000
language = "en-US"
overlay = true
deepgram_api_keyYour Deepgram API key (required)
hotkeyPush-to-talk key (default: "right_option")
output_mode"clipboard" or "stdout" (default: "clipboard")
sample_rateAudio sample rate in Hz (default: 16000)
languageDeepgram language code (default: "en-US")
overlayShow visual overlay while recording (default: true)

Resolution order

Settings are resolved in this order. Later sources override earlier ones:

  1. Built-in defaults
  2. .env file in the current directory
  3. ~/.config/golos/config.toml
  4. Environment variables
  5. CLI flags (--output, --hotkey)

Hotkeys

Valid values for the hotkey config or --hotkey flag:

right_optionRight Option / Alt key (alias: right_alt)
right_commandRight Command key (alias: right_cmd)
fnFn key
f18F18 key
f19F19 key
golos --hotkey fn

Environment Variables

These override the matching config.toml values:

DEEPGRAM_API_KEYOverrides deepgram_api_key
GOLOS_OUTPUTOverrides output_mode
GOLOS_HOTKEYOverrides hotkey
DEEPGRAM_API_KEY="your-key" golos

You can also put variables in a .env file in your working directory.