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 or --notebook 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 | | 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 | | 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 | | Get source guide | notebooklm source guide | | 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 | | 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 , 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 --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 | 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 — 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):

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

1. 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} ``

1. 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 flag or notebooklm use | | "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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mathews-Tom
• Source: Mathews-Tom/armory
• License: MIT
• Homepage: https://mathews-tom.github.io/armory/

Install and usage instructions live in the source repository linked above.