notebooklm

<!-- notebooklm-py v0.3.4 --> # 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. ## Dynamic Workflow orchestration NotebookLM work decomposes into independent units that parallelize cleanly. Use explicit notebook IDs (`-n`/`--notebook`) and per-agent isolation (`NOTEBOOKLM_HOME`) so concurrent agents never clobber shared context (`~/.notebooklm/context.json`). **1. Plan.** Enumerate the request into its natural units BEFORE acting: which sources to ingest, which artifact types to produce, what download formats are wanted. Pick a notebook ID once and pin it to every command. **2. Fan out (parallel, file-disjoint by notebook).** - *Source ingestion:* add all sources, then wait for each in parallel background subagents (`source wait <id> -n <nb>`). Continue-on-fail — one bad URL never blocks the rest (R-SCOPE: disjoint IDs, no shared context). - *Artifact generation:* podcast, video, report, quiz, mind-map etc. are independent — kick each off with `generate <type> ... --json`, capture every `task_id`, and spawn one background `artifact wait` subagent per artifact. Do NOT serialize or poll in the main thread (generation runs 5–45 min). - *Deep research (loop-until-dry, unknown size):* `source add-research "query" --mode deep --no-wait`, then a subagent runs `research wait -n <nb> --import-all` until the discovery set is exhausted; re-query a narrower angle if coverage is thin. **3. Adversarially verify (≥3 skeptic lenses, 2-of-3 consensus).** Before claiming an artifact is done, falsify it across independent checks — do not trust the tool's own "completed": - *Existence:* `artifact list --json` shows `status: completed` for the captured `task_id`. - *Materialization:* the downloaded file exists and is non-empty / non-zero bytes on disk. - *Faithfulness:* spot-check `ask "..." --json` answers against `source fulltext` via `find_citation_context()` — flag any claim whose `cited_text` cannot be located in a real source as a hallucination, never report it as fact. A `GENERATION_FAILED` / rate-limit / 401 / 403 is an ABORT, never a PASS (L5). **4. Synthesize yourself.** You write the final summary — never paste a subagent's raw report as the verdict. Report: notebook ID, sources ingested (ready/failed), artifacts produced with their on-disk paths, and any cited-but-unverifiable claim explicitly flagged. **Output contract:** every run ends with (a) the notebook ID, (b) a source manifest (ready vs failed), (c) artifact paths on disk, (d) verification status per artifact. **Verify command:** `notebooklm artifact list --json` + `test -s <downloaded-file>` for each download. **No-hallucination guardrail:** every factual claim traces to a source via citation context; unverifiable claims are flagged, not stated (R-CITE). ## Installation **From PyPI (Recommended):** ```bash pip install notebooklm-py ``` **From GitHub (use latest release tag, NOT main branch):** ```bash # 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. After installation, install the Claude Code skill: ```bash notebooklm skill install ``` ## Prerequisites **IMPORTANT:** Before using any command, you MUST authenticate: ```bash 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: | Variable | Purpose | |----------|---------| | `NOTEBOOKLM_HOME` | Custom config directory (default: `~/.notebooklm`) | | `NOTEBOOKLM_AUTH_JSON` | Inline auth JSON - no file writes needed | **CI/CD setup:** Set `NOTEBOOKLM_AUTH_JSON` from a secret containing your `storage_state.json` contents. **Multiple accounts:** 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:** Set unique `NOTEBOOKLM_HOME` per agent: `export NOTEBOOKLM_HOME=/tmp/agent-$ID` 3. **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 **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 | Task | Command | |------|---------| | Authenticate | `notebooklm login` | | Diagnose auth issues | `notebooklm auth check` | | Diagnose auth (full) | `notebooklm auth check --test` | | List notebooks | `notebooklm list` | | Create notebook | `notebooklm create "Title"` | | Set context | `notebooklm use <notebook_id>` | | Show context | `notebooklm status` | | Add URL source | `notebooklm source add "https://..."` | | Add file | `notebooklm source add ./file.pdf` | | Add YouTube | `notebooklm source add "https://youtube.com/..."` | | List sources | `notebooklm source list` | | Delete source by ID | `notebooklm source delete <source_id>` | | Delete source by exact title | `notebooklm source delete-by-title "Exact Title"` | | Wait for source processing | `notebooklm source wait <source_id>` | | Web research (fast) | `notebooklm source add-research "query"` | | Web research (deep) | `notebooklm source add-research "query" --mode deep --no-wait` | | Check research status | `notebooklm research status` | | Wait for research | `notebooklm research wait --import-all` | | Chat | `notebooklm ask "question"` | | Chat (specific sources) | `notebooklm ask "question" -s src_id1 -s src_id2` | | Chat (with references) | `notebooklm ask "question" --json` | | Chat (save answer as note) | `notebooklm ask "question" --save-as-note` | | Chat (save with title) | `notebooklm ask "question" --save-as-note --note-title "Title"` | | Show conversation history | `notebooklm history` | | Save all history as note | `notebooklm history --save` | | Continue specific conversation | `notebooklm ask "question" -c <conversation_id>` | | Save history with title | `notebooklm history --save --note-title "My Research"` | | Get source fulltext | `notebooklm source fulltext <source_id>` | | Get source guide | `notebooklm source guide <source_id>` | | Generate podcast | `notebooklm generate audio "instructions"` | | Generate podcast (JSON) | `notebooklm generate audio --json` | | Generate podcast (specific sources) | `notebooklm generate audio -s src_id1 -s src_id2` | | Generate video | `notebooklm generate video "instructions"` | | Generate report | `notebooklm generate report --format briefing-doc` | | Generate report (append instructions) | `notebooklm generate report --format study-guide --append "Target audience: beginners"` | | Generate quiz | `notebooklm generate quiz` | | Revise a slide | `notebooklm generate revise-slide "prompt" --artifact <id> --slide 0` | | Check artifact status | `notebooklm artifact list` | | Wait for completion | `notebooklm artifact wait <artifact_id>` | | Download audio | `notebooklm download audio ./output.mp3` | | Download video | `notebooklm download video ./output.mp4` | | Download slide deck (PDF) | `notebooklm download slide-deck ./slides.pdf` | | Download slide deck (PPTX) | `notebooklm download slide-deck ./slides.pptx --format pptx` | | Download report | `notebooklm download report ./report.md` | | Download mind map | `notebooklm download mind-map ./map.json` | | Download data table | `notebooklm download data-table ./data.csv` | | Download quiz | `notebooklm download quiz quiz.json` | | Download quiz (markdown) | `notebooklm download quiz --format markdown quiz.md` | | Download flashcards | `notebooklm download flashcards cards.json` | | Download flashcards (markdown) | `notebooklm download flashcards --format markdown cards.md` | | Delete notebook | `notebooklm notebook delete <id>` | | List languages | `notebooklm language list` | | Get language | `notebooklm language get` | | Set language | `notebooklm language set zh_Hans` | **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: ```python 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 ```