📓 gemini-notebook-cli

The agent-first Gemini Notebook client for Node.js & TypeScript

Drive Gemini Notebook from your terminal or your code — with a JSON-first CLI purpose-built for LLM agents: structured output, machine-readable errors, and exit codes you can branch on.

⚠️ Unofficial. This talks to Gemini Notebook's internal RPC endpoints, which can change without notice. Not affiliated with or endorsed by Google. Inspired by notebooklm-py. Gemini Notebook was formerly known as NotebookLM.

🤖 Built for AI agents

Most CLIs are written for a human to read. This one is written for an agent to drive. Three design rules make it safe to hand to an LLM:

--json on every data command — parse results, never scrape prose.
Errors are data — a failure prints { "error": { "code", "message" } } to stdout (so a single capture always parses), with details when useful.
Exit codes are a contract — branch on what failed, no string matching:

Exit	Code	Meaning	Agent action
`0`	`OK`	success	use the JSON result
`3`	`AUTH`	session expired/rejected	run `gemini-notebook login`
`4`	`NOT_FOUND`	resource missing	stop / report
`5`	`NOT_READY`	artifact still generating	poll again later
`6`	`RATE_LIMIT`	throttled	back off and retry
`7`	`RPC`	protocol/API drift	surface details
`8`	`NETWORK`	transport/timeout	retry

# An agent driving the CLI — branch on the exit code, parse stdout as JSON.
out=$(gemini-notebook ask "$NB" "Summarize the latest source" --json); code=$?
case $code in
  0) echo "$out" | jq -r '.answer, (.references[] | "  ["+(.citationNumber|tostring)+"] "+.sourceId)' ;;
  3) gemini-notebook login ;;     # AUTH  → refresh session, retry
  6) sleep 30 ;;             # RATE_LIMIT → back off
  *) echo "$out" | jq -r '.error.message' >&2 ;;
esac

Progress goes to stderr, results to stdout — pipe one without the other.

✨ Highlights

🔑 Keychain-free login — sign in through your real browser (cookies are read after you log in; nothing is decrypted off disk) or paste a "Copy as cURL". No OS-keychain prompt, so it works for anyone — not just the machine that made the session. Browser login follows both the legacy Google host and the current Gemini Notebook host.
📚 Grounded chat — answers carry real citations (source id, cited passage, character ranges, relevance score) and support multi-turn conversations via ask --conversation-id.
🎨 Every studio artifact — audio, video (incl. cinematic and short-form), report (briefing / study guide / blog post / custom), quiz, flashcards, infographic, slide deck, data table — generate and download, inspect the stored generation prompt, and retry a failed one.
🏷️ Organize & steer — group a notebook's sources into labels (manual or AI auto-grouping), filter source list by label, and get AI-suggested prompts for what to ask next.
🔬 Research · notes · sharing — web/Drive research discovery + import (with cancel), notes CRUD, and public-link sharing.
🧱 Solid by construction — TypeScript strict mode, undici transport with network-fault classification + retry, and 183 unit tests that pin the position-sensitive wire format against captured fixtures.

🆕 What's new — v0.2.0 Gemini Notebook rebrand

Package renamed to @cola_runner/gemini-notebook-cli, with the gemini-notebook executable and GeminiNotebookClient SDK entry point.
Runtime configuration now uses GEMINI_NOTEBOOK_* and ~/.config/gemini-notebook-cli; this release intentionally provides no legacy aliases or storage migration.
Browser login recognizes the current Gemini Notebook host (notebook.google.com) and no longer waits for the streaming app's load event.
Generate vertical short-form videos with generate video --format short.
Read the original prompt behind any studio artifact with artifact get-prompt.
whoami now derives the account tier from the authoritative quota block rather than Google's promotions endpoint.

🆕 What's new — the 2026-06 product update

Google's June 2026 update turned Gemini Notebook into an agentic researcher: Gemini 3.5 as the default model, chat-driven source discovery, in-notebook code execution, transparent reasoning, and a wider set of export formats (.docx, Excel, PowerPoint, charts, images). These are rolling out to AI Ultra and Workspace business accounts first, then everyone.

Two things follow for this CLI:

gemini-notebook whoami tells you which rollout your account is in — your subscription tier code plus notebook/source quotas. Use it to check whether the new agentic features are live for you yet.
The new server-side capabilities (source discovery, code execution, the new export formats) ride on internal RPC endpoints we haven't reverse-engineered yet. Status: tracking upstream notebooklm-py. Chat already benefits from Gemini 3.5 automatically once it reaches your account — no CLI change needed.

gemini-notebook whoami --json
# { "tier": "GEMINI_NOTEBOOK_TIER_ULTRA", "tierCode": 6, "tierLabel": "Ultra", "notebookLimit": …, "sourceLimit": … }

🚀 Install

npm install -g @cola_runner/gemini-notebook-cli     # global `gemini-notebook` command
# …or run without installing:
npx @cola_runner/gemini-notebook-cli login

The core install is tiny — just commander / undici / tough-cookie, no browser. That's all an agent needs: authenticate headless with gemini-notebook login --paste (paste a "Copy as cURL"/Cookie header), then every other command is pure HTTP.

The one-click browser login is optional and needs Playwright:

npm i -g playwright && playwright install chromium   # only for `gemini-notebook login`

From source (contributors)

git clone https://github.com/cola-runner/gemini-notebook-cli.git && cd gemini-notebook-cli
pnpm install
pnpm build
pnpm playwright install chromium     # one-time, for browser login
npm link                             # puts `gemini-notebook` on your PATH

No build step while hacking? Use pnpm dev <command> to run straight from source.

gemini-notebook login           # browser sign-in (or `login --paste` for headless)
gemini-notebook list            # confirm it worked

🧰 Commands

# Auth
gemini-notebook login                      # browser auto-capture (no keychain)
gemini-notebook login --paste              # or paste a "Copy as cURL" / Cookie header
gemini-notebook status                     # check auth state
gemini-notebook whoami                     # show your subscription tier + quotas

# Notebooks
gemini-notebook list
gemini-notebook create "My research"
gemini-notebook rename <nb> "New title"
gemini-notebook delete <nb>

# Sources
gemini-notebook source add <nb> --url https://en.wikipedia.org/wiki/SpaceX
gemini-notebook source add <nb> --text "..." --title "Notes"
gemini-notebook source add <nb> --file ./paper.pdf --wait   # upload a real PDF/image/docx/audio
gemini-notebook source list <nb>
gemini-notebook source list <nb> --label "Tax docs"          # only sources in a label

# Labels (group a notebook's sources by topic)
gemini-notebook label list <nb>
gemini-notebook label create <nb> "Tax docs" --emoji 📁
gemini-notebook label generate <nb>                          # AI auto-grouping (unlabeled sources)
gemini-notebook label assign <nb> <labelId> <sourceId...>
gemini-notebook label unassign <nb> <labelId> <sourceId...>
gemini-notebook label delete <nb> <labelId...>

# Chat (with citations + follow-ups)
gemini-notebook ask <nb> "What is this about?"
gemini-notebook ask <nb> "And what about that?" --conversation-id <id>
gemini-notebook suggest-prompts <nb>                          # AI-suggested questions to ask

# Notes
gemini-notebook note create <nb> --title "T" --content "..."
gemini-notebook note list <nb>

# Sharing
gemini-notebook share public <nb>          # anyone-with-link; prints the share URL
gemini-notebook share status <nb>

# Research (web/Drive discovery → import)
gemini-notebook research start <nb> "history of the Falcon 9" --wait
gemini-notebook research import <nb> <taskId> --limit 5
gemini-notebook research cancel <nb> <taskId>                 # stop an in-flight run

# Studio artifacts — generate & download
gemini-notebook generate audio <nb> --format deep-dive --wait
gemini-notebook generate video <nb> --format short --wait
gemini-notebook generate report <nb> --format study-guide --wait
gemini-notebook artifact list <nb>
gemini-notebook artifact get-prompt <nb> <artifactId>        # show the original generation prompt
gemini-notebook artifact retry <nb> <artifactId>             # re-run a failed artifact
gemini-notebook download audio <nb> ./overview.mp4
gemini-notebook download slide-deck <nb> ./deck.pdf

Add --json to any of the above for machine-readable output.

🧩 Programmatic API

import { GeminiNotebookClient } from '@cola_runner/gemini-notebook-cli';

const client = await GeminiNotebookClient.fromStorage();

const nb = await client.notebooks.create('Research');
await client.sources.addUrl(nb.id, 'https://en.wikipedia.org/wiki/SpaceX');

const { answer, references } = await client.chat.ask(nb.id, 'Summarize the source.');
console.log(answer);
for (const r of references) console.log(`[${r.citationNumber}] ${r.sourceId} — ${r.citedText}`);

// Generate an audio overview, then block until it's ready.
const { taskId } = await client.artifacts.generateAudio(nb.id);
await client.artifacts.waitForCompletion(nb.id, taskId);

📊 Status

Area	Status
RPC encoder/decoder · auth + cookies · session/transport	✅
`notebooks` — list / create / get / rename / delete	✅
`sources` — add URL/YouTube/file (resumable upload) · list (+ `--label`) · delete · wait	✅
`labels` — create · list · AI auto-grouping · rename · assign/unassign · delete	✅
`chat` — ask · citations · multi-turn · suggest-prompts	✅
`artifacts` — generate (incl. short video) · list · get prompt · poll · download · delete · rename · export · retry	✅
`notes` (CRUD) · `share` (public link) · `research` (web/Drive · cancel)	✅
`whoami` — authoritative tier code + account quotas	✅
Mind maps · per-user share ACLs · save-answer-as-note	⏳ planned
2026-06 agentic update — source discovery · code exec · new exports	⏳ tracking upstream

🙏 Credits

Protocol groundwork and RPC method IDs come from notebooklm-py. This is an independent TypeScript reimplementation with an agent-first CLI.

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
docs/superpowers		docs/superpowers
src		src
tests/unit		tests/unit
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
demo-spacex.sh		demo-spacex.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

📓 gemini-notebook-cli

The agent-first Gemini Notebook client for Node.js & TypeScript

🤖 Built for AI agents

✨ Highlights

🆕 What's new — v0.2.0 Gemini Notebook rebrand

🆕 What's new — the 2026-06 product update

🚀 Install

🧰 Commands

🧩 Programmatic API

📊 Status

🙏 Credits

📄 License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

📓 gemini-notebook-cli

The agent-first Gemini Notebook client for Node.js & TypeScript

🤖 Built for AI agents

✨ Highlights

🆕 What's new — v0.2.0 Gemini Notebook rebrand

🆕 What's new — the 2026-06 product update

🚀 Install

🧰 Commands

🧩 Programmatic API

📊 Status

🙏 Credits

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages