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

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:

{ "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

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.

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.