Back to Details

notebooklm

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- notebooklm-py v0.2.1 -->
<!-- notebooklm-py v0.2.1 -->

NotebookLM Automation

NotebookLM 自动化

Automate Google NotebookLM: create notebooks, add sources, chat with content, generate artifacts (podcasts, videos, quizzes), and download results.
自动化Google NotebookLM：创建笔记本、添加资源、与内容对话、生成成果物（播客、视频、测验）并下载结果。

Installation

安装

From PyPI (Recommended):
bash
pip install notebooklm-py
From GitHub (use latest release tag, NOT main branch):
bash
undefined
从PyPI安装（推荐）：
bash
pip install notebooklm-py
从GitHub安装（使用最新发布标签，而非main分支）：
bash
undefined

Get the latest release tag (using curl)

获取最新发布标签（使用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
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}"

⚠️ **请勿从main分支安装**（`pip install git+https://github.com/teng-lin/notebooklm-py`）。main分支可能包含未发布/不稳定的变更。除非你在测试未发布功能，否则请始终使用PyPI或特定的发布标签。

安装完成后，安装Claude Code技能：
```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
.
重要提示： 在使用任何命令之前，你必须先进行身份验证：
bash
notebooklm login          # 打开浏览器进行Google OAuth验证
notebooklm list           # 验证身份验证是否成功
如果命令因身份验证错误失败，请重新运行
notebooklm login
。

CI/CD, Multiple Accounts, and Parallel Agents

CI/CD、多账户与并行Agent

For automated environments, multiple accounts, or parallel agent workflows:
VariablePurpose
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工作流：
变量用途
NOTEBOOKLM_HOME
自定义配置目录（默认：
~/.notebooklm
）
NOTEBOOKLM_AUTH_JSON
内联身份验证JSON - 无需写入文件
CI/CD设置： 从包含你的
storage_state.json
内容的密钥中设置
NOTEBOOKLM_AUTH_JSON
。
多账户： 为每个账户使用不同的
NOTEBOOKLM_HOME
目录。
并行Agent： CLI将笔记本上下文存储在共享文件（
~/.notebooklm/context.json
）中。多个并发Agent使用
notebooklm use
会覆盖彼此的上下文。
并行工作流解决方案：
  1. 始终使用明确的笔记本ID（推荐）：使用
    -n <notebook_id>
    （适用于
    wait
    /
    download
    命令）或
    --notebook <notebook_id>
    （适用于其他命令），而非依赖
    use
    命令
  2. Agent级隔离： 为每个Agent设置唯一的
    NOTEBOOKLM_HOME
    ：
    export NOTEBOOKLM_HOME=/tmp/agent-$ID
  3. 使用完整UUID： 在自动化中避免使用部分ID（可能会导致歧义）

Agent Setup Verification

Agent设置验证

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
在开始工作流之前，验证CLI是否准备就绪：
  1. notebooklm status
    → 应显示“Authenticated as: email@...”
  2. notebooklm list --json
    → 应返回有效的JSON（即使笔记本列表为空）
  3. 如果任一命令失败 → 运行
    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"
  • "Add these sources to NotebookLM"
明确触发： 用户说出"/notebooklm"、"use notebooklm"，或提及该工具的名称
意图检测： 识别以下类似请求：
  • "创建一个关于[主题]的播客"
  • "总结这些URL/文档"
  • "根据我的研究生成测验"
  • "将此转换为音频概述"
  • "将这些资源添加到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 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
  • 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 status
    - 检查上下文
  • notebooklm auth check
    - 诊断身份验证问题
  • notebooklm list
    - 列出笔记本
  • notebooklm source list
    - 列出资源
  • notebooklm artifact list
    - 列出成果物
  • notebooklm artifact wait
    - 等待成果物完成（在子Agent上下文中）
  • notebooklm source wait
    - 等待资源处理完成（在子Agent上下文中）
  • notebooklm research status
    - 检查研究状态
  • notebooklm research wait
    - 等待研究完成（在子Agent上下文中）
  • notebooklm use <id>
    - 设置上下文（⚠️ 仅适用于单Agent - 并行工作流中使用
    -n
    标志）
  • notebooklm create
    - 创建笔记本
  • notebooklm ask "..."
    - 对话查询
  • notebooklm source add
    - 添加资源
运行前需询问用户：
  • notebooklm delete
    - 破坏性操作
  • notebooklm generate *
    - 运行时间长，可能失败
  • notebooklm download *
    - 写入文件系统
  • notebooklm artifact wait
    - 运行时间长（在主对话中）
  • notebooklm source wait
    - 运行时间长（在主对话中）
  • notebooklm research wait
    - 运行时间长（在主对话中）

Quick Reference

快速参考

TaskCommand
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
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 (new conversation)
notebooklm ask "question" --new
Chat (specific sources)
notebooklm ask "question" -s src_id1 -s src_id2
Chat (with references)
notebooklm ask "question" --json
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 quiz
notebooklm generate quiz
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 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>
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 
--new
to start fresh conversations (avoids conversation ID conflicts).
Partial IDs: Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for: 
use
, 
delete
, 
wait
commands. For automation, prefer full UUIDs to avoid ambiguity.
任务命令
身份验证
notebooklm login
诊断身份验证问题
notebooklm auth check
全面诊断身份验证
notebooklm auth check --test
列出笔记本
notebooklm list
创建笔记本
notebooklm create "Title"
设置上下文
notebooklm use <notebook_id>
查看上下文
notebooklm status
添加URL资源
notebooklm source add "https://..."
添加文件
notebooklm source add ./file.pdf
添加YouTube链接
notebooklm source add "https://youtube.com/..."
列出资源
notebooklm source list
等待资源处理完成
notebooklm source wait <source_id>
快速网页研究
notebooklm source add-research "query"
深度网页研究
notebooklm source add-research "query" --mode deep --no-wait
检查研究状态
notebooklm research status
等待研究完成
notebooklm research wait --import-all
对话
notebooklm ask "question"
开启新对话
notebooklm ask "question" --new
指定资源对话
notebooklm ask "question" -s src_id1 -s src_id2
带引用的对话
notebooklm ask "question" --json
获取资源全文
notebooklm source fulltext <source_id>
获取资源指南
notebooklm source guide <source_id>
生成播客
notebooklm generate audio "instructions"
生成播客（JSON格式）
notebooklm generate audio --json
指定资源生成播客
notebooklm generate audio -s src_id1 -s src_id2
生成视频
notebooklm generate video "instructions"
生成测验
notebooklm generate quiz
检查成果物状态
notebooklm artifact list
等待成果物完成
notebooklm artifact wait <artifact_id>
下载音频
notebooklm download audio ./output.mp3
下载视频
notebooklm download video ./output.mp4
下载报告
notebooklm download report ./report.md
下载思维导图
notebooklm download mind-map ./map.json
下载数据表
notebooklm download data-table ./data.csv
下载测验
notebooklm download quiz quiz.json
下载测验（Markdown格式）
notebooklm download quiz --format markdown quiz.md
下载抽认卡
notebooklm download flashcards cards.json
下载抽认卡（Markdown格式）
notebooklm download flashcards --format markdown cards.md
删除笔记本
notebooklm notebook delete <id>
并行工作流安全提示： 在并行工作流中使用明确的笔记本ID。支持
-n
简写的命令：
artifact wait
、
source wait
、
research wait/status
、
download *
。下载命令还支持
-a/--artifact
。其他命令使用
--notebook
。对话时使用
--new
开启新对话（避免对话ID冲突）。
部分ID使用： 使用UUID的前6个以上字符。必须是唯一前缀（如果有歧义则会失败）。适用于：
use
、
delete
、
wait
命令。在自动化中，优先使用完整UUID以避免歧义。

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
Extract IDs: Parse the 
id
, 
source_id
, or 
task_id
field from JSON output.
带
--json
参数的命令返回结构化数据以便解析：
创建笔记本：
$ notebooklm create "Research" --json
{"id": "abc123de-...", "title": "Research"}
添加资源：
$ notebooklm source add "https://example.com" --json
{"source_id": "def456...", "title": "Example", "status": "processing"}
生成成果物：
$ notebooklm generate audio "Focus on key points" --json
{"task_id": "xyz789...", "status": "pending"}
带引用的对话：
$ 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..."}]}
获取资源全文（已索引内容）：
$ notebooklm source fulltext <source_id> --json
{"source_id": "...", "title": "...", "char_count": 12345, "content": "Full indexed text..."}
引用说明： 引用中的
cited_text
通常是片段或章节标题，而非完整引用段落。
start_char
/
end_char
位置指向NotebookLM的内部分块索引，而非原始全文。使用
SourceFulltext.find_citation_context()
定位引用：
python
fulltext = await client.sources.get_fulltext(notebook_id, ref.source_id)
matches = fulltext.find_citation_context(ref.cited_text)  # 返回列表[(context, position)]
if matches:
    context, pos = matches[0]  # 第一个匹配项；如果matches长度大于1则检查重复项
提取ID： 从JSON输出中解析
id
、
source_id
或
task_id
字段。

Generation Types

生成类型

All generate commands support:
  • -s, --source
    to use specific source(s) instead of all sources
  • --json
    for machine-readable output (returns 
    task_id
    and 
    status
    )
TypeCommandDownloadable
Podcast
generate audio
Yes (.mp3)
Video
generate video
Yes (.mp4)
Slides
generate slide-deck
Yes (.pdf)
Infographic
generate infographic
Yes (.png)
Report
generate report
Yes (.md)
Mind Map
generate mind-map
Yes (.json)
Data Table
generate data-table
Yes (.csv)
Quiz
generate quiz
Yes (.json/.md/.html)
Flashcards
generate flashcards
Yes (.json/.md/.html)
所有生成命令支持：
  • -s, --source
    使用特定资源而非全部资源
  • --json
    生成机器可读输出（返回
    task_id
    和
    status
    ）
类型命令可下载
播客
generate audio
是（.mp3）
视频
generate video
是（.mp4）
幻灯片
generate slide-deck
是（.pdf）
信息图
generate infographic
是（.png）
报告
generate report
是（.md）
思维导图
generate mind-map
是（.json）
数据表
generate data-table
是（.csv）
测验
generate quiz
是（.json/.md/.html）
抽认卡
generate flashcards
是（.json/.md/.html）

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)
时间： 总计5-10分钟
  1. notebooklm create "Research: [topic]"
    — 如果失败：使用
    notebooklm login
    检查身份验证
  2. 为每个URL/文档运行
    notebooklm source add
    — 如果某个失败：记录警告，继续处理其他资源
  3. 等待资源处理完成：
    notebooklm source list --json
    直到所有状态=READY — 生成前必须完成
  4. notebooklm generate audio "Focus on [specific angle]"
    （运行前需确认） — 如果触发速率限制：等待5分钟，重试一次
  5. 记录返回的成果物ID
  6. 稍后运行
    notebooklm artifact list
    检查状态
  7. 完成后运行
    notebooklm download audio ./podcast.mp3
    （运行前需确认）

Research to Podcast (Automated with Subagent)

研究到播客（使用子Agent自动化）

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
时间： 5-10分钟，但在后台运行
当用户需要完全自动化（生成完成后自动下载）：
  1. 按常规方式创建笔记本并添加资源
  2. 等待资源处理完成（使用
    source wait
    或检查
    source list --json
    ）
  3. 运行
    notebooklm generate audio "..." --json
    → 从输出中解析
    artifact_id
  4. 使用Task工具启动后台Agent： 
    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. 主对话继续进行，同时Agent在后台等待
子Agent中的错误处理：
  • 如果
    artifact wait
    返回退出码2（超时）：报告超时，建议检查
    artifact list
  • 如果下载失败：先检查成果物状态是否为COMPLETED
优势： 非阻塞，用户可进行其他操作，完成后自动下载

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
时间： 1-2分钟
  1. notebooklm create "Analysis: [project]"
  2. notebooklm source add ./doc.pdf
    （或URL）
  3. notebooklm ask "Summarize the key points"
  4. notebooklm ask "What are the main arguments?"
  5. 根据需要继续对话

Bulk Import

批量导入

Time: Varies by source count
  1. notebooklm create "Collection: [name]"
  2. Add multiple sources:
    bash
    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: Max 50 sources per notebook Supported types: PDFs, YouTube URLs, web URLs, Google Docs, text files
时间： 因资源数量而异
  1. notebooklm create "Collection: [name]"
  2. 添加多个资源：
    bash
    notebooklm source add "https://url1.com"
notebooklm source add "https://url2.com"
notebooklm source add ./local-file.pdf
  3. notebooklm source list
    验证导入结果
资源限制： 每个笔记本最多50个资源 支持类型： PDF、YouTube URL、网页URL、Google Docs、文本文件

Bulk Import with Source Waiting (Subagent Pattern)

带资源等待的批量导入（子Agent模式）

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:
    bash
    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.
时间： 因资源数量而异
当添加多个资源并需要等待处理完成后再进行对话/生成时：
  1. 使用
    --json
    参数添加资源以捕获ID：
    bash
    notebooklm source add "https://url1.com" --json  # → {"source_id": "abc..."}
notebooklm source add "https://url2.com" --json  # → {"source_id": "def..."}
  2. 启动后台Agent等待所有资源处理完成： 
    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. 主对话继续进行，同时Agent在后台等待
  4. 资源处理完成后，继续进行对话或生成
为什么要等待资源？ 资源必须先完成索引才能进行对话或生成。每个资源需要10-60秒。

Deep Web Research (Subagent Pattern)

深度网页研究（子Agent模式）

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):
    bash
    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
:
bash
notebooklm source add-research "topic" --mode deep --import-all
时间： 2-5分钟，在后台运行
深度研究可查找并分析关于某个主题的网页资源：
  1. 创建笔记本：
    notebooklm create "Research: [topic]"
  2. 启动深度研究（非阻塞）：
    bash
    notebooklm source add-research "topic query" --mode deep --no-wait
  3. 启动后台Agent等待并导入资源： 
    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. 主对话继续进行，同时Agent在后台等待
  5. Agent完成后，资源会自动导入
替代方案（阻塞）： 对于简单场景，省略
--no-wait
：
bash
notebooklm source add-research "topic" --mode deep --import-all

Blocks for up to 5 minutes

最多阻塞5分钟


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

**模式选择：**
- `--mode fast`：特定主题，需要快速概述（5-10个资源，数秒完成）
- `--mode deep`：广泛主题，需要全面分析（20+个资源，2-5分钟完成）

**研究来源：**
- `--from web`：搜索网页（默认）
- `--from drive`：搜索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:
bash
notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json
JSON schemas (key fields):
notebooklm list --json
:
json
{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}
notebooklm auth check --json
:
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
:
json
{"sources": [{"id": "...", "title": "...", "status": "ready|processing|error"}]}
notebooklm artifact list --json
:
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
    )
进度更新： 每个步骤的简要状态
  • "正在创建笔记本'研究：AI'..."
  • "正在添加资源：https://example.com..."
  • "开始生成音频...（任务ID：abc123）"
长操作的即发即忘模式：
  • 启动生成后立即返回成果物ID
  • 不要在主对话中轮询或等待 - 生成需要5-45分钟（见时间表格）
  • 用户可手动检查状态，或使用子Agent的
    artifact wait
JSON输出： 使用
--json
标志获取机器可读输出：
bash
notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json
JSON模式（关键字段）：
notebooklm list --json
:
json
{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}
notebooklm auth check --json
:
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
:
json
{"sources": [{"id": "...", "title": "...", "status": "ready|processing|error"}]}
notebooklm artifact list --json
:
json
{"artifacts": [{"id": "...", "title": "...", "type": "Audio Overview", "status": "in_progress|pending|completed|unknown"}]}
状态值：
  • 资源：
    processing
    → 
    ready
    （或
    error
    ）
  • 成果物：
    pending
    或
    in_progress
    → 
    completed
    （或
    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:
ErrorCauseAction
Auth/cookie errorSession expiredRun 
notebooklm auth check
then 
notebooklm login
"No notebook context"Context not setUse 
-n <id>
or 
--notebook <id>
flag (parallel), or 
notebooklm use <id>
(single-agent)
"No result found for RPC ID"Rate limitingWait 5-10 min, retry
GENERATION_FAILED
Google rate limitWait and retry later
Download failsGeneration incompleteCheck 
artifact list
for status
Invalid notebook/source IDWrong IDRun 
notebooklm list
to verify
RPC protocol errorGoogle changed APIsMay need CLI update
操作失败时，为用户提供选择：
  1. 重试操作
  2. 跳过并继续其他操作
  3. 调查错误原因
错误决策树：
错误原因操作
身份验证/ cookie错误会话过期运行
notebooklm auth check
然后
notebooklm login
"No notebook context"未设置上下文使用
-n <id>
或
--notebook <id>
标志（并行工作流），或
notebooklm use <id>
（单Agent）
"No result found for RPC ID"速率限制等待5-10分钟后重试
GENERATION_FAILED
Google速率限制稍后重试
下载失败生成未完成检查
artifact list
中的状态
无效的笔记本/资源IDID错误运行
notebooklm list
验证
RPC协议错误Google更改了API可能需要更新CLI

Exit Codes

退出码

All commands use consistent exit codes:
CodeMeaningAction
0SuccessContinue
1Error (not found, processing failed)Check stderr, see Error Handling
2Timeout (wait commands only)Extend timeout or check status manually
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)
所有命令使用一致的退出码：
代码含义操作
0成功继续
1错误（未找到、处理失败）检查stderr，参考错误处理部分
2超时（仅适用于wait命令）延长超时时间或手动检查状态
示例：
  • source wait
    如果资源未找到或处理失败返回1
  • artifact wait
    如果在完成前超时返回2
  • generate
    如果触发速率限制返回1（查看stderr获取详细信息）

Known Limitations

已知限制

Rate limiting: Audio, video, quiz, flashcards, infographic, and slides 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, FAQ, data-table generation
Unreliable operations: These may fail with rate limiting:
  • Audio (podcast) generation
  • Video generation
  • Quiz and flashcard generation
  • Infographic and slides 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:
OperationTypical timeSuggested timeout
Source processing30s - 10 min600s
Research (fast)30s - 2 min180s
Research (deep)15 - 30+ min1800s
Notesinstantn/a
Mind-mapinstant (sync)n/a
Quiz, flashcards5 - 15 min900s
Report, data-table5 - 15 min900s
Audio generation10 - 20 min1200s
Video generation15 - 45 min2700s
Polling intervals: When checking status manually, poll every 15-30 seconds to avoid excessive API calls.
速率限制： 音频、视频、测验、抽认卡、信息图和幻灯片生成可能因Google的速率限制而失败。这是API限制，而非bug。
可靠操作： 以下操作始终可用：
  • 笔记本（列出、创建、删除、重命名）
  • 资源（添加、列出、删除）
  • 对话/查询
  • 思维导图、学习指南、FAQ、数据表生成
不可靠操作： 以下操作可能因速率限制失败：
  • 音频（播客）生成
  • 视频生成
  • 测验和抽认卡生成
  • 信息图和幻灯片生成
解决方法： 如果生成失败：
  1. 检查状态：
    notebooklm artifact list
  2. 5-10分钟后重试
  3. 作为回退使用NotebookLM网页UI
处理时间差异很大。 对长操作使用子Agent模式：
操作典型时间建议超时时间
资源处理30秒 - 10分钟600秒
快速研究30秒 - 2分钟180秒
深度研究15 - 30+分钟1800秒
笔记即时n/a
思维导图即时（同步）n/a
测验、抽认卡5 - 15分钟900秒
报告、数据表5 - 15分钟900秒
音频生成10 - 20分钟1200秒
视频生成15 - 45分钟2700秒
轮询间隔： 手动检查状态时，每15-30秒轮询一次，避免过多API调用。

Troubleshooting

故障排除

bash
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
Diagnose auth: 
notebooklm auth check
- shows cookie domains, storage path, validation status Re-authenticate: 
notebooklm login
Check version: 
notebooklm --version
Update skill: 
notebooklm skill install
bash
notebooklm --help              # 主命令帮助
notebooklm auth check          # 诊断身份验证问题
notebooklm auth check --test   # 完整身份验证验证（含网络测试）
notebooklm notebook --help     # 笔记本管理帮助
notebooklm source --help       # 资源管理帮助
notebooklm research --help     # 研究状态/等待帮助
notebooklm generate --help     # 内容生成帮助
notebooklm artifact --help     # 成果物管理帮助
notebooklm download --help     # 下载内容帮助
诊断身份验证： 
notebooklm auth check
- 显示cookie域、存储路径、验证状态 重新身份验证： 
notebooklm login
检查版本： 
notebooklm --version
更新技能： 
notebooklm skill install