Install the 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.

npm install -g scribiz     # then: scribiz --helpnpx 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.

Tools it needs

It calls programs you install yourself.

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.

brew install ffmpeg yt-dlp

sudo apt install ffmpegpipx install yt-dlp

winget install Gyan.FFmpegwinget 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.

scribiz login      # a free Scribiz accountscribiz setup      # or: your own Gemini API key

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

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.

$ scribiz login┌  scribiz login│●  Open https://scribiz.com/login/device?user_code=ABCD1234│  and confirm the code ABCD1234Waiting for you to approve in the browser (Ctrl+C to cancel)...│◆  Signed in as [email protected] (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:

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

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

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, 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.

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

scribiz talk.mp4 > talk.srtscribiz "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.

Check your setup

scribiz doctor

$ scribiz doctorscribiz 0.1.1 · engine 0.1.0 · node 24.21.0 · darwin arm64Credential  ✓ Scribiz key (https://scribiz.com/api) sbz_live_…Q7xK from config · accepted, 120 msTools  ✓ 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/denoConfig  /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.

Where things live

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 covers everything you can change.

Next

• Commands
• Flags
• Recipes
• Use it as a local MCP server