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

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

Autonomy Rules

The wait rule (resolves the only ambiguous case): A wait command (artifact wait, source wait, research wait) is fine to run without confirmation when it runs in a background agent/job that polls an already-started task. It needs confirmation when run inline in the main conversation, because it blocks the conversation for the full generation window. Default to delegating waits to a background worker; only block inline if the user explicitly asked for a blocking workflow.

Run automatically (no confirmation):

• notebooklm status / auth check / doctor - diagnostics
• notebooklm list / source list / artifact list / history - read-only listings
• notebooklm language list / language get / language set - language config
• notebooklm research status - check research status
• notebooklm artifact wait / source wait / research wait - only in a background/automation context (see the wait rule above)
• notebooklm use <id> - set context (⚠️ SINGLE-AGENT ONLY - use -n flag in parallel workflows)
• notebooklm create - create notebook
• notebooklm source add - add sources
• notebooklm ask "..." - chat queries (without --save-as-note)
• notebooklm profile list / profile create / profile switch - profile management

Ask before running:

• notebooklm delete - destructive
• notebooklm generate * - long-running, may fail
• notebooklm download * - writes to filesystem
• notebooklm artifact wait / source wait / research wait - only when run inline in the main conversation (see the wait rule above)
• notebooklm ask "..." --save-as-note - writes a note
• notebooklm history --save - writes a note

Quick Reference

For a complete command reference, see references/quick-reference.md. Detailed tables (generation types and options, language codes, JSON schemas, exit codes) and step-by-step workflows live in references/reference.md.

Core command surface

Day-to-day commands (full table in references/quick-reference.md):

• Notebooks: create "Title", list, use <id> (single-agent), notebook delete <id>
• Sources: source add <url|file>, source list, source wait <id>, source fulltext <id>, source add-research "query" [--mode deep]
• Chat: ask "question" (add --json for citations, --save-as-note to persist)
• Generate: generate <audio|video|slide-deck|infographic|report|mind-map|data-table|quiz|flashcards> [...] — returns a task_id
• Artifacts: artifact list, artifact wait <id>, download <type> <path>
• Research: research status, research wait --import-all
• Config: language set <code>, profile create/switch, doctor

--json is available on most commands for machine-readable output. Generation, download, exit codes, JSON schemas, language codes, processing times, and step-by-step workflows are documented in references/reference.md.

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 a background worker with artifact wait

JSON output: Most commands accept --json for machine-readable output (list, auth check, source list, artifact list, generate, ask, ...). Field-level schemas and status-value meanings are in references/reference.md.

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: 0 success, 1 error (not found / processing failed), 2 timeout (wait commands only). Full breakdown in references/reference.md.

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 (source processing 30s–10min, deep research 15–30+min, audio 10–20min, video 15–45min). Use background execution for long operations and poll every 15–30s when checking status manually. Full timing/timeout table is in references/reference.md.

Language is a GLOBAL account setting (notebooklm language set <code>, e.g. ja, zh_Hans), overridable per generate command with --language. Code list and offline --local usage are in references/reference.md.

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 Update an outdated CLI: reinstall the latest release per the Installation section above (pip install -U notebooklm-py). If the CLI provides a notebooklm skill install subcommand for refreshing its bundled skill files, run that after upgrading; otherwise the pip upgrade is sufficient.