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

bashCopy code
uv tool install notebooklm-py

Authentication (one-time)

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

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

Verify Setup

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

CI/CD and Parallel Agents

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

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

Features Beyond the Web UI

JSON Output Formats

Use --json for machine-readable output:

Create notebook:

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

Add source:

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

Generate artifact:

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

Chat with references:

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

Source list:

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

Artifact list:

jsonCopy code
{
  "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):

   bashCopy code
   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:

   Copy code
   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

Error Handling

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.

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