Skip to content
Scribiz
Get transcript

CLI

Config and env

The config file, the environment variables, the cache, and which setting wins.

View Markdown

Scribiz needs almost no configuration. This page lists what exists, so you know what you can change and what wins when two settings disagree.

The config file

~/.scribiz/config.json is created the first time you sign in with scribiz login or add a key with scribiz setup. The folder is mode 0700 and the file is mode 0600, so only you can read them. scribiz doctor shows its path and whether it exists.

~/.scribiz/config.json
{  "token": "sbz_live_your_key_here",  "cookiesBrowser": "chrome"}
KeyWhat it isSet by
geminiApiKeyYour own Gemini keyscribiz setup
tokenA Scribiz API keyscribiz login
speechThe speech model every run usesscribiz models use
openrouterApiKeyYour own OpenRouter key, for an openrouter:<model> speech modelscribiz models key
apiBaseThe Scribiz API addressRarely changed. login saves it when SCRIBIZ_API_URL points somewhere other than https://scribiz.com/api
cookiesBrowserThe browser whose login to use for links that need one, such as Instagram, when you do not pass --cookies-from-browserYou, by editing the file

The file holds one credential. scribiz login saves token and removes geminiApiKey. scribiz setup saves geminiApiKey and removes token. scribiz logout removes both, on this machine only: it does not revoke the Scribiz key, which you do in the dashboard. Unknown keys are dropped the next time the CLI saves the file. You can edit it by hand. Keep the permissions at 0600.

Environment variables

VariableWhat it does
SCRIBIZ_API_KEYA Scribiz key. Your audio goes to Scribiz, which has it read by its speech model (ElevenLabs through OpenRouter) or by Google, and the run uses your account's minutes. Use it in CI and on servers.
GEMINI_API_KEYYour own Gemini key. The CLI then calls Google directly and uses no Scribiz minutes. It wins over a sign-in saved by scribiz login, and scribiz whoami says so.
SCRIBIZ_SPEECHThe speech model, as --speech takes it. The flag wins over it, and it wins over the saved choice.
OPENROUTER_API_KEYYour own OpenRouter key. Only read when the speech model is an openrouter:<model>; the audio then goes from your computer to OpenRouter.
SCRIBIZ_TRANSCRIBE_CLIThe transcribe-cli of transcribe.cpp that runs the local models (Parakeet, Whisper turbo), when it is not next to scribiz, on the PATH or in Homebrew's folder.
SCRIBIZ_WHISPER_CLIThe whisper-cli of whisper.cpp, only for the earlier local models (local:base, local:small, local:turbo).
SCRIBIZ_API_URLThe Scribiz API address. Default https://scribiz.com/api. For an API on your own machine, a bare address such as http://localhost:8787 works too.
SCRIBIZ_CONFIG_DIRUse this folder instead of ~/.scribiz. Programs that embed the CLI set it.
SCRIBIZ_CACHEUse this folder for the cache. Default ~/.scribiz/cache/v1.
NO_COLORNo color in the output.

Prefer the environment over flags for secrets. A key in an argument is visible to every process on the machine, which is why no flag takes a key.

The CLI does not read a .env file itself. Export the variable in your shell, or save a credential with scribiz login or scribiz setup.

Which setting wins

For credentials, the first match in this list is used:

  1. SCRIBIZ_API_KEY
  2. GEMINI_API_KEY
  3. token in the config file
  4. geminiApiKey in the config file

Environment variables beat the config file, so a GEMINI_API_KEY that is still exported keeps a run on your own key after you sign in. --no-config skips the file, and then only the environment counts. scribiz whoami shows which credential a run will use and where it came from. More in Authentication.

For the speech model: --speech, then SCRIBIZ_SPEECH, then speech in the file, then the default for the credential: scribiz when signed in, gemini with your own Gemini key. Local models are kept in a models folder next to the config file.

For the API address: SCRIBIZ_API_URL, then apiBase in the file, then https://scribiz.com/api.

The cache

The CLI keeps text results so a second run on the same video is instant and costs nothing:

Text
~/.scribiz/cache/v1/  youtube/jNQXAC9IVRw/    meta.json    captions.en.manual.json    transcript.captions-manual.platform.ad7dd68faa.json    synthesis.gemini-3.8-flash.full.4df1654294da2efe.json  local/8ee9f0a250ac5a75f42640c01fdbfc97/    meta.json    transcript.asr.gemini-3.5-transcribe.3ac57d80ae.json    visual.gemini-3.5-flash-lite.2.1.json    synthesis.gemini-3.8-flash.full.d2e49c9cbd96e564.json
  • Entries are keyed by the video's own id from yt-dlp, not by the URL, so every link form of the same video shares one entry.
  • A local file is keyed by a hash of its size, its modification time and its first and last megabyte.
  • meta.json (the title, channel and caption list of a link) is refreshed after 24 hours.
  • Media is never cached.
  • The cache is capped at 2 GiB. The least recently used entries go first.
  • A cached transcript made with speakers and word times also satisfies a request that needs less. A captions result never satisfies a request for speakers.

--no-cache ignores the cache for one run: it neither reads nor writes it. --force recomputes everything and still saves the result. Delete the folder to clear the cache.

Temporary files

Each run works in a private folder under scribiz/ in your system's temp directory. It is never next to your media. The CLI deletes it when the run ends, and removes folders left behind by a crashed run once they are 24 hours old.

If you used the old transcribe CLI

An ~/.transcribe/config.json with OpenAI or OpenRouter keys is ignored. Scribiz does not use those keys. The first run tells you so once. scribiz is a separate program from @illyism/transcribe.

Checked against the Scribiz build on 2026-10-05.

Loading the index