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.

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). The main branch may contain unreleased/unstable changes. Always use PyPI or a specific release tag, unless you are testing unreleased features.

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:

CI/CD setup: Set NOTEBOOKLM_AUTH_JSON from a secret containing your storage_state.json contents.

Multiple accounts: Use named profiles (notebooklm profile create work, then notebooklm -p work login). Alternatively, use different NOTEBOOKLM_HOME directories per account.

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

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. The start_char/end_char positions reference NotebookLM's internal chunked index, not the raw fulltext. Use SourceFulltext.find_citation_context() to locate citations:

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, or task_id field from JSON output.

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

Features Beyond the Web UI

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

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 flag for machine-readable output:

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:

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:

Override per command: Use --language flag on generate commands:

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

Offline mode: Use --local flag to skip server sync:

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 - shows cookie domains, storage path, validation status Re-authenticate: notebooklm login Check version: notebooklm --version Refresh a CLI-managed install: notebooklm skill install

Description

A clear description of the bug.

Steps to Reproduce

1. ... 2. ... 3. ...

Expected Behavior

What you expected to happen.

Actual Behavior

What actually happened. Include the full error message or traceback if applicable.

Paste error output here

Environment

• OS: (e.g., macOS 15, Ubuntu 24.04, Windows 11)
• Python version: (e.g., 3.12)
• notebooklm-py version: (run notebooklm --version)
• Install method: (pip, uv, pipx)

Debug Output

If applicable, run the failing command with -vv for verbose logging and paste the relevant output:

notebooklm -vv <your-command-here>

Checklist

• [ ] I verified this bug exists on the latest version of notebooklm-py
• [ ] I searched existing issues and this is not a duplicate

Use Case

Describe the problem or workflow this feature would address.

Proposed Solution

How you'd like this to work (CLI usage, API example, etc.).

Alternatives Considered

Any alternative approaches you've thought of.

Summary

Brief description of the changes.

Related Issue

Closes #<issue_number>

Changes

• ...

Test Plan

• [ ] I tested these changes locally
• [ ] Tests pass (pytest)
• [ ] Linting passes (ruff check src/ tests/)
• [ ] Formatting passes (ruff format --check src/ tests/)
• [ ] Type checking passes (mypy src/notebooklm --ignore-missing-imports)

Notes

Any additional context, trade-offs, or design decisions.

Repository Guidelines

Status: Active Last Updated: 2026-03-13

Project Structure & Module Organization

src/notebooklm/ contains the async client and typed APIs. Internal feature modules use _ prefixes such as _sources.py and _artifacts.py; src/notebooklm/cli/ holds Click commands, and src/notebooklm/rpc/ handles protocol encoding and decoding. Tests are split by scope: tests/unit/, tests/integration/, and tests/e2e/. Recorded HTTP fixtures live in tests/cassettes/. Examples are in docs/examples/, and diagnostics live in scripts/.

Build, Test, and Development Commands

Use uv for local work:

uv sync --extra dev --extra browser
uv run pytest
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/notebooklm
uv run pre-commit run --all-files

Run uv run pytest tests/e2e -m readonly only after notebooklm login and setting test notebook env vars.

Coding Style & Naming Conventions

Target Python 3.10+, 4-space indentation, and double quotes. Ruff enforces formatting and import order with a 100-character line length. Keep module and test file names in snake_case; prefer descriptive Click command names that match existing groups such as source, artifact, and research. Preserve the internal/public split: _*.py for implementation, exported types in src/notebooklm/__init__.py.

Testing Guidelines

Put pure logic in tests/unit/, VCR-backed flows in tests/integration/, and authenticated NotebookLM coverage in tests/e2e/. Name tests test_<behavior>.py and record cassettes with NOTEBOOKLM_VCR_RECORD=1 uv run pytest tests/integration/test_vcr_*.py -v. Coverage is expected to stay at or above the configured 90% threshold.

Commit, PR, and Agent Notes

Follow the existing commit style: feat(cli): ..., fix(cli): ..., refactor(test): ..., style: .... PRs should include a short summary, linked issue when relevant, and the commands run locally. For Codex or other parallel agents, prefer --json, pass explicit notebook IDs instead of relying on notebooklm use, and isolate runs with NOTEBOOKLM_HOME=/tmp/<agent-id> when multiple agents share one machine.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• Auto-refresh on auth expiry - fetch_tokens now optionally runs a user-provided refresh command when a Google session cookie has expired, reloads cookies from storage, and retries once. Opt in by setting the NOTEBOOKLM_REFRESH_CMD environment variable to a script that rewrites ~/.notebooklm/storage_state.json (e.g. a sync script reading from a cookie vault). Covers every CLI entry point without changing the public API. A process-scoped flag prevents retry loops.

[0.3.4] - 2026-03-12

Added

• Notebook metadata export - Added notebook metadata APIs and CLI export with a simplified sources list
• New notebooklm metadata command with human-readable and --json output
• New NotebookMetadata and SourceSummary public types
• New client.notebooks.get_metadata() helper
• Cinematic Video Overview support - Added cinematic generation and download flows
• notebooklm generate video --format cinematic
• Infographic styles - Added CLI support for selecting infographic visual styles
• `source delete-by-title` - Added explicit exact-title deletion command for sources

Fixed

• Research imports on timeout - CLI research imports now retry on timeout with backoff
• Metadata command behavior - Aligned metadata output and implementation with current CLI patterns
• Regional login cookies - Improved browser login handling for regional Google domains
• Notebook summary parsing - Fixed notebook summary response parsing
• Source delete UX - Improved source delete resolution, ambiguity handling, and title-vs-ID errors
• Empty downloads - Raise an error instead of producing zero-byte files
• Module execution - Added python -m notebooklm support

Changed

• Documentation refresh - Updated release, development, CLI, README, and Python API docs for current commands, APIs, and uv workflows
• Public API surface - Exported NotebookMetadata, SourceSummary, and InfographicStyle

[0.3.3] - 2026-03-03

Added

• `ask --save-as-note` - Save chat answers as notebook notes directly from the CLI (#135)
• notebooklm ask "question" --save-as-note - Save response as a note
• notebooklm ask "question" --save-as-note --note-title "Title" - Save with custom title
• `history --save` - Save full conversation history as a notebook note (#135)
• notebooklm history --save - Save history with default title
• notebooklm history --save --note-title "Title" - Save with custom title
• notebooklm history --show-all - Show full Q&A content instead of preview
• `generate report --append` - Append custom instructions to built-in report format templates (#134)
• Works with briefing-doc, study-guide, and blog-post formats (no effect on custom)
• Example: notebooklm generate report --format study-guide --append "Target audience: beginners"
• `generate revise-slide` - Revise individual slides in an existing slide deck (#129)
• notebooklm generate revise-slide "prompt" --artifact <id> --slide 0
• PPTX download for slide decks - Download slide decks as editable PowerPoint files (#129)
• notebooklm download slide-deck --format pptx (web UI only offers PDF)

Fixed

• Partial artifact ID in download commands - Download commands now support partial artifact IDs (#130)
• Chat empty answer - Fixed ask returning empty answer when API response marker changes (#123)
• X.com/Twitter content parsing - Fixed parsing of X.com/Twitter source content (#119)
• Language sync on login - Syncs server language setting to local config after notebooklm login (#124)
• Python version check - Added runtime check with clear error message for Python < 3.10 (#125)
• RPC error diagnostics - Improved error reporting for GET_NOTEBOOK and auth health check failures (#126, #127)
• Conversation persistence - Chat conversations now persist server-side; conversation ID shown in history output (#138)
• History Q&A previews - Fixed populating Q&A previews using conversation turns API (#136)
• `generate report --language` - Fixed missing --language option for report generation (#109)

Changed

• Chat history API - Simplified history retrieval; removed exchange_id, improved conversation grouping with parallel fetching (#140, #141)
• Conversation ID tracking - Server-side conversation lookup via new hPTbtc RPC (GET_LAST_CONVERSATION_ID) replaces local exchange ID tracking
• History Q&A population - Now uses khqZz RPC (GET_CONVERSATION_TURNS) to fetch full Q&A turns with accurate previews (#136)

Infrastructure

• Bumped actions/upload-artifact from v6 to v7 (#131)

[0.3.2] - 2026-01-26

Fixed

• CLI conversation reset - Fixed conversation ID not resetting when switching notebooks (#97)
• UTF-8 file encoding - Added explicit UTF-8 encoding to all file I/O operations (#93)
• Windows Playwright login - Restored ProactorEventLoop for Playwright login on Windows (#91)

Infrastructure

• Fixed E2E test teardown hook for pytest 8.x compatibility (#101)
• Added 15-second delay between E2E generation tests to avoid rate limits (#95)

[0.3.1] - 2026-01-23

Fixed

• Windows CLI hanging - Fixed asyncio ProactorEventLoop incompatibility causing CLI to hang on Windows (#79)
• Unicode encoding errors - Fixed encoding issues on non-English Windows systems (#80)
• Streaming downloads - Downloads now use streaming with temp files to prevent corrupted partial downloads (#82)
• Partial ID resolution - All CLI commands now support partial ID matching for notebooks, sources, and artifacts (#84)
• Source operations - Fixed empty array handling and add_drive nesting (#73)
• Guide response parsing - Fixed 3-level nesting in get_guide responses (#72)
• RPC health check - Handle null response in health check scripts (#71)
• Script cleanup - Ensure temp notebook cleanup on failure or interrupt

Infrastructure

• Added develop branch to nightly E2E tests with staggered schedule
• Added custom branch support to nightly E2E workflow for release testing

[0.3.0] - 2026-01-21

Added

• Language settings - Configure output language for artifact generation (audio, video, etc.)
• New notebooklm language list - List all 80+ supported languages with native names
• New notebooklm language get - Show current language setting
• New notebooklm language set <code> - Set language (e.g., zh_Hans, ja, es)
• Language is a global setting affecting all notebooks in your account
• --local flag for offline-only operations (skip server sync)
• --language flag on generate commands for per-command override
• Sharing API - Programmatic notebook sharing management
• New client.sharing.get_status(notebook_id) - Get current sharing configuration
• New client.sharing.set_public(notebook_id, True/False) - Enable/disable public link
• New client.sharing.set_view_level(notebook_id, level) - Set viewer access (FULL_NOTEBOOK or CHAT_ONLY)
• New client.sharing.add_user(notebook_id, email, permission) - Share with specific users
• New client.sharing.update_user(notebook_id, email, permission) - Update user permissions
• New client.sharing.remove_user(notebook_id, email) - Remove user access
• New ShareStatus, SharedUser dataclasses for structured sharing data
• New ShareAccess, SharePermission, ShareViewLevel enums
• `SourceType` enum - New str, Enum for type-safe source identification:
• GOOGLE_DOCS, GOOGLE_SLIDES, GOOGLE_SPREADSHEET, PDF, PASTED_TEXT, WEB_PAGE, YOUTUBE, MARKDOWN, DOCX, CSV, IMAGE, MEDIA, UNKNOWN
• `ArtifactType` enum - New str, Enum for type-safe artifact identification:
• AUDIO, VIDEO, REPORT, QUIZ, FLASHCARDS, MIND_MAP, INFOGRAPHIC, SLIDES, DATA_TABLE, UNKNOWN
• `.kind` property - Unified type access across Source, Artifact, and SourceFulltext:

  # Works with both enum and string comparison
  source.kind == SourceType.PDF        # True
  source.kind == "pdf"                 # Also True
  artifact.kind == ArtifactType.AUDIO  # True
  artifact.kind == "audio"             # Also True

• `UnknownTypeWarning` - Warning (deduplicated) when API returns unknown type codes
• `SourceStatus.PREPARING` - New status (5) for sources in upload/preparation phase
• E2E test coverage - Added file upload tests for CSV, MP3, MP4, DOCX, JPG, Markdown with type verification
• `--retry` flag for generation commands - Automatic retry with exponential backoff on rate limits
• notebooklm generate audio --retry 3 - Retry up to 3 times on rate limit errors
• Works with all generate commands (audio, video, quiz, etc.)
• `ArtifactStatus.FAILED` - New status (code 4) for artifact generation failures
• Centralized exception hierarchy - All errors now inherit from NotebookLMError base class
• New SourceAddError with detailed failure messages for source operations
• Granular exception types for better error handling in automation
• CLI `share` command group - Notebook sharing management from command line
• notebooklm share - Enable public sharing
• notebooklm share --revoke - Disable public sharing
• Partial UUID matching for note commands - note get, note delete, etc. now support partial IDs

Fixed

• Silent failures in CLI - Commands now properly report errors instead of failing silently
• Source type emoji display - Improved consistency in source list output

Changed

• Source type detection - Use API-provided type codes as source of truth instead of URL/extension heuristics
• CLI file handling - Simplified to always use add_file() for proper type detection

Removed

• `detect_source_type()` - Obsolete heuristic function replaced by Source.kind property
• `ARTIFACT_TYPE_DISPLAY` - Unused constant replaced by get_artifact_type_display()

Deprecated

The following emit DeprecationWarning when accessed and will be removed in v0.4.0. See Migration Guide for upgrade instructions.

• `Source.source_type` - Use .kind property instead (returns SourceType str enum)
• `Artifact.artifact_type` - Use .kind property instead (returns ArtifactType str enum)
• `Artifact.variant` - Use .kind, .is_quiz, or .is_flashcards instead
• `SourceFulltext.source_type` - Use .kind property instead
• `StudioContentType` - Use ArtifactType (str enum) for user-facing code

[0.2.1] - 2026-01-15

Added

• Authentication diagnostics - New notebooklm auth check command for troubleshooting auth issues
• Shows storage file location and validity
• Lists cookies present and their domains
• Detects NOTEBOOKLM_AUTH_JSON and NOTEBOOKLM_HOME usage
• --test flag performs network validation
• --json flag for machine-readable output (CI/CD friendly)
• Structured logging - Comprehensive DEBUG logging across library
• NOTEBOOKLM_LOG_LEVEL environment variable (DEBUG, INFO, WARNING, ERROR)
• RPC call timing and method tracking
• Legacy NOTEBOOKLM_DEBUG_RPC=1 still works
• RPC health monitoring - Automated nightly check for Google API changes
• Detects RPC method ID mismatches before they cause failures
• Auto-creates GitHub issues with rpc-breakage label on detection

Fixed

• Cookie domain priority - Prioritize .google.com cookies over regional domains (e.g., .google.co.uk) for more reliable authentication
• YouTube URL parsing - Improved handling of edge cases in YouTube video URLs

Documentation

• Added auth check to CLI reference and troubleshooting guide
• Consolidated CI/CD troubleshooting in development guide
• Added installation instructions to SKILL.md for Claude Code
• Clarified version numbering policy (PATCH vs MINOR)

[0.2.0] - 2026-01-14

Added

• Source fulltext extraction - Retrieve the complete indexed text content of any source
• New client.sources.get_fulltext(notebook_id, source_id) Python API
• New source fulltext <source_id> CLI command with --json and -o output options
• Returns SourceFulltext dataclass with content, title, URL, and character count
• Chat citation references - Get detailed source references for chat answers
• AskResult.references field contains list of ChatReference objects
• Each reference includes source_id, cited_text, start_char, end_char, chunk_id
• Use notebooklm ask "question" --json to see references in CLI output
• Source status helper - New source_status_to_str() function for consistent status display
• Quiz and flashcard downloads - Export interactive study materials in multiple formats
• New download quiz and download flashcards CLI commands
• Supports JSON, Markdown, and HTML output formats via --format flag
• Python API: client.artifacts.download_quiz() and client.artifacts.download_flashcards()
• Extended artifact downloads - Download additional artifact types
• New download report command (exports as Markdown)
• New download mind-map command (exports as JSON)
• New download data-table command (exports as CSV)
• All download commands support --all, --latest, --name, and --artifact selection options

Fixed

• Regional Google domain authentication - SID cookie extraction now works with regional Google domains (e.g., google.co.uk, google.de, google.cn) in addition to google.com
• Artifact completion detection - Media URL availability is now verified before reporting artifact as complete, preventing premature "ready" status
• URL hostname validation - Use proper URL parsing instead of string operations for security

Changed

• Pre-commit checks - Added mypy type checking to required pre-commit workflow

[0.1.4] - 2026-01-11

Added

• Source selection for chat and artifacts - Select specific sources when using ask or generate commands
• New --sources flag accepts comma-separated source IDs or partial matches
• Works with all generation commands (audio, video, quiz, etc.) and chat
• Research sources table - research status now displays sources in a formatted table instead of just a count

Fixed

• JSON output broken in TTY terminals - --json flag output was including ANSI color codes, breaking JSON parsing for commands like notebooklm list --json
• Warning stacklevel - warnings.warn calls now report correct source location

Infrastructure

• Windows CI testing - Windows is now part of the nightly E2E test matrix
• VCR.py integration - Added recorded HTTP cassette support for faster, deterministic integration tests
• Test coverage improvements - Improved coverage for _artifacts.py (71% → 83%), download.py, and session.py

[0.1.3] - 2026-01-10

Fixed

• PyPI README links - Documentation links now work correctly on PyPI
• Added hatch-fancy-pypi-readme plugin for build-time link transformation
• Relative links (e.g., docs/troubleshooting.md) are converted to version-tagged GitHub URLs
• PyPI users now see links pointing to the exact version they installed (e.g., /blob/v0.1.3/docs/...)
• Development repository link - Added prominent source link for PyPI users to find the GitHub repo

[0.1.2] - 2026-01-10

Added

• Ruff linter/formatter - Added to development workflow with pre-commit hooks and CI integration
• Multi-version testing - Docker-based test runner script for Python 3.10-3.14 (/matrix skill)
• Artifact verification workflow - New CI workflow runs 2 hours after nightly tests to verify generated artifacts

Changed

• Python version support - Now supports Python 3.10-3.14 (dropped 3.9)
• CI authentication - Use NOTEBOOKLM_AUTH_JSON environment variable (inline JSON, no file writes)

Fixed

• E2E test cleanup - Generation notebook fixture now only cleans artifacts once per session (was deleting artifacts between tests)
• Nightly CI - Fixed pytest marker from -m e2e to -m "not variants" (e2e marker didn't exist)
• macOS CI fix for Playwright version extraction (grep pattern anchoring)
• Python 3.10 test compatibility with mock.patch resolution

Documentation

• Claude Code skill: parallel agent safety guidance
• Claude Code skill: timeout recommendations for all artifact types
• Claude Code skill: clarified -n vs --notebook flag availability

[0.1.1] - 2026-01-08

Added

• NOTEBOOKLM_HOME environment variable for custom storage location
• NOTEBOOKLM_AUTH_JSON environment variable for inline authentication (CI/CD friendly)
• Claude Code skill installation via notebooklm skill install

Fixed

• Infographic generation parameter structure
• Mind map artifacts now persist as notes after generation
• Artifact export with proper ExportType enum handling
• Skill install path resolution for package data

Documentation

• PyPI release checklist
• Streamlined README
• E2E test fixture documentation

[0.1.0] - 2026-01-06

Added

• Initial release of notebooklm-py - unofficial Python client for Google NotebookLM
• Full notebook CRUD operations (create, list, rename, delete)
• Research polling CLI commands for LLM agent workflows:
• notebooklm research status - Check research progress (non-blocking)
• notebooklm research wait --import-all - Wait for completion and import sources
• notebooklm source add-research --no-wait - Start deep research without blocking
• Multi-artifact downloads with intelligent selection:
• download audio, download video, download infographic, download slide-deck
• Multiple artifact selection (--all flag)
• Smart defaults and intelligent filtering (--latest, --earliest, --name, --artifact-id)
• File/directory conflict handling (--force, --no-clobber, auto-rename)
• Preview mode (--dry-run) and structured output (--json)
• Source management:
• Add URL sources (with YouTube transcript support)
• Add text sources
• Add file sources (PDF, TXT, MD, DOCX) via native upload
• Delete sources
• Rename sources
• Studio artifact generation:
• Audio overviews (podcasts) with 4 formats and 3 lengths
• Video overviews with 9 visual styles
• Quizzes and flashcards
• Infographics, slide decks, and data tables
• Study guides, briefing docs, and reports
• Query/chat interface with conversation history support
• Research agents (Fast and Deep modes)
• Artifact downloads (audio, video, infographics, slides)
• CLI with 27 commands
• Comprehensive documentation (API, RPC, examples)
• 96 unit tests (100% passing)
• E2E tests for all major features

Fixed

• Audio overview instructions parameter now properly supported at RPC position [6][1][0]
• Quiz and flashcard distinction via title-based filtering
• Package renamed from notebooklm-automation to notebooklm
• CLI module renamed from cli.py to notebooklm_cli.py
• Removed orphaned cli_query.py file

⚠️ Beta Release Notice

This is the initial public release of notebooklm-py. While core functionality is tested and working, please note:

• RPC Protocol Fragility: This library uses undocumented Google APIs. Method IDs can change without notice, potentially breaking functionality. See Troubleshooting for debugging guidance.
• Unofficial Status: This is not affiliated with or endorsed by Google.
• API Stability: The Python API may change in future releases as we refine the interface.

Known Issues

• RPC method IDs may change: Google can update their internal APIs at any time, breaking this library. Check the RPC Development Guide for how to identify and update method IDs.
• Rate limiting: Heavy usage may trigger Google's rate limits. Add delays between bulk operations.
• Authentication expiry: CSRF tokens expire after some time. Re-run notebooklm login if you encounter auth errors.
• Large file uploads: Files over 50MB may fail or timeout. Split large documents if needed.

[Unreleased]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.4...HEAD [0.3.4]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.3...v0.3.4 [0.3.3]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.2...v0.3.3 [0.3.2]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.1...v0.3.2 [0.3.1]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/teng-lin/notebooklm-py/compare/v0.2.1...v0.3.0 [0.2.1]: https://github.com/teng-lin/notebooklm-py/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.4...v0.2.0 [0.1.4]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.3...v0.1.4 [0.1.3]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.2...v0.1.3 [0.1.2]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.1...v0.1.2 [0.1.1]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/teng-lin/notebooklm-py/releases/tag/v0.1.0

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

IMPORTANT: Follow documentation rules in CONTRIBUTING.md - especially the file creation and naming conventions.

Project Overview

notebooklm-py is an unofficial Python client for Google NotebookLM that uses undocumented RPC APIs. The library enables programmatic automation of NotebookLM features including notebook management, source integration, AI querying, and studio artifact generation (podcasts, videos, quizzes, etc.).

Critical constraint: This uses Google's internal batchexecute RPC protocol with obfuscated method IDs that Google can change at any time. All RPC method IDs in src/notebooklm/rpc/types.py are undocumented and subject to breakage.

Development Commands

# Create/recreate venv with uv (recommended - relocatable venvs)
uv venv .venv
uv pip install -e ".[all]"
playwright install chromium

# Activate virtual environment
source .venv/bin/activate

# Run all tests (excluding e2e by default)
pytest

# Run with coverage
pytest --cov

# Run e2e tests (requires authentication)
pytest tests/e2e -m e2e

# CLI testing
notebooklm --help

Pre-Commit Checks (REQUIRED before committing)

IMPORTANT: Always run these checks before committing to avoid CI failures:

# Format code with ruff
ruff format src/ tests/

# Check for linting issues
ruff check src/ tests/

# Type checking with mypy
mypy src/notebooklm --ignore-missing-imports

# Run tests
pytest

Or use this one-liner:

ruff format src/ tests/ && ruff check src/ tests/ && mypy src/notebooklm --ignore-missing-imports && pytest

Architecture

Layered Design

CLI Layer (cli/)
    ↓
Client Layer (client.py, _*.py APIs)
    ↓
Core Layer (_core.py)
    ↓
RPC Layer (rpc/)

1. RPC Layer (src/notebooklm/rpc/):

• types.py: All RPC method IDs and enums (source of truth)
• encoder.py: Request encoding
• decoder.py: Response parsing

2. Core Layer (src/notebooklm/_core.py):

• HTTP client management
• RPC call abstraction
• Request counter handling

3. Client Layer (src/notebooklm/client.py, _*.py):

• NotebookLMClient: Main async client with namespaced APIs
• _notebooks.py, _sources.py, _artifacts.py, etc.: Domain APIs

4. CLI Layer (src/notebooklm/cli/):

• Modular Click commands
• session.py, notebook.py, source.py, generate.py, etc.

Key Files

Repository Structure

src/notebooklm/
├── __init__.py          # Public exports
├── client.py            # NotebookLMClient
├── auth.py              # Authentication
├── types.py             # Dataclasses
├── _core.py             # Core infrastructure
├── _notebooks.py        # NotebooksAPI
├── _sources.py          # SourcesAPI
├── _artifacts.py        # ArtifactsAPI
├── _chat.py             # ChatAPI
├── _research.py         # ResearchAPI
├── _notes.py            # NotesAPI
├── rpc/                 # RPC protocol layer
│   ├── types.py         # Method IDs and enums
│   ├── encoder.py       # Request encoding
│   └── decoder.py       # Response parsing
└── cli/                 # CLI implementation
    ├── __init__.py
    ├── helpers.py       # Shared utilities
    ├── session.py       # login, use, status, clear
    ├── notebook.py      # list, create, delete, rename
    ├── source.py        # source add, list, delete
    ├── artifact.py      # artifact commands
    ├── generate.py      # generate audio, video, etc.
    ├── download.py      # download commands
    ├── chat.py          # ask, configure, history
    └── note.py          # note commands

API Patterns

Client Usage

# Correct pattern - uses namespaced APIs
async with await NotebookLMClient.from_storage() as client:
    notebooks = await client.notebooks.list()
    await client.sources.add_url(nb_id, url)
    result = await client.chat.ask(nb_id, question)
    status = await client.artifacts.generate_audio(nb_id)

CLI Structure

Commands are organized as:

• Top-level: login, use, status, clear, list, create, ask
• Grouped: source add, artifact list, generate audio, download video, note create

Testing Strategy

• Unit tests (tests/unit/): Test encoding/decoding, no network
• Integration tests (tests/integration/): Mock HTTP responses
• E2E tests (tests/e2e/): Real API, require auth, marked @pytest.mark.e2e

E2E Test Status

• ✅ Notebook operations (list, create, rename, delete)
• ✅ Source operations (add URL/text/YouTube, rename)
• ✅ Download operations (audio, video, infographic, slides)
• ⚠️ Artifact generation may fail due to rate limiting

Common Pitfalls

1. RPC method IDs change: Check network traffic and update rpc/types.py 2. Nested list structures: Params are position-sensitive. Check existing implementations. 3. Source ID nesting: Different methods need [id], [[id]], [[[id]]], or [[[[id]]]] 4. CSRF tokens expire: Use client.refresh_auth() or re-run notebooklm login 5. Rate limiting: Add delays between bulk operations

Documentation

All docs use lowercase-kebab naming in docs/:

• docs/cli-reference.md - CLI commands
• docs/python-api.md - Python API reference
• docs/configuration.md - Storage and settings
• docs/troubleshooting.md - Known issues
• docs/development.md - Architecture, testing, releasing
• docs/rpc-development.md - RPC capture and debugging
• docs/rpc-reference.md - RPC payload structures

When to Suggest CLI vs API

• CLI: Quick tasks, shell scripts, LLM agent automation
• Python API: Application integration, complex workflows, async operations

Pull Request Workflow (REQUIRED)

After creating a PR, you MUST monitor and address feedback:

1. Monitor CI Status

# Check CI status (repeat until all pass)
gh pr checks <PR_NUMBER>

Wait for all checks to pass. If any fail, investigate and fix.

2. Check for Review Comments

# Get review comments
gh api repos/teng-lin/notebooklm-py/pulls/<PR_NUMBER>/comments \
  --jq '.[] | "File: \(.path):\(.line)\nComment: \(.body)\n---"'

3. Address Feedback

For each review comment (especially from gemini-code-assist): 1. Read and understand the feedback 2. Make the suggested fix if it improves the code 3. Commit with a descriptive message referencing the feedback 4. Push and re-check CI 5. Reply to the review thread confirming the fix:

   gh api repos/teng-lin/notebooklm-py/pulls/<PR>/comments/<COMMENT_ID>/replies \
     -f body="Addressed in commit <SHA>: <brief description>"

4. Verify Final State

# Ensure PR is ready to merge
gh pr view <PR_NUMBER> --json state,mergeStateStatus,mergeable

Important: Do NOT consider a PR complete until:

• All CI checks pass
• All review comments are addressed
• mergeStateStatus is CLEAN

Contributing to notebooklm-py

For Human Contributors

Getting Started

# Install in development mode
pip install -e ".[all]"
playwright install chromium

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Run formatter
ruff format src/ tests/

Code Quality

This project uses ruff for linting and formatting:

# Check for lint issues
ruff check src/ tests/

# Auto-fix lint issues
ruff check --fix src/ tests/

# Check formatting
ruff format --check src/ tests/

# Apply formatting
ruff format src/ tests/

Pre-commit hooks (optional but recommended):

pip install pre-commit
pre-commit install

Pull Request Process

1. Create a feature branch from main 2. Make your changes with clear commit messages 3. Ensure tests pass: pytest 4. Ensure lint passes: ruff check src/ tests/ 5. Ensure formatting: ruff format --check src/ tests/ 6. Submit a PR with a description of changes

Pull Request Quality Expectations

• Reference an issue: PRs should link to an existing issue or clearly describe the problem being solved. If no issue exists, open one first for discussion.
• AI-assisted contributions: Welcome, but the submitter must review, understand, and test the code before submitting. PRs that appear to be unreviewed AI output will be closed.
• No duplicates: Check existing open PRs before submitting. Duplicate PRs for the same issue will be closed in favor of the first or best submission.
• Accurate severity: Claims of "critical" bugs must include evidence (stack trace, reproduction steps, affected users). Routine edge cases are not critical.
• Tested locally: All PRs must include evidence of local testing. The PR template includes a checklist for this.

---

Documentation Rules for AI Agents

IMPORTANT: All AI agents (Claude, Gemini, etc.) must follow these rules when working in this repository.

File Creation Rules

1. No Root Rule - Never create .md files in the repository root unless explicitly instructed by the user.

2. Modify, Don't Fork - Edit existing files; never create FILE_v2.md, FILE_REFERENCE.md, or FILE_updated.md duplicates.

3. Scratchpad Protocol - All analysis, investigation logs, and intermediate work go in docs/scratch/ with date prefix: YYYY-MM-DD-<context>.md

4. Consolidation First - Before creating new docs, search for existing related docs and update them instead.

Protected Sections

Some sections within files are critical and must not be modified without explicit user approval.

Inline markers (source of truth):

<!-- PROTECTED: Do not modify without approval -->
## Critical Section Title
Content that should not be changed by agents...
<!-- END PROTECTED -->

For code files:

# PROTECTED: Do not modify without approval
class RPCMethod(Enum):
    ...
# END PROTECTED

Rule: Never modify content between PROTECTED and END PROTECTED markers unless explicitly instructed by the user.

Design Decision Lifecycle

Design decisions should be captured where they're most useful, not in separate documents that become stale.

Why not design docs? Separate design documents accumulate and become stale. PR descriptions stay attached to the code changes, are searchable in GitHub, and don't clutter the repository.

Scratch files (docs/scratch/) - Temporary investigation logs and intermediate work. Format: YYYY-MM-DD-<context>.md. Periodically cleaned up.

Naming Conventions

Status Headers

All documentation files should include status metadata:

**Status:** Active | Deprecated
**Last Updated:** YYYY-MM-DD

Agents should ignore files marked Deprecated.

Information Management

1. Link, Don't Copy - Reference README.md sections instead of repeating commands. Prevents drift between docs.

2. Scoped Instructions - Subfolders like docs/examples/ may have their own README.md with folder-specific rules.

---

Documentation Structure

docs/
├── cli-reference.md       # CLI command reference
├── python-api.md          # Python API reference
├── configuration.md       # Storage and settings
├── troubleshooting.md     # Common issues and solutions
├── stability.md           # API versioning policy
├── development.md         # Architecture and testing
├── releasing.md           # Release checklist
├── rpc-development.md     # RPC capture and debugging
├── rpc-reference.md       # RPC payload structures
└── examples/              # Runnable example scripts

CLI Reference

Status: Active Last Updated: 2026-03-13

Complete command reference for the notebooklm CLI—providing full programmatic access to all NotebookLM features, including capabilities not exposed in the web UI.

Command Structure

notebooklm [-p PROFILE] [--storage PATH] [--version] [-v] <command> [OPTIONS] [ARGS]

Global Options:

• -p, --profile NAME - Use a named profile (overrides NOTEBOOKLM_PROFILE env var)
• --storage PATH - Override the default storage location
• -v, --verbose - Enable verbose output
• --version - Show version and exit
• --help - Show help message

Environment Variables:

• NOTEBOOKLM_HOME - Base directory for all config files (default: ~/.notebooklm)
• NOTEBOOKLM_PROFILE - Active profile name (default: default)
• NOTEBOOKLM_AUTH_JSON - Inline authentication JSON (for CI/CD, no file writes needed)
• NOTEBOOKLM_DEBUG_RPC - Enable RPC debug logging (1 to enable)

See Configuration for details on environment variables and CI/CD setup.

Command Organization:

• Session commands - Authentication and context management
• Notebook commands - CRUD operations on notebooks
• Chat commands - Querying and conversation management
• Grouped commands - source, artifact, agent, generate, download, note, share, research, language, skill, auth, profile
• Utility commands - metadata, doctor

---

Quick Reference

Session Commands

Profile Commands (notebooklm profile <cmd>)

Language Commands (notebooklm language <cmd>)

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

Notebook Commands

Chat Commands

Source Commands (notebooklm source <cmd>)

Supported source types: URLs, YouTube videos, files (PDF, text, Markdown, Word, audio, video, images), Google Drive documents, and pasted text.

source delete <id> accepts only full source IDs or unique partial-ID prefixes. To delete by exact source title, use source delete-by-title "<title>".

Research Commands (notebooklm research <cmd>)

Generate Commands (notebooklm generate <type>)

All generate commands support:

• --source/-s to select specific sources (repeatable)
• --json for machine-readable output (returns task_id and status)
• --language to override output language (defaults to config or 'en')
• --retry N to automatically retry on rate limits with exponential backoff

Artifact Commands (notebooklm artifact <cmd>)

Download Commands (notebooklm download <type>)

Note Commands (notebooklm note <cmd>)

Metadata Command

Export notebook metadata and a simplified source list.

notebooklm metadata [OPTIONS]

Options:

• -n, --notebook ID - Specify notebook (uses current if not set)
• --json - Output as JSON for scripts

Examples:

notebooklm metadata
notebooklm metadata -n abc123 --json

Skill Commands (notebooklm skill <cmd>)

Manage NotebookLM agent skill integration.

Defaults:

• skill install uses --scope user --target all
• claude maps to .claude/skills/notebooklm/SKILL.md
• agents maps to .agents/skills/notebooklm/SKILL.md
• show --target source prints the canonical packaged skill file

The packaged wheel includes the repo-root SKILL.md, so the same skill content powers notebooklm skill install, GitHub discovery, and npx skills add teng-lin/notebooklm-py.

Codex does not use the skill subcommand. In this repository it reads the root `AGENTS.md` file and invokes the notebooklm CLI or Python API directly.

Agent Commands (notebooklm agent <cmd>)

Show bundled instructions for supported agent environments.

agent show codex prefers the root `AGENTS.md` file when running from a source checkout, so the CLI mirrors the same instructions Codex sees in the repository.

Features Beyond the Web UI

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

---

Detailed Command Reference

Session: login

Authenticate with Google NotebookLM via browser.

notebooklm login [OPTIONS]

Opens a Chromium browser with a persistent profile. Log in to your Google account, then press Enter in the terminal to save the session.

Options:

• --storage PATH - Where to save storage_state.json (default: $NOTEBOOKLM_HOME/storage_state.json)
• --browser [chromium|msedge] - Browser to use for login (default: chromium). Use msedge for Microsoft Edge.

Examples:

# Default (Chromium)
notebooklm login

# Use Microsoft Edge (for orgs that require Edge for SSO)
notebooklm login --browser msedge

Session: use

Set the active notebook for subsequent commands.

notebooklm use <notebook_id>

Supports partial ID matching:

notebooklm use abc  # Matches abc123def456...

Session: status

Show current context (active notebook and conversation).

notebooklm status [OPTIONS]

Options:

• --paths - Show resolved configuration file paths
• --json - Output as JSON (useful for scripts)

Examples:

# Basic status
notebooklm status

# Show where config files are located
notebooklm status --paths
# Output shows home_dir, storage_path, context_path, browser_profile_dir

# JSON output for scripts
notebooklm status --json

With `--paths`:

                Configuration Paths
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ File            ┃ Path                         ┃ Source          ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ Home Directory  │ /home/user/.notebooklm      │ default         │
│ Storage State   │ .../storage_state.json      │                 │
│ Context         │ .../context.json            │                 │
│ Browser Profile │ .../browser_profile         │                 │
└─────────────────┴──────────────────────────────┴─────────────────┘

Language: list, get, set

Manage the output language for artifact generation (audio, video, etc.).

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

# List all supported languages with native names
notebooklm language list

# Show current language setting (syncs from server)
notebooklm language get

# Set language to Simplified Chinese
notebooklm language set zh_Hans

# Set language to Japanese
notebooklm language set ja

Options for `get`:

• --local - Skip server sync, show local config only
• --json - Output as JSON

Options for `set`:

• --local - Save to local config only, skip server sync
• --json - Output as JSON

Common language codes:

Run notebooklm language list for all 80+ supported languages.

Share: status, public, view-level, add, update, remove

Manage notebook sharing settings and user permissions.

# Show current sharing status and shared users
notebooklm share status

# Enable public link sharing (anyone with link can view)
notebooklm share public --enable

# Disable public sharing
notebooklm share public --disable

# Set what viewers can access
notebooklm share view-level full   # Full notebook (chat, sources, notes)
notebooklm share view-level chat   # Chat interface only

# Share with specific users
notebooklm share add user@example.com                        # Add as viewer (default)
notebooklm share add user@example.com --permission editor    # Add as editor
notebooklm share add user@example.com -m "Check this out!"   # With message
notebooklm share add user@example.com --no-notify            # Skip email notification

# Update user permission
notebooklm share update user@example.com --permission editor

# Remove user access
notebooklm share remove user@example.com
notebooklm share remove user@example.com -y   # Skip confirmation

Options (all commands):

• -n, --notebook ID - Specify notebook (uses current if not set, supports partial IDs)
• --json - Output as JSON

Permission levels:

View levels:

Session: auth check

Diagnose authentication issues by validating storage file, cookies, and optionally testing token fetch.

notebooklm auth check [OPTIONS]

Options:

• --test - Also test token fetch from NotebookLM (makes network request)
• --json - Output as JSON (useful for scripts)

Examples:

# Quick local validation
notebooklm auth check

# Full validation with network test
notebooklm auth check --test

# JSON output for automation
notebooklm auth check --json

Checks performed: 1. Storage file exists and is readable 2. JSON structure is valid 3. Required cookies (SID) are present 4. Cookie domains are correct (.google.com vs regional) 5. (With --test) Token fetch succeeds

Output shows:

• Authentication source (file path or environment variable)
• Which cookies were found and from which domains
• Detailed cookie breakdown by domain (highlighting key auth cookies)
• Token lengths when using --test

Use cases:

• Debug "Not logged in" errors
• Verify auth setup in CI/CD environments
• Check if cookies are from correct domain (regional vs .google.com)
• Diagnose NOTEBOOKLM_AUTH_JSON environment variable issues

Source: add-research

Perform AI-powered research and add discovered sources to the notebook.

notebooklm source add-research <query> [OPTIONS]

Options:

• --mode [fast|deep] - Research depth (default: fast)
• --from [web|drive] - Search source (default: web)
• --import-all - Automatically import all found sources (works with blocking mode)
• --no-wait - Start research and return immediately (non-blocking)

Examples:

# Fast web research (blocking)
notebooklm source add-research "Quantum computing basics"

# Deep research into Google Drive
notebooklm source add-research "Project Alpha" --from drive --mode deep

# Non-blocking deep research for agent workflows
notebooklm source add-research "AI safety papers" --mode deep --no-wait

Research: status

Check research status for the current notebook (non-blocking).

notebooklm research status [OPTIONS]

Options:

• -n, --notebook ID - Notebook ID (uses current if not set)
• --json - Output as JSON

Output states:

• No research running - No active research session
• Research in progress - Deep research is still running
• Research completed - Shows query, found sources, and summary

Examples:

# Check status
notebooklm research status

# JSON output for scripts/agents
notebooklm research status --json

Research: wait

Wait for research to complete (blocking).

notebooklm research wait [OPTIONS]

Options:

• -n, --notebook ID - Notebook ID (uses current if not set)
• --timeout SECONDS - Maximum seconds to wait (default: 300)
• --interval SECONDS - Seconds between status checks (default: 5)
• --import-all - Import all found sources when done
• --json - Output as JSON

Examples:

# Basic wait
notebooklm research wait

# Wait longer for deep research
notebooklm research wait --timeout 600

# Wait and auto-import sources
notebooklm research wait --import-all

# JSON output for agent workflows
notebooklm research wait --json --import-all

Use case: Primarily for LLM agents that need to wait for non-blocking deep research started with source add-research --no-wait.

Generate: audio

Generate an audio overview (podcast).

notebooklm generate audio [description] [OPTIONS]

Options:

• --format [deep-dive|brief|critique|debate] - Podcast format (default: deep-dive)
• --length [short|default|long] - Duration (default: default)
• --language LANG - Language code (default: en)
• -s, --source ID - Use specific source(s) (repeatable, uses all if not specified)
• --wait - Wait for generation to complete
• --json - Output as JSON (returns task_id and status)

Examples:

# Basic podcast (starts async, returns immediately)
notebooklm generate audio

# Debate format with custom instructions
notebooklm generate audio "Compare the two main viewpoints" --format debate

# Generate and wait for completion
notebooklm generate audio "Focus on key points" --wait

# Generate using only specific sources
notebooklm generate audio -s src_abc -s src_def

# JSON output for scripting/automation
notebooklm generate audio --json
# Output: {"task_id": "abc123...", "status": "pending"}

Generate: video

Generate a video overview.

notebooklm generate video [description] [OPTIONS]

Options:

• --format [explainer|brief] - Video format
• --style [auto|classic|whiteboard|kawaii|anime|watercolor|retro|heritage|paper-craft] - Visual style
• --language LANG - Language code
• -s, --source ID - Use specific source(s) (repeatable, uses all if not specified)
• --wait - Wait for generation to complete
• --json - Output as JSON (returns task_id and status)

Examples:

# Kid-friendly explainer
notebooklm generate video "Explain for 5 year olds" --style kawaii

# Professional style
notebooklm generate video --style classic --wait

# Generate from specific sources only
notebooklm generate video -s src_123 -s src_456

# JSON output for scripting/automation
notebooklm generate video --json

Generate: revise-slide

Revise an individual slide in an existing slide deck using a natural-language prompt.

notebooklm generate revise-slide <description> --artifact <id> --slide N [OPTIONS]

Required Options:

• -a, --artifact ID - The slide deck artifact ID to revise
• --slide N - Zero-based index of the slide to revise (0 = first slide)

Optional:

• --wait - Wait for revision to complete
• --json - Machine-readable output

Examples:

# Revise the first slide
notebooklm generate revise-slide "Move the title up" --artifact art123 --slide 0

# Revise the fourth slide and wait for completion
notebooklm generate revise-slide "Remove taxonomy table" --artifact art123 --slide 3 --wait

Note: The slide deck must already be fully generated before using revise-slide. Use artifact list to find the artifact ID.

---

Generate: report

Generate a text report (briefing doc, study guide, blog post, or custom).

notebooklm generate report [description] [OPTIONS]

Options:

• --format [briefing-doc|study-guide|blog-post|custom] - Report format (default: briefing-doc)
• --append TEXT - Append extra instructions to the built-in prompt (no effect with --format custom)
• -s, --source ID - Use specific source(s) (repeatable, uses all if not specified)
• --wait - Wait for generation to complete
• --json - Output as JSON

Examples:

notebooklm generate report --format study-guide
notebooklm generate report "Executive summary for stakeholders" --format briefing-doc

# Generate report from specific sources
notebooklm generate report --format study-guide -s src_001 -s src_002

# Custom report with description (auto-selects custom format)
notebooklm generate report "Create a white paper analyzing the key trends"

# Append instructions to a built-in format
notebooklm generate report --format study-guide --append "Target audience: beginners"
notebooklm generate report --format briefing-doc --append "Focus on AI trends, keep it under 2 pages"

Download: audio, video, slide-deck, infographic, report, mind-map, data-table

Download generated artifacts to your local machine.

notebooklm download <type> [OUTPUT_PATH] [OPTIONS]

Artifact Types and Output Formats:

Options:

• --all - Download all artifacts of this type
• --latest - Download only the most recent artifact (default if no ID/name provided)
• --earliest - Download only the oldest artifact
• --name NAME - Download artifact with matching title (supports partial matches)
• -a, --artifact ID - Select specific artifact by ID (supports partial IDs)
• --dry-run - Show what would be downloaded without actually downloading
• --force - Overwrite existing files
• --no-clobber - Skip if file already exists (default)
• --format [pdf|pptx] - Slide deck format (slide-deck command only, default: pdf)
• --json - Output result in JSON format

Examples:

# Download the latest podcast
notebooklm download audio ./podcast.mp3

# Download all infographics
notebooklm download infographic --all

# Download a specific slide deck by name
notebooklm download slide-deck --name "Final Presentation"

# Download slide deck as PPTX (editable PowerPoint)
notebooklm download slide-deck --format pptx

# Preview a batch download
notebooklm download audio --all --dry-run

# Download a report as markdown
notebooklm download report ./study-guide.md

# Download mind map as JSON
notebooklm download mind-map ./concept-map.json

# Download data table as CSV (opens in Excel)
notebooklm download data-table ./research-data.csv

Download: quiz, flashcards

Download quiz questions or flashcard decks in various formats.

notebooklm download quiz [OUTPUT_PATH] [OPTIONS]
notebooklm download flashcards [OUTPUT_PATH] [OPTIONS]

Options:

• -n, --notebook ID - Notebook ID (uses current context if not set)
• --format FORMAT - Output format: json (default), markdown, or html
• -a, --artifact ID - Select specific artifact by ID

Output Formats:

• JSON - Structured data preserving full API fields (answerOptions, rationale, isCorrect, hint)
• Markdown - Human-readable format with checkboxes for correct answers
• HTML - Raw HTML as returned from NotebookLM

Examples:

# Download quiz as JSON
notebooklm download quiz quiz.json

# Download quiz as markdown
notebooklm download quiz --format markdown quiz.md

# Download flashcards as JSON (normalizes f/b keys to front/back)
notebooklm download flashcards cards.json

# Download flashcards as markdown
notebooklm download flashcards --format markdown cards.md

# Download flashcards as raw HTML
notebooklm download flashcards --format html cards.html

---

Common Workflows

Research → Podcast

Find information on a topic and create a podcast about it.

# 1. Create a notebook for this research
notebooklm create "Climate Change Research"
# Output: Created notebook: abc123

# 2. Set as active
notebooklm use abc123

# 3. Add a starting source
notebooklm source add "https://en.wikipedia.org/wiki/Climate_change"

# 4. Research more sources automatically (blocking - waits up to 5 min)
notebooklm source add-research "climate change policy 2024" --mode deep --import-all

# 5. Generate a podcast
notebooklm generate audio "Focus on policy solutions and future outlook" --format debate --wait

# 6. Download the result
notebooklm download audio ./climate-podcast.mp3

Research → Podcast (Non-blocking with Subagent)

For LLM agents, use non-blocking mode to avoid timeout:

# 1-3. Create notebook and add initial source (same as above)
notebooklm create "Climate Change Research"
notebooklm use abc123
notebooklm source add "https://en.wikipedia.org/wiki/Climate_change"

# 4. Start deep research (non-blocking)
notebooklm source add-research "climate change policy 2024" --mode deep --no-wait
# Returns immediately

# 5. In a subagent, wait for research and import
notebooklm research wait --import-all --timeout 300
# Blocks until complete, then imports sources

# 6. Continue with podcast generation...

Research commands:

• research status - Check if research is in progress, completed, or not running
• research wait --import-all - Block until research completes, then import sources

Document Analysis → Study Materials

Upload documents and create study materials.

# 1. Create notebook
notebooklm create "Exam Prep"
notebooklm use <id>

# 2. Add your documents
notebooklm source add "./textbook-chapter.pdf"
notebooklm source add "./lecture-notes.pdf"

# 3. Get a summary
notebooklm summary

# 4. Generate study materials
notebooklm generate quiz --difficulty hard --wait
notebooklm generate flashcards --wait
notebooklm generate report --format study-guide --wait

# 5. Ask specific questions
notebooklm ask "Explain the key concepts in chapter 3"
notebooklm ask "What are the most likely exam topics?"

YouTube → Quick Summary

Turn a YouTube video into notes.

# 1. Create notebook and add video
notebooklm create "Video Notes"
notebooklm use <id>
notebooklm source add "https://www.youtube.com/watch?v=VIDEO_ID"

# 2. Get summary
notebooklm summary

# 3. Ask questions
notebooklm ask "What are the main points?"
notebooklm ask "Create bullet point notes"

# 4. Generate a quick briefing doc
notebooklm generate report --format briefing-doc --wait

Bulk Import

Add multiple sources at once.

# Set active notebook
notebooklm use <id>

# Add multiple URLs
notebooklm source add "https://example.com/article1"
notebooklm source add "https://example.com/article2"
notebooklm source add "https://example.com/article3"

# Add multiple local files (use a loop)
for f in ./papers/*.pdf; do
  notebooklm source add "$f"
done

---

Tips for LLM Agents

When using this CLI programmatically:

1. Two ways to specify notebooks: Either use notebooklm use <id> to set context, OR pass -n <id> directly to commands. Most commands support -n/--notebook as an explicit override.

2. Generation commands are async by default (except mind-map):

• mind-map: Synchronous, completes instantly (no --wait option)
• All others: Return immediately with task ID (default: --no-wait)

Avoid --wait for LLM agents—all async operations can take minutes to 30+ minutes. Use artifact wait <id> in a background task or inform the user to check back later.

3. Partial IDs work: notebooklm use abc matches any notebook ID starting with "abc".

4. Check status: Use notebooklm status to see the current active notebook and conversation.

5. Auto-detection: source add auto-detects content type:

• URLs starting with http → web source
• YouTube URLs → video transcript extraction
• File paths → file upload (PDF, text, Markdown, Word, audio, video, images)

6. Error handling: Commands exit with non-zero status on failure. Check stderr for error messages.

7. Deep research: Use --no-wait with source add-research --mode deep to avoid blocking. Then use research wait --import-all in a subagent to wait for completion.