notebooklm

NotebookLM Automation

Complete programmatic access to Google NotebookLM — including capabilities not exposed in the web UI. Create notebooks, add sources (URLs, YouTube, PDFs, audio, video, images), chat with content, generate all artifact types, and download results in multiple formats.

Prerequisites

Installation

uv tool install notebooklm-py

Authentication (one-time)

notebooklm login          # Opens browser for Google OAuth
notebooklm list           # Verify authentication works

If commands fail with auth errors, re-run notebooklm login.

Verify Setup

notebooklm --version
notebooklm status         # Shows "Authenticated as: email@..."
notebooklm list --json    # Should return valid JSON

CI/CD and Parallel Agents

Variable	Purpose
NOTEBOOKLM_HOME	Custom config directory (default: ~/.notebooklm)
NOTEBOOKLM_AUTH_JSON	Inline auth JSON — no file writes needed

Parallel agents: The CLI stores notebook context in ~/.notebooklm/context.json. Multiple concurrent agents using notebooklm use overwrite each other's context. Use explicit -n <notebook_id> or --notebook <notebook_id> flags instead, or set unique NOTEBOOKLM_HOME per agent.

Quick Reference

Task	Command
Authenticate	notebooklm login
Diagnose auth	notebooklm auth check --test
List notebooks	notebooklm list
Create notebook	notebooklm create "Title"
Set context	notebooklm use <notebook_id>
Show context	notebooklm status
Add URL source	notebooklm source add "https://..."
Add file	notebooklm source add ./file.pdf
Add YouTube	notebooklm source add "https://youtube.com/..."
List sources	notebooklm source list
Wait for source	notebooklm source wait <source_id>
Web research (fast)	notebooklm source add-research "query"
Web research (deep)	notebooklm source add-research "query" --mode deep --no-wait
Check research status	notebooklm research status
Wait for research	notebooklm research wait --import-all
Chat	notebooklm ask "question"
Chat (new conversation)	notebooklm ask "question" --new
Chat (specific sources)	notebooklm ask "question" -s src_id1 -s src_id2
Chat (with references)	notebooklm ask "question" --json
Get source fulltext	notebooklm source fulltext <source_id>
Get source guide	notebooklm source guide <source_id>
Generate podcast	notebooklm generate audio "instructions"
Generate video	notebooklm generate video "instructions"
Generate quiz	notebooklm generate quiz
Generate infographic	notebooklm generate infographic
Generate slide deck	notebooklm generate slide-deck
Generate report	notebooklm generate report
Generate mind map	notebooklm generate mind-map
Generate data table	notebooklm generate data-table "description"
Generate flashcards	notebooklm generate flashcards
Check artifact status	notebooklm artifact list
Wait for completion	notebooklm artifact wait <artifact_id>
Download audio	notebooklm download audio ./output.mp3
Download video	notebooklm download video ./output.mp4
Download report	notebooklm download report ./report.md
Download mind map	notebooklm download mind-map ./map.json
Download data table	notebooklm download data-table ./data.csv
Download quiz	notebooklm download quiz quiz.json
Download quiz (markdown)	notebooklm download quiz --format markdown quiz.md
Download flashcards	notebooklm download flashcards cards.json
Download infographic	notebooklm download infographic ./infographic.png
Download slide deck	notebooklm download slide-deck ./slides.pdf
List languages	notebooklm language list
Set language	notebooklm language set zh_Hans

Partial IDs: Use the first 6+ characters of UUIDs. Must be a unique prefix. Prefer full UUIDs in automation.

Autonomy Rules

Run without confirmation:

• status, auth check, list, source list, artifact list, language list/get/set
• use <id>, create, ask "...", source add
• source wait, artifact wait, research wait/status (in subagent context)

Confirm before running:

• delete — destructive
• generate * — long-running, may fail due to rate limits
• download * — writes to filesystem
• artifact wait, source wait, research wait — long-running (in main conversation)

Generation Types

All generate commands support:

• -s, --source to use specific source(s) instead of all
• --language to override output language
• --json for machine-readable output (returns task_id and status)
• --retry N for automatic retry with exponential backoff

Type	Command	Key Options	Download Format
Podcast	generate audio	--format [deep-dive|brief|critique|debate], --length [short|default|long]	.mp3
Video	generate video	--format [explainer|brief], --style [auto|classic|whiteboard|kawaii|anime|watercolor|retro-print|heritage|paper-craft]	.mp4
Slide Deck	generate slide-deck	--format [detailed|presenter], --length [default|short]	.pdf
Infographic	generate infographic	--orientation [landscape|portrait|square], --detail [concise|standard|detailed]	.png
Report	generate report	--format [briefing-doc|study-guide|blog-post|custom]	.md
Mind Map	generate mind-map	(sync, instant)	.json
Data Table	generate data-table	description required	.csv
Quiz	generate quiz	--difficulty [easy|medium|hard], --quantity [fewer|standard|more]	.json/.md/.html
Flashcards	generate flashcards	--difficulty [easy|medium|hard], --quantity [fewer|standard|more]	.json/.md/.html

Features Beyond the Web UI

Feature	Command	Description
Batch downloads	download <type> --all	Download all artifacts of a type at once
Quiz/Flashcard export	download quiz --format json	Export as JSON, Markdown, or HTML
Mind map extraction	download mind-map	Hierarchical JSON for visualization tools
Data table export	download data-table	Structured tables as CSV
Source fulltext	source fulltext <id>	Retrieve the indexed text content of any source
Programmatic sharing	share commands	Manage sharing permissions without the UI

JSON Output Formats

Use --json for machine-readable output:

Create notebook:

{ "id": "abc123de-...", "title": "Research" }

Add source:

{ "source_id": "def456...", "title": "Example", "status": "processing" }

Generate artifact:

{ "task_id": "xyz789...", "status": "pending" }

Chat with references:

{
  "answer": "X is... [1] [2]",
  "conversation_id": "...",
  "references": [
    {
      "source_id": "abc123...",
      "citation_number": 1,
      "cited_text": "Relevant passage..."
    }
  ]
}

Source list:

{
  "sources": [
    { "id": "...", "title": "...", "status": "ready|processing|error" }
  ]
}

Artifact list:

{
  "artifacts": [
    {
      "id": "...",
      "title": "...",
      "type": "Audio Overview",
      "status": "in_progress|pending|completed|unknown"
    }
  ]
}

Common Workflows

Research to Podcast

1. notebooklm create "Research: [topic]" --json — capture notebook ID
2. notebooklm source add "https://..." --json for each source — capture source IDs
3. notebooklm source list --json — wait until all status=ready
4. notebooklm generate audio "Focus on [angle]" --json — capture artifact ID
5. notebooklm artifact wait <artifact_id> — blocks until complete
6. notebooklm download audio ./podcast.mp3

Document Analysis

1. notebooklm create "Analysis: [project]"
2. notebooklm source add ./doc.pdf
3. notebooklm ask "Summarize the key points"
4. Continue chatting as needed

Bulk Import

1. notebooklm create "Collection: [name]"
2. Add sources (max 50 per notebook):

   notebooklm source add "https://url1.com" --json
   notebooklm source add "https://url2.com" --json
   notebooklm source add ./local-file.pdf --json
   

3. notebooklm source list --json to verify

Supported source types: PDFs, YouTube URLs, web URLs, Google Docs, text files, Markdown, Word docs, audio files, video files, images.

Deep Web Research

1. notebooklm create "Research: [topic]"
2. Start deep research: notebooklm source add-research "topic" --mode deep --no-wait
3. Wait: notebooklm research wait --import-all --timeout 300
4. Sources auto-imported when research completes

Modes: --mode fast (5-10 sources, seconds) vs --mode deep (20+ sources, 2-5 min). Search from: --from web (default) or --from drive (Google Drive).

Subagent Pattern for Long Operations

For non-blocking generation, spawn a background agent:

1. Run notebooklm generate audio "..." --json — parse artifact_id
2. Spawn a Task agent to wait and download:

   Wait for artifact {artifact_id} in notebook {notebook_id} to complete.
   Use: notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
   Then: notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}
   

3. Main conversation continues while agent waits

Processing Times

Operation	Typical Time	Suggested Timeout
Source processing	30s - 10 min	600s
Research (fast)	30s - 2 min	180s
Research (deep)	15 - 30+ min	1800s
Mind map	instant (sync)	n/a
Notes	instant	n/a
Quiz, flashcards	5 - 15 min	900s
Report, data table	5 - 15 min	900s
Audio generation	10 - 20 min	1200s
Video generation	15 - 45 min	2700s

Error Handling

Error	Cause	Action
Auth/cookie error	Session expired	notebooklm auth check then notebooklm login
"No notebook context"	Context not set	Use -n <id> flag or notebooklm use <id>
"No result found for RPC ID"	Rate limiting	Wait 5-10 min, retry
GENERATION_FAILED	Google rate limit	Wait and retry later
Download fails	Generation incomplete	Check artifact list for status
Invalid notebook/source ID	Wrong ID	Run notebooklm list to verify
RPC protocol error	Google changed APIs	May need CLI update (uv tool upgrade notebooklm-py)

Exit codes: 0 = success, 1 = error, 2 = timeout (wait commands only).

Reliable operations: Notebooks, sources, chat, mind map, report, data table. May hit rate limits: Audio, video, quiz, flashcards, infographic, slide deck.

Language Configuration

Language is a global setting affecting all notebooks.

notebooklm language list              # 80+ supported languages
notebooklm language get               # Current setting
notebooklm language set ja            # Set globally
notebooklm generate audio --language ja  # Override per command

Common codes: en, zh_Hans, zh_Hant, ja, ko, es, fr, de, pt_BR.

Limitations

• Unofficial API: Uses browser automation via notebooklm-py. May break if Google changes NotebookLM internals. Not affiliated with Google.
• 50 sources per notebook: Hard limit from NotebookLM.
• Rate limiting: Generation endpoints are rate-limited by Google. No workaround beyond waiting.
• Auth expiry: Google OAuth sessions expire. Re-run notebooklm login when auth fails.
• No streaming: Chat responses are returned in full, not streamed.
• Single-agent context: notebooklm use writes to a shared file. Use -n flags for parallel workflows.