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.

Installation

From PyPI (Recommended):

pip install notebooklm-py

From GitHub (use latest release tag, NOT main branch):

# Get the latest release tag (using curl)
LATEST_TAG=$(curl -s https://api.github.com/repos/teng-lin/notebooklm-py/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
pip install "git+https://github.com/teng-lin/notebooklm-py@${LATEST_TAG}"

⚠️ DO NOT install from main branch (

pip install git+https://github.com/teng-lin/notebooklm-py

Skill install methods:

• notebooklm skill install

  installs this skill into the supported local agent directories managed by the CLI.

• npx skills add teng-lin/notebooklm-py

  installs this skill from the GitHub repository into compatible agent skill directories.
• If you are already reading this file inside an agent skill directory, the skill is already installed. You only need the Python package and authentication below.

CLI-managed install:

notebooklm skill install

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

CI/CD, Multiple Accounts, and Parallel Agents

For automated environments, multiple accounts, or parallel agent workflows:

NOTEBOOKLM_HOME

~/.notebooklm

NOTEBOOKLM_PROFILE

default

NOTEBOOKLM_AUTH_JSON

CI/CD setup: Set

NOTEBOOKLM_AUTH_JSON

storage_state.json

Multiple accounts: Use named profiles (

notebooklm profile create work

notebooklm -p work login

NOTEBOOKLM_HOME

Parallel agents: The CLI stores notebook context in a shared file (

~/.notebooklm/context.json

notebooklm use

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 via profiles:

   export NOTEBOOKLM_PROFILE=agent-$ID

   (each profile gets its own context file)
3. Per-agent isolation via home: Set unique

   NOTEBOOKLM_HOME

   per agent:

   export NOTEBOOKLM_HOME=/tmp/agent-$ID

4. Use full UUIDs: Avoid partial IDs in automation (they can become ambiguous)

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

• notebooklm profile list

  - list profiles

• notebooklm profile create

  - create profile

• notebooklm profile switch

  - switch active profile

• notebooklm doctor

  - check environment health

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

notebooklm login

notebooklm auth check

notebooklm auth check --test

notebooklm list

notebooklm create "Title"

notebooklm use <notebook_id>

notebooklm status

notebooklm source add "https://..."

notebooklm source add ./file.pdf

notebooklm source add "https://youtube.com/..."

notebooklm source list

notebooklm source delete <source_id>

notebooklm source delete-by-title "Exact Title"

notebooklm source wait <source_id>

notebooklm source add-research "query"

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

notebooklm research status

notebooklm research wait --import-all

notebooklm ask "question"

notebooklm ask "question" -s src_id1 -s src_id2

notebooklm ask "question" --json

notebooklm ask "question" --save-as-note

notebooklm ask "question" --save-as-note --note-title "Title"

notebooklm history

notebooklm history --save

notebooklm ask "question" -c <conversation_id>

notebooklm history --save --note-title "My Research"

notebooklm source fulltext <source_id>

notebooklm source guide <source_id>

notebooklm generate audio "instructions"

notebooklm generate audio --json

notebooklm generate audio -s src_id1 -s src_id2

notebooklm generate video "instructions"

notebooklm generate report --format briefing-doc

notebooklm generate report --format study-guide --append "Target audience: beginners"

notebooklm generate quiz

notebooklm generate revise-slide "prompt" --artifact <id> --slide 0

notebooklm artifact list

notebooklm artifact wait <artifact_id>

notebooklm download audio ./output.mp3

notebooklm download video ./output.mp4

notebooklm download slide-deck ./slides.pdf

notebooklm download slide-deck ./slides.pptx --format pptx

notebooklm download report ./report.md

notebooklm download mind-map ./map.json

notebooklm download data-table ./data.csv

notebooklm download quiz quiz.json

notebooklm download quiz --format markdown quiz.md

notebooklm download flashcards cards.json

notebooklm download flashcards --format markdown cards.md

notebooklm notebook delete <id>

notebooklm language list

notebooklm language get

notebooklm language set zh_Hans

notebooklm profile list

notebooklm profile create work

notebooklm profile switch work

notebooklm profile delete old

notebooklm profile rename old new

notebooklm -p work list

notebooklm doctor

notebooklm doctor --fix

Parallel safety: Use explicit notebook IDs in parallel workflows. Commands supporting

-n

artifact wait

source wait

research wait/status

download *

-a/--artifact

--notebook

-c <conversation_id>

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

wait

source delete-by-title "Title"

Command Output Formats

Commands with

--json

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

start_char

end_char

SourceFulltext.find_citation_context()

fulltext = await client.sources.get_fulltext(notebook_id, ref.source_id)
matches = fulltext.find_citation_context(ref.cited_text)  # Returns list[(context, position)]
if matches:
    context, pos = matches[0]  # First match; check len(matches) > 1 for duplicates

Extract IDs: Parse the

id

source_id

task_id

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

generate audio

--format [deep-dive|brief|critique|debate]

--length [short|default|long]

generate video

--format [explainer|brief]

--style [auto|classic|whiteboard|kawaii|anime|watercolor|retro-print|heritage|paper-craft]

generate slide-deck

--format [detailed|presenter]

--length [default|short]

generate revise-slide "prompt" --artifact <id> --slide N

--wait

--notebook

generate infographic

--orientation [landscape|portrait|square]

--detail [concise|standard|detailed]

--style [auto|sketch-note|professional|bento-grid|editorial|instructional|bricks|clay|anime|kawaii|scientific]

generate report

--format [briefing-doc|study-guide|blog-post|custom]

--append "extra instructions"

generate mind-map

generate data-table

generate quiz

--difficulty [easy|medium|hard]

--quantity [fewer|standard|more]

generate flashcards

--difficulty [easy|medium|hard]

--quantity [fewer|standard|more]

Features Beyond the Web UI

These capabilities are available via CLI but not in NotebookLM's web interface:

download <type> --all

download quiz --format json

download mind-map

download data-table

download slide-deck --format pptx

generate revise-slide "prompt" --artifact <id> --slide N

generate report --format study-guide --append "..."

source fulltext <id>

ask "..." --save-as-note

history --save

share

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

Benefits: Non-blocking, user can do other work, automatic download on completion

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

Time: Varies by source count

1. notebooklm create "Collection: [name]"

2. Add multiple sources:

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

3. notebooklm source list

   to verify

Source limits: Varies by plan—Standard: 50, Plus: 100, Pro: 300, Ultra: 600 sources per notebook. See NotebookLM plans for details. The CLI does not enforce these limits; they are applied by your NotebookLM account. Supported types: PDFs, YouTube URLs, web URLs, Google Docs, text files, Markdown, Word docs, audio files, video files, images

Bulk Import with Source Waiting (Subagent Pattern)

Time: Varies by source count

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.

Deep Web Research (Subagent Pattern)

Time: 2-5 minutes, runs in background

Deep research finds and analyzes web sources on a topic:

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
5. When agent completes, sources are imported automatically

Alternative (blocking): For simple cases, omit

--no-wait

notebooklm source add-research "topic" --mode deep --import-all
# Blocks for up to 5 minutes

When to use each mode:

• --mode fast

  : Specific topic, quick overview needed (5-10 sources, seconds)

• --mode deep

  : Broad topic, comprehensive analysis needed (20+ sources, 2-5 min)

Research sources:

• --from web

  : Search the web (default)

• --from drive

  : Search 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

JSON output: Use

--json

notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json

JSON schemas (key fields):

notebooklm list --json

{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}

notebooklm auth check --json

{"checks": {"storage_exists": true, "json_valid": true, "cookies_present": true, "sid_cookie": true, "token_fetch": true}, "details": {"storage_path": "...", "auth_source": "file", "cookies_found": ["SID", "HSID", "..."], "cookie_domains": [".google.com"]}}

notebooklm source list --json

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

notebooklm artifact list --json

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

Status values:

• Sources:

  processing

  →

  ready

  (or

  error

  )
• Artifacts:

  pending

  or

  in_progress

  →

  completed

  (or

  unknown

  )

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 decision tree:

notebooklm auth check

notebooklm login

-n <id>

--notebook <id>

notebooklm use <id>

GENERATION_FAILED

artifact list

notebooklm list

Exit Codes

All commands use consistent exit codes:

Examples:

• source wait

  returns 1 if source not found or processing failed

• artifact wait

  returns 2 if timeout reached before completion

• generate

  returns 1 if rate limited (check stderr for details)

Known Limitations

Rate limiting: Audio, video, quiz, flashcards, infographic, and slide deck generation may fail due to Google's rate limits. This is an API limitation, not a bug.

Reliable operations: These always work:

• Notebooks (list, create, delete, rename)
• Sources (add, list, delete)
• Chat/queries
• Mind-map, study-guide, report, data-table generation

Unreliable operations: These may fail with rate limiting:

• Audio (podcast) generation
• Video generation
• Quiz and flashcard generation
• Infographic and slide deck generation

Workaround: If generation fails:

1. Check status:

   notebooklm artifact list

2. Retry after 5-10 minutes
3. Use the NotebookLM web UI as fallback

Processing times vary significantly. Use the subagent pattern for long operations:

Polling intervals: When checking status manually, poll every 15-30 seconds to avoid excessive API calls.

Language Configuration

Language setting controls the output language for generated artifacts (audio, video, etc.).

Important: Language is a GLOBAL setting that affects all notebooks in your account.

# List all 80+ supported languages with native names
notebooklm language list

# Show current language setting
notebooklm language get

# Set language for artifact generation
notebooklm language set zh_Hans  # Simplified Chinese
notebooklm language set ja       # Japanese
notebooklm language set en       # English (default)

Common language codes:

en

zh_Hans

zh_Hant

ja

ko

es

fr

de

pt_BR

Override per command: Use

--language

notebooklm generate audio --language ja   # Japanese podcast
notebooklm generate video --language zh_Hans  # Chinese video

Offline mode: Use

--local

notebooklm language set zh_Hans --local  # Save locally only
notebooklm language get --local  # Read local config only

Troubleshooting

notebooklm --help              # Main commands
notebooklm auth check          # Diagnose auth issues
notebooklm auth check --test   # Full auth validation with network test
notebooklm notebook --help     # Notebook management
notebooklm source --help       # Source management
notebooklm research --help     # Research status/wait
notebooklm generate --help     # Content generation
notebooklm artifact --help     # Artifact management
notebooklm download --help     # Download content
notebooklm language --help     # Language settings

Diagnose auth:

notebooklm auth check

notebooklm login

notebooklm --version

notebooklm skill install