Config and env

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.

{  "token": "sbz_live_your_key_here",  "cookiesBrowser": "chrome"}

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

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 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:

~/.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.