CLI Reference

CLI Reference

Status: Active Last Updated: 2026-01-20

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 [--storage PATH] [--version] <command> [OPTIONS] [ARGS]

Global Options:

• --storage PATH - Override the default storage location (~/.notebooklm/storage_state.json)
• --version - Show version and exit
• --help - Show help message

Environment Variables:

• NOTEBOOKLM_HOME - Base directory for all config files (default: ~/.notebooklm)
• 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, generate, download, note

Quick Reference

Session Commands

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.

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

Skill Commands (notebooklm skill <cmd>)

Manage Claude Code skill integration.

After installation, Claude Code recognizes NotebookLM commands via /notebooklm or natural language like "create a podcast about X".

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

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

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: 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)
• -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"

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
• --dry-run - Show what would be downloaded without actually downloading
• --force - Overwrite existing files
• --no-clobber - Skip if file already exists (default)
• --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"

# 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 --type 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 --type 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.