# Config and env

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

Page: https://scribiz.com/docs/cli/config

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.

```json title="~/.scribiz/config.json"
{
  "token": "sbz_live_your_key_here",
  "cookiesBrowser": "chrome"
}
```

| Key | What it is | Set by |
| --- | --- | --- |
| `geminiApiKey` | Your own Gemini key | `scribiz setup` |
| `token` | A Scribiz API key | `scribiz login` |
| `apiBase` | The Scribiz API address | Rarely changed. `login` saves it when `SCRIBIZ_API_URL` points somewhere other than `https://scribiz.com/api` |
| `cookiesBrowser` | The browser whose login to use for links that need one, such as Instagram, when you do not pass `--cookies-from-browser` | You, 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](https://scribiz.com/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

| Variable | What it does |
| --- | --- |
| `SCRIBIZ_API_KEY` | A Scribiz key. Your audio goes to Scribiz, which sends it to Google, and the run uses your account's minutes. Use it in CI and on servers. |
| `GEMINI_API_KEY` | Your 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_API_URL` | The 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_DIR` | Use this folder instead of `~/.scribiz`. Programs that embed the CLI set it. |
| `SCRIBIZ_CACHE` | Use this folder for the cache. Default `~/.scribiz/cache/v1`. |
| `NO_COLOR` | No 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](https://scribiz.com/docs/authentication.md#which-credential-wins).

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.