notebooklm

name	notebooklm
description	Complete API for Google NotebookLM - full programmatic access including features not in the web UI. Create notebooks, add sources, generate all artifact types, download in multiple formats. Activates on explicit /notebooklm or intent like "create a podcast about X"

Phase 0 — EVOLVE

Read evolution.md in this skill's folder (if it exists). Apply accumulated lessons.

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

IMPORTANT: Before using any command, you MUST authenticate:

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

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

Update the CLI:

pip install -U notebooklm-py

Parallel Agents

The CLI stores notebook context in a shared file (~/.notebooklm/context.json). Multiple concurrent agents using notebooklm use can overwrite each other's context.

Solutions for parallel workflows:

1. Always use explicit notebook ID (recommended): Pass -n <notebook_id> (for wait/download commands) or --notebook <notebook_id> (for others) instead of relying on use
2. Per-agent isolation: Set unique NOTEBOOKLM_HOME per agent: export NOTEBOOKLM_HOME=/tmp/agent-$ID
3. Use full UUIDs: Avoid partial IDs in automation (they can become ambiguous)

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

Agent Setup Verification

Before starting workflows, verify the CLI is ready:

1. notebooklm status → Should show "Authenticated as: email@..."
2. notebooklm list --json → Should return valid JSON (even if empty notebooks list)
3. If either fails → Run notebooklm login

When This Skill Activates

Explicit: User says "/notebooklm", "use notebooklm", or mentions the tool by name

Intent detection: Recognize requests like:

• "Create a podcast about [topic]"
• "Summarize these URLs/documents"
• "Generate a quiz from my research"
• "Turn this into an audio overview"
• "Create flashcards for studying"
• "Generate a video explainer"
• "Make an infographic"
• "Create a mind map of the concepts"
• "Download the quiz as markdown"
• "Add these sources to NotebookLM"

Autonomy Rules

Run automatically (no confirmation):

• notebooklm status - check context
• notebooklm auth check - diagnose auth issues
• notebooklm list - list notebooks
• notebooklm source list - list sources
• notebooklm artifact list - list artifacts
• notebooklm language list - list supported languages
• notebooklm language get - get current language
• notebooklm language set - set language (global setting)
• notebooklm artifact wait - wait for artifact completion (in subagent context)
• notebooklm source wait - wait for source processing (in subagent context)
• notebooklm research status - check research status
• notebooklm research wait - wait for research (in subagent context)
• notebooklm use <id> - set context (⚠️ SINGLE-AGENT ONLY - use -n flag in parallel workflows)
• notebooklm create - create notebook
• notebooklm ask "..." - chat queries (without --save-as-note)
• notebooklm history - display conversation history (read-only)
• notebooklm source add - add sources

Ask before running:

• notebooklm delete - destructive
• notebooklm generate * - long-running, may fail
• notebooklm download * - writes to filesystem
• notebooklm artifact wait - long-running (when in main conversation)
• notebooklm source wait - long-running (when in main conversation)
• notebooklm research wait - long-running (when in main conversation)
• notebooklm ask "..." --save-as-note - writes a note
• notebooklm history --save - writes a note

Quick Reference

Task	Command
Authenticate	notebooklm login
Diagnose auth issues	notebooklm auth check
Diagnose auth (full)	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
Delete source by ID	notebooklm source delete <source_id>
Delete source by exact title	notebooklm source delete-by-title "Exact Title"
Wait for source processing	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 (specific sources)	notebooklm ask "question" -s src_id1 -s src_id2
Chat (with references)	notebooklm ask "question" --json
Chat (save answer as note)	notebooklm ask "question" --save-as-note
Chat (save with title)	notebooklm ask "question" --save-as-note --note-title "Title"
Show conversation history	notebooklm history
Save all history as note	notebooklm history --save
Continue specific conversation	notebooklm ask "question" -c <conversation_id>
Save history with title	notebooklm history --save --note-title "My Research"
Get source fulltext	notebooklm source fulltext <source_id>
Get source guide	notebooklm source guide <source_id>
Generate podcast	notebooklm generate audio "instructions"
Generate podcast (JSON)	notebooklm generate audio --json
Generate podcast (specific sources)	notebooklm generate audio -s src_id1 -s src_id2
Generate video	notebooklm generate video "instructions"
Generate report	notebooklm generate report --format briefing-doc
Generate report (append instructions)	notebooklm generate report --format study-guide --append "Target audience: beginners"
Generate quiz	notebooklm generate quiz
Revise a slide	notebooklm generate revise-slide "prompt" --artifact <id> --slide 0
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 slide deck (PDF)	notebooklm download slide-deck ./slides.pdf
Download slide deck (PPTX)	notebooklm download slide-deck ./slides.pptx --format pptx
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 flashcards (markdown)	notebooklm download flashcards --format markdown cards.md
Delete notebook	notebooklm notebook delete <id>
List languages	notebooklm language list
Get language	notebooklm language get
Set language	notebooklm language set zh_Hans

Parallel safety: Use explicit notebook IDs in parallel workflows. Commands supporting -n shorthand: artifact wait, source wait, research wait/status, download *. Download commands also support -a/--artifact. Other commands use --notebook. For chat, use -c <conversation_id> to target a specific conversation.

Partial IDs: Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for ID-based commands such as use, source delete, and wait. For exact source-title deletion, use source delete-by-title "Title". For automation, prefer full UUIDs to avoid ambiguity.

Command Output Formats

Commands with --json return structured data for parsing:

Create notebook:

$ notebooklm create "Research" --json
{"id": "abc123de-...", "title": "Research"}

Add source:

$ notebooklm source add "https://example.com" --json
{"source_id": "def456...", "title": "Example", "status": "processing"}

Generate artifact:

$ notebooklm generate audio "Focus on key points" --json
{"task_id": "xyz789...", "status": "pending"}

Chat with references:

$ notebooklm ask "What is X?" --json
{"answer": "X is... [1] [2]", "conversation_id": "...", "turn_number": 1, "is_follow_up": false, "references": [{"source_id": "abc123...", "citation_number": 1, "cited_text": "Relevant passage from source..."}, {"source_id": "def456...", "citation_number": 2, "cited_text": "Another passage..."}]}

Source fulltext (get indexed content):

$ notebooklm source fulltext <source_id> --json
{"source_id": "...", "title": "...", "char_count": 12345, "content": "Full indexed text..."}

Understanding citations: The cited_text in references is often a snippet or section header, not the full quoted passage. Use SourceFulltext.find_citation_context() in Python to locate citations within the full text.

Extract IDs: Parse the id, source_id, or task_id field from JSON output.

Status values:

• Sources: processing → ready (or error)
• Artifacts: pending or in_progress → completed (or unknown)

Generation Types

All generate commands support:

• -s, --source to use specific source(s) instead of all sources
• --language to set output language (defaults to configured language or 'en')
• --json for machine-readable output (returns task_id and status)
• --retry N to automatically retry on rate limits with exponential backoff

Type	Command	Options	Download
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 / .pptx
Slide Revision	generate revise-slide "prompt" --artifact <id> --slide N	--wait, --notebook	(re-downloads parent deck)
Infographic	generate infographic	--orientation [landscape|portrait|square], --detail [concise|standard|detailed], --style [auto|sketch-note|professional|bento-grid|editorial|instructional|bricks|clay|anime|kawaii|scientific]	.png
Report	generate report	--format [briefing-doc|study-guide|blog-post|custom], --append "extra instructions"	.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 (web UI only shows interactive view)
Mind map extraction	download mind-map	Export hierarchical JSON for visualization tools
Data table export	download data-table	Download structured tables as CSV
Slide deck as PPTX	download slide-deck --format pptx	Download slide deck as editable .pptx (web UI only offers PDF)
Slide revision	generate revise-slide "prompt" --artifact <id> --slide N	Modify individual slides with a natural-language prompt
Report template append	generate report --format study-guide --append "..."	Append custom instructions to built-in format templates without losing the format type
Source fulltext	source fulltext <id>	Retrieve the indexed text content of any source
Save chat to note	ask "..." --save-as-note / history --save	Save Q&A answers or conversation history as notebook notes
Programmatic sharing	share commands	Manage sharing permissions without the UI

Common Workflows

Research to Podcast (Interactive)

Time: 5-10 minutes total

1. notebooklm create "Research: [topic]" — if fails: check auth with notebooklm login
2. notebooklm source add for each URL/document — if one fails: log warning, continue with others
3. Wait for sources: notebooklm source list --json until all status=READY — required before generation
4. notebooklm generate audio "Focus on [specific angle]" (confirm when asked) — if rate limited: wait 5 min, retry once
5. Note the artifact ID returned
6. Check notebooklm artifact list later for status
7. notebooklm download audio ./podcast.mp3 when complete (confirm when asked)

Research to Podcast (Automated with Subagent)

Time: 5-10 minutes, but continues in background

When user wants full automation (generate and download when ready):

1. Create notebook and add sources as usual
2. Wait for sources to be ready (use source wait or check source list --json)
3. Run notebooklm generate audio "..." --json → parse artifact_id from output
4. Spawn a background agent using Task tool:

   Task(
     prompt="Wait for artifact {artifact_id} in notebook {notebook_id} to complete, then download.
             Use: notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
             Then: notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}",
     subagent_type="general-purpose"
   )
   

5. Main conversation continues while agent waits

Error handling in subagent:

• If artifact wait returns exit code 2 (timeout): Report timeout, suggest checking artifact list
• If download fails: Check if artifact status is COMPLETED first

Document Analysis

Time: 1-2 minutes

1. notebooklm create "Analysis: [project]"
2. notebooklm source add ./doc.pdf (or URLs)
3. notebooklm ask "Summarize the key points"
4. notebooklm ask "What are the main arguments?"
5. Continue chatting as needed

Bulk Import with Source Waiting (Subagent Pattern)

When adding multiple sources and needing to wait for processing before chat/generation:

1. Add sources with --json to capture IDs:

   notebooklm source add "https://url1.com" --json  # → {"source_id": "abc..."}
   notebooklm source add "https://url2.com" --json  # → {"source_id": "def..."}
   

2. Spawn a background agent to wait for all sources:

   Task(
     prompt="Wait for sources {source_ids} in notebook {notebook_id} to be ready.
             For each: notebooklm source wait {id} -n {notebook_id} --timeout 120
             Report when all ready or if any fail.",
     subagent_type="general-purpose"
   )
   

3. Main conversation continues while agent waits
4. Once sources are ready, proceed with chat or generation

Why wait for sources? Sources must be indexed before chat or generation. Takes 10-60 seconds per source.

Source limits: Standard: 50, Plus: 100, Pro: 300, Ultra: 600 sources per notebook. Supported types: PDFs, YouTube URLs, web URLs, Google Docs, text files, Markdown, Word docs, audio files, video files, images

Deep Web Research (Subagent Pattern)

Time: 2-5 minutes, runs in background

1. Create notebook: notebooklm create "Research: [topic]"
2. Start deep research (non-blocking):

   notebooklm source add-research "topic query" --mode deep --no-wait
   

3. Spawn a background agent to wait and import:

   Task(
     prompt="Wait for research in notebook {notebook_id} to complete and import sources.
             Use: notebooklm research wait -n {notebook_id} --import-all --timeout 300
             Report how many sources were imported.",
     subagent_type="general-purpose"
   )
   

4. Main conversation continues while agent waits

Alternative (blocking): notebooklm source add-research "topic" --mode deep --import-all

When to use each mode:

• --mode fast: Specific topic, quick overview (5-10 sources, seconds)
• --mode deep: Broad topic, comprehensive analysis (20+ sources, 2-5 min)

Research sources: --from web (default), --from drive (Google Drive)

Output Style

Progress updates: Brief status for each step

• "Creating notebook 'Research: AI'..."
• "Adding source: https://example.com..."
• "Starting audio generation... (task ID: abc123)"

Fire-and-forget for long operations:

• Start generation, return artifact ID immediately
• Do NOT poll or wait in main conversation - generation takes 5-45 minutes (see timing table)
• User checks status manually, OR use subagent with artifact wait

Error Handling

On failure, offer the user a choice:

1. Retry the operation
2. Skip and continue with something else
3. Investigate the error

Error	Cause	Action
Auth/cookie error	Session expired	Run notebooklm auth check then notebooklm login
"No notebook context"	Context not set	Use -n <id> or --notebook <id> flag (parallel), or notebooklm use <id> (single-agent)
"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 pip install -U notebooklm-py

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

Known Limitations

Reliable operations: Notebooks, sources, chat, mind-map, report, data-table generation

May rate-limit: Audio, video, quiz, flashcards, infographic, slide deck generation. Workaround: retry after 5-10 min or use the web UI as fallback.

Processing times — use the subagent pattern for long operations:

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

Polling intervals: When checking status manually, poll every 15-30 seconds.

Language Configuration

Language is a GLOBAL setting affecting all notebooks.

notebooklm language list              # 80+ supported languages
notebooklm language get               # current setting
notebooklm language set zh_Hans       # set globally
notebooklm generate audio --language ja   # per-command override

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

Troubleshooting

notebooklm --help / --version
notebooklm auth check --test           # full auth validation
notebooklm <command> --help            # per-command help