# Install the CLI > Install the scribiz command with npm, sign in to a free account or add your own Gemini key, check it with scribiz doctor, and find its files. Page: https://scribiz.com/docs/cli The CLI is the whole engine in one command. It runs on your machine and fetches links from your own connection. You run it with a free Scribiz account (`scribiz login`) or with your own Gemini API key (`scribiz setup`). It is on npm as `scribiz`. ```bash npm install -g scribiz # then: scribiz --help npx scribiz --help # or run it without installing ``` It needs Node.js 24 or newer and `ffmpeg`. A link also needs `yt-dlp`. Both are listed below. > [!NOTE] > Tested on macOS only. Linux and Windows have not been tried yet. The install lines below for those systems install the tools, but the CLI itself has not been run there. ## Tools it needs It calls programs you install yourself. | Tool | Needed for | | --- | --- | | `ffmpeg` and `ffprobe` | Reading local files and cutting audio | | `yt-dlp` | Reading links: titles, captions and media from YouTube, TikTok, Instagram and others | | A JavaScript runtime | `yt-dlp` needs Deno, Node or Bun to read YouTube. Scribiz finds one for it. | A file needs `ffmpeg`. A link needs `yt-dlp`, with one exception: without it, or with one that cannot start, a public YouTube link is still read through Gemini, with approximate timing. If you only run files, you can skip `yt-dlp`. ```bash tab="macOS" brew install ffmpeg yt-dlp ``` ```bash tab="Debian and Ubuntu" sudo apt install ffmpeg pipx install yt-dlp ``` ```bash tab="Windows" winget install Gyan.FFmpeg winget install yt-dlp.yt-dlp ``` Keep `yt-dlp` current. Sites change often and an old version is the most common reason a link stops working. On Debian and Ubuntu the `apt` package of `yt-dlp` is often too old, so use `pipx`. Scribiz looks for each tool on your `PATH` and then in `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.bun/bin` and `~/.deno/bin`, so a program that starts it with a short `PATH` still finds them. ## The first run There are two ways to start. Pick one. ```bash scribiz login # a free Scribiz account scribiz setup # or: your own Gemini API key ``` | | `scribiz login` | `scribiz setup` | | --- | --- | --- | | What you need | A Scribiz account (an email link, no password) | A Gemini key from [Google AI Studio](https://aistudio.google.com/apikey) | | Where the audio goes | From your machine to Scribiz, which sends it to Google | From your machine straight to Google, with your key | | What it costs | Your account's minutes: 30 a month on the free plan | Google bills the key. No Scribiz minutes are used | | When it runs out | The CLI says when your minutes come back | Google's quota for your key applies | | What is saved | A Scribiz key in `~/.scribiz/config.json` | Your Gemini key in `~/.scribiz/config.json` | Command-line sign-in came with version 0.1.1. Run `scribiz --version` to check which one you have. ### Sign in to a free account ```bash scribiz login ``` `login` shows a code and a link. In a terminal it also opens the link in your browser. Confirm the code at `https://scribiz.com/login/device` while you are signed in to Scribiz. If you are not, the page asks you to sign in first and keeps the code. The code expires after 10 minutes. ```console $ scribiz login ┌ scribiz login │ ● Open https://scribiz.com/login/device?user_code=ABCD1234 │ and confirm the code ABCD1234 Waiting for you to approve in the browser (Ctrl+C to cancel)... │ ◆ Signed in as you@example.com (free plan). Key sbz_live_…Q7xK saved to /Users/you/.scribiz/config.json │ ● Runs with this sign-in send your audio to Scribiz, which sends it to Google. `scribiz whoami` shows your minutes. │ └ Try: scribiz "https://www.youtube.com/watch?v=jNQXAC9IVRw" ``` The CLI saves a Scribiz key to `~/.scribiz/config.json`, readable by you only. It is a key like any other: it appears in the dashboard under API keys as `CLI on` and the name of your machine, and you can revoke it there. An account can hold up to 10 keys. A free account has 30 minutes a month. `scribiz whoami` shows your plan and the minutes you have left. On a server, over SSH or in CI, where nobody can open a browser, create a key in the dashboard and set `SCRIBIZ_API_KEY`, or run `scribiz login --key` and paste it. `scribiz login --no-browser` prints the link without opening it. When your minutes are used up, the CLI stops with exit code 3 and says when they come back: ```text You are out of minutes for this period. Your minutes come back on 2026-11-01 (UTC). Your own Gemini key is the other way: run `scribiz setup`. ``` The date is the start of your next monthly period. The CLI does not offer a way to add minutes. ### Use your own Gemini key ```bash scribiz setup ``` `setup` asks for your Gemini API key, checks it with Google, and saves it to `~/.scribiz/config.json`, readable by you only. Get a key at [Google AI Studio](https://aistudio.google.com/apikey). Without a terminal, pipe it in: `echo "$KEY" | scribiz setup`. `setup` refuses a key that starts with `sbz_` before it contacts Google, and points you to `scribiz login --key`. Or set `GEMINI_API_KEY` in the environment. See [Authentication](https://scribiz.com/docs/authentication.md#use-your-own-gemini-key). Your key is sent to Google and nowhere else. What leaves your machine: the audio, cut into short chunks, goes to Google with your key. With `--visual`, a low-resolution copy of the video made on your machine goes too. The whole video is never uploaded. For a public YouTube link that is read through Gemini, only the link goes to Google, and Google reads the video from YouTube. Google's rules for your key apply, so read [Google's Gemini API terms](https://ai.google.dev/gemini-api/terms), in particular what they say about free-tier keys. ### One credential at a time `login` and `setup` replace each other: the file holds one credential, and the newer one wins. In the environment, `SCRIBIZ_API_KEY` is used before `GEMINI_API_KEY`, and both before what the file holds. So a `GEMINI_API_KEY` that is still exported keeps a run on your own key after you sign in, and `scribiz whoami` says so. See [Which credential wins](https://scribiz.com/docs/authentication.md#which-credential-wins). `scribiz logout` removes the saved sign-in and the saved Gemini key from the file. It does not revoke the Scribiz key: the key keeps working until you revoke it in the [dashboard](https://scribiz.com/dashboard). A key in your environment is not touched. ### With no credential at all In a terminal, the first run asks how you want to run it: sign in to Scribiz, or use your own Gemini API key. It saves your choice and carries on with your request. With `--json`, `--no-input` or no terminal, it never asks: it stops with the error `AUTH` and exit code 3. If an old `~/.transcribe/config.json` from the previous `transcribe` CLI exists, the first run says once that its OpenAI and OpenRouter keys are not used. ## Your first command ```bash scribiz talk.mp4 > talk.srt scribiz "https://www.youtube.com/watch?v=jNQXAC9IVRw" -f context ``` Put a link that has a `?` in quotes: zsh reads the `?` as a wildcard and stops with `no matches found`. An empty argument is an error, never the current folder. To run a folder, write `scribiz .`. See [Commands](https://scribiz.com/docs/cli/commands.md). ## Check your setup ```bash scribiz doctor ``` ```console $ scribiz doctor scribiz 0.1.1 · engine 0.1.0 · node 24.21.0 · darwin arm64 Credential ✓ Scribiz key (https://scribiz.com/api) sbz_live_…Q7xK from config · accepted, 120 ms Tools ✓ ffmpeg 9.0.2 /opt/homebrew/bin/ffmpeg ✓ ffprobe 9.0.2 /opt/homebrew/bin/ffprobe ✓ yt-dlp 2026.08.19 /opt/homebrew/bin/yt-dlp ✓ js runtime 2.9.7 /opt/homebrew/bin/deno Config /Users/you/.scribiz/config.json (mode 600) ``` `doctor` reports which credential it found and whether Scribiz or Google accepts it (it says "your Gemini key" when the credential is your own), the versions of `ffmpeg`, `ffprobe` and `yt-dlp`, the JavaScript runtime `yt-dlp` will use, and the config file. `ffmpeg` and `ffprobe` are required. `yt-dlp` and the runtime are optional, so a missing one shows a dash instead of a cross, with a note on what you lose. A `yt-dlp` that is installed but cannot start is reported as one that does not run, with the reason and the fix. A missing tool is reported with a hint for your system. If `doctor` shows no problems, a run will start. It exits 0 when everything is fine, 3 when the credential is missing or rejected, 6 when `ffmpeg` or `ffprobe` is missing, and 1 for anything else. `scribiz doctor --json` prints the same report as a protocol message. See [The JSON protocol](https://scribiz.com/docs/cli/json-protocol.md). ## Where things live | Path | What | | --- | --- | | `~/.scribiz/config.json` | Your saved sign-in or Gemini key, and settings. Readable by you only. | | `~/.scribiz/cache/v1` | Transcripts and summaries as text, so a second run on the same video costs nothing. `--no-cache` turns it off. | Scribiz writes temporary files to a private run folder under your system's temp directory, never next to your files, and deletes it when the run ends. [Config and env](https://scribiz.com/docs/cli/config.md) covers everything you can change. ## Next - [Commands](https://scribiz.com/docs/cli/commands.md) - [Flags](https://scribiz.com/docs/cli/flags.md) - [Recipes](https://scribiz.com/docs/cli/recipes.md) - [Use it as a local MCP server](https://scribiz.com/docs/mcp/connection-modes.md#local) --- Checked against the Scribiz build on 2026-10-05.