Skip to content

CLI

Jump to bottom
Garon edited this page Jun 22, 2026 · 2 revisions

CLI

Glimpse ships a glimpse command that does more than transcribe a file. It covers two things:

  • a speech engine for running, serving, and managing models from the terminal, and
  • a scripting surface for the app: your history, dictionary, replacements, library, model selection, and the local API, so Finder Quick Actions, Shortcuts, Raycast, and shell scripts can drive Glimpse without clicking around.

Quick links

Install the CLI

The glimpse command isn't on your PATH by default. You install it from inside the app.

  1. Open Glimpse.
  2. Go to Settings, About.
  3. Under Command line, click Install CLI.

That creates ~/.local/bin/glimpse pointing at the Glimpse binary (a symlink on macOS, a small .cmd shim on Windows). The CLI is part of Glimpse Personal / commercial, so you need an active license for the install button to be enabled. Use Uninstall in the same row to remove it.

If glimpse isn't found afterward, make sure ~/.local/bin is on your PATH and restart your shell. The About screen flags this for you when the directory isn't on PATH.

How it works

Commands fall into three buckets depending on whether they need the running app.

Bucket Commands App needed?
Headless reads, query the local databases directly history …, dictionary list, replacements list, model list, library status / list / export No. Glimpse just has to have run once so the databases exist.
App actions, change state or transcribe with your settings dictionary add / remove, replacements add / remove, model set, library import, open, api start / stop Yes. The CLI talks to the app over a local control socket and launches it in the background if it isn't running.
Engine, standalone speech with no app models …, serve, raw transcribe No. These run the bundled speech engine directly.

Two commands connect to the app only if it's already running, and never launch it: status and transcribe in Glimpse mode (see below). They report a clear "app not running" instead.

Licensing. Installing the CLI and running app actions or engine commands require an active license. App actions are checked when the command reaches the app. Headless reads need neither a license nor a running app.

The control socket is a per-user local socket (a Unix domain socket on macOS, a named pipe on Windows). The name includes your username so accounts on a shared machine can't collide.

Output and exit codes

Add --json to any command for machine-readable output: {"ok":true, …} on success, and {"ok":false,"error":"…"} on stderr when it fails. For transcribe, --json also switches it into Glimpse mode (see below).

Exit Meaning
0 Success
1 User error (bad args, file or item not found, not licensed)
2 App required but not running, or it couldn't be launched
3 Job failed (transcription or import error)
4 Cancelled, or --wait timed out

transcribe

transcribe has two modes. With no Glimpse-specific flag it hands off to the raw speech engine. Pass any of --output, --output-dir, --stdout, --suffix, --language, --model, --cleanup, --no-cleanup, or --json, and it switches to Glimpse mode: it reuses the running app's warm model and applies your dictionary, replacements, and (optionally) LLM cleanup, the same as dictating in the app.

Glimpse mode

Needs Glimpse running. It won't auto-launch; you'll get exit code 2 if it's closed.

glimpse transcribe ~/Desktop/meeting.m4a                       # writes meeting.txt beside it
glimpse transcribe meeting.m4a --output ~/Desktop/notes.txt
glimpse transcribe *.m4a --output-dir ~/Desktop/transcripts --json
glimpse transcribe clip.wav --stdout
Flag Description
--output <path> Write the transcript to this file (single input only)
--output-dir <dir> With multiple inputs, write <dir>/<basename><suffix> for each
--suffix <ext> Output extension when inferring paths (default .txt)
--stdout Print the transcript instead of writing a file
--language <code> Override the language for this run
--model <id> Override the speech model (a model key from model list)
--cleanup / --no-cleanup Force or skip LLM cleanup regardless of your setting
--json Emit a structured result per file

With no --output, --output-dir, or --stdout, it writes a sibling <name>.txt next to each input and prints the path. --output is single-file only; use --output-dir for batches. Glimpse-mode transcribe does not create library items. Use library import for that.

Raw engine mode

No Glimpse flags goes straight to the engine, unchanged from earlier versions:

glimpse transcribe meeting.wav --response-format srt
glimpse transcribe note.wav --prompt "ACME, Tauri" --timestamps
  • --prompt "…", initial prompt or context
  • --dictionary term, bias toward a term (repeat for more)
  • --timestamps, include segment timestamps
  • --response-format text|json|verbose_json|srt|vtt, defaults to text; verbose_json includes segments

models

Manage the bundled speech models (engine command, no app needed).

glimpse models list
glimpse models install whisper_large_v3_turbo_q8
glimpse models status whisper_large_v3_turbo_q8
glimpse models delete  whisper_large_v3_turbo_q8

--json and --cache-dir <DIR> are global and can sit anywhere on the line.

serve

Run the engine as a standalone OpenAI-compatible HTTP server.

glimpse serve --model whisper_large_v3_turbo_q8

Defaults to http://127.0.0.1:11435. Endpoints: GET /v1/models, POST /v1/models/{id}/install, POST /v1/audio/transcriptions.

  • --host / --port, bind address
  • --api-key <KEY>, require an API key on requests
  • --cors, allow browser clients
  • --remote-endpoint <URL>, proxy to an upstream OpenAI-compatible server instead of running locally
  • --remote-api-key / --remote-model, credentials and model for that upstream

serve is the standalone engine, configured entirely by flags. To start the app's built-in local API using your in-app settings and saved keys, use api start instead.

history

Read-only dictation history, straight from the local database. No app, no license.

glimpse history last                       # text of the most recent dictation
glimpse history list --limit 20 --offset 0
glimpse history search "quarterly" --limit 20
glimpse history get <id>
glimpse history stats                       # lifetime words, duration, count

Plain output for list and search is tab-separated id, timestamp, and a one-line preview. With --json each record includes text, raw_text, llm_cleaned, speech_model, llm_model, mode_name, word_count, audio_duration_seconds, audio_path, audio_available, and status.

dictionary

Your custom recognition words. list is headless; add and remove change live app state and launch Glimpse if needed.

glimpse dictionary list
glimpse dictionary add Tauri Raycast ACME
glimpse dictionary remove ACME

remove matches case-insensitively. Both writes return the resulting word list.

replacements

Text replacements applied after transcription (from to to). Same split: list is headless, writes go through the app.

glimpse replacements list
glimpse replacements add --from "btw" --to "by the way"
glimpse replacements remove --from "btw"

add updates an existing entry with the same from (case-insensitive) rather than duplicating it.

model

Pick the active speech model. list is headless; set changes live app state.

glimpse model list
glimpse model list --installed-only
glimpse model set parakeet-v3-int8
glimpse model set remote

list prints one row per model. * marks the active one, then the model key, its state (installed, available, or remote), and a label. set takes a model key from that list, or remote to switch to remote speech.

library

Import files into the Library (async, full pipeline) and read item state back.

glimpse library import ~/Downloads/podcast.mp4 --json
glimpse library import *.mp3 --wait --open
glimpse library status <id>
glimpse library list --limit 20 --status complete
glimpse library export <id> --to srt --output ~/Desktop/podcast.srt

import queues each file through the same pipeline as in-app import and returns immediately with job rows (id, status, name).

Flag Description
--store-original Keep a copy of the source file in library storage
--model <id> Transcribe with a specific model instead of your default
--open Bring up the app on the Library after queuing
--wait Block until each job finishes (polls; times out after 1 hour, exit 4)

status and list are headless reads. list --status filters by state (complete, transcribing, error, …). export writes a completed item's transcript as txt, md, srt, or vtt (--output is required).

open

Bring up the app and navigate. Always launches Glimpse if it's closed.

glimpse open                     # opens the Glimpse window
glimpse open history
glimpse open models
glimpse open --tab general|models|history

There's no dedicated deep-link for the Library yet, so that just brings the app to the front.

status

Report runtime state. Connects only if Glimpse is already running, and never launches it.

glimpse status
glimpse status --json

Reports app_running, the recording pill state, the active_model, and whether the local API is up (host and port in --json). Use it in a Shortcut to avoid kicking off a job while you're mid-dictation.

api

Control the app's built-in local API, the same server you can toggle in Settings, using your saved model, port, key, and CORS settings.

glimpse api status
glimpse api start
glimpse api stop

status reports without launching the app. start and stop route to the app (launching it if needed) and require an active license.

Recipes

You want Command
Finder, Transcribe to a text file glimpse transcribe "$@"
Finder, Transcribe into the Library glimpse library import "$@" --open
Shortcut, Copy last dictation glimpse history last to clipboard
Shortcut, Add a dictionary word glimpse dictionary add "$1"
Raycast, Search history glimpse history search "$1" --limit 20 --json
Raycast, Switch model glimpse model set "$1"
Open Glimpse on history glimpse open history
Guard a Shortcut while recording glimpse status --json, check pill

Cache and data locations

Models (engine cache):

  • Mac: ~/Library/Application Support/com.glimpse.data/models
  • Windows: %APPDATA%\com.glimpse.data\models

Override per-command with --cache-dir, or globally with GLIMPSE_SPEECH_CACHE_DIR.

Databases the headless reads use (under com.glimpse.data):

Resource Path
History and library com.glimpse.data/transcriptions.db
Settings (dictionary, replacements, active model) com.glimpse.data/Glimpse/settings.db
Library media com.glimpse.data/library/

Audio formats

transcribe reads 16 kHz mono PCM WAV directly. Anything else (mp3, m4a, mp4, mov, …) is converted automatically via FFmpeg, so you need ffmpeg on PATH for non-WAV input.

ffmpeg -version          # quick check

If that fails, see FFmpeg Mac or ffmpeg windows. You can also pre-convert:

ffmpeg -i input.mov -ar 16000 -ac 1 -c:a pcm_s16le output.wav

Troubleshooting

  • glimpse: command not found. Run Install CLI from Settings, About, make sure ~/.local/bin is on your PATH, and restart your shell.
  • Exit code 2 or "Glimpse is not running". The command needs the app. Most launch it for you; status and Glimpse-mode transcribe don't, so open Glimpse first.
  • "An active Glimpse license is required". App actions and engine commands need a license. Check Settings, Account. Headless reads don't.
  • Non-WAV audio fails. Confirm ffmpeg -version works.
  • A model "isn't installed". Run glimpse models status <id> to see what's missing, then glimpse models install <id>.

Still stuck? Open an issue with the exact command and its error.

Getting Started

Features

Help

Clone this wiki locally