notebooklm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NotebookLM Automation

NotebookLM 自动化

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.

实现对Google NotebookLM的全程序化访问——包括网页UI未公开的功能。可创建笔记本、添加来源（URL、YouTube、PDF、音频、视频、图片）、与内容对话、生成所有类型的成果物，并以多种格式下载结果。

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:

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:

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

Per-agent isolation: Set unique

NOTEBOOKLM_HOME

per agent:

export NOTEBOOKLM_HOME=/tmp/agent-$ID

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

可能会覆盖彼此的上下文。

并行工作流解决方案：

始终使用明确的笔记本ID（推荐）：传递
```
-n <notebook_id>
```
（用于
```
wait
```
/
```
download
```
命令）或
```
--notebook <notebook_id>
```
（用于其他命令），而不是依赖
```
use
```
**Agent级隔离：**为每个Agent设置唯一的
```
NOTEBOOKLM_HOME
```
：
```
export NOTEBOOKLM_HOME=/tmp/agent-$ID
```
**使用完整UUID：**在自动化中避免使用部分ID（它们可能会变得模糊）

Agent Setup Verification

Agent设置验证

Before starting workflows, verify the CLI is ready:

```
notebooklm status
```
→ Should show "Authenticated as: email@..."
```
notebooklm list --json
```
→ Should return valid JSON (even if empty notebooks list)
If either fails → Run
```
notebooklm login
```

在开始工作流之前，请验证CLI是否准备就绪：

```
notebooklm status
```
→ 应显示“Authenticated as: email@...”
```
notebooklm list --json
```
→ 应返回有效的JSON（即使笔记本列表为空）
如果任一命令失败 → 运行
```
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"

**明确触发：**用户说出"/notebooklm"、"use notebooklm"或提及该工具名称

**意图检测：**识别以下类似请求：

"创建关于[主题]的播客"
"总结这些URL/文档"
"从我的研究生成测验"
"将此转换为音频概述"
"创建学习用抽认卡"
"生成视频讲解"
"制作信息图"
"创建概念思维导图"
"以markdown格式下载测验"
"将这些来源添加到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
```
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 language list
```
- 列出支持的语言
```
notebooklm language get
```
- 获取当前语言
```
notebooklm language set
```
- 设置语言（全局设置）
```
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

快速参考

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

--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>`
列出支持语言	`notebooklm language list`
获取当前语言	`notebooklm language get`
设置语言	`notebooklm language set zh_Hans`

**并行安全：**在并行工作流中使用明确的笔记本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
```
--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

Type	Command	Options	Download
Podcast	`generate audio`	`--format [deep-dive\|brief\|critique\|debate]` , `--length [short\|default\|long]`	.mp3
Video	`generate video`	`--format [explainer\|brief]` , `--style [auto\|classic\|whiteboard\|kawaii\|anime\|watercolor\|retro-print\|heritage\|paper-craft]`	.mp4
Slide Deck	`generate slide-deck`	`--format [detailed\|presenter]` , `--length [default\|short]`	.pdf
Infographic	`generate infographic`	`--orientation [landscape\|portrait\|square]` , `--detail [concise\|standard\|detailed]`	.png
Report	`generate report`	`--format [briefing-doc\|study-guide\|blog-post\|custom]`	.md
Mind Map	`generate mind-map`	(sync, instant)	.json
Data Table	`generate data-table`	description required	.csv
Quiz	`generate quiz`	`--difficulty [easy\|medium\|hard]` , `--quantity [fewer\|standard\|more]`	.json/.md/.html
Flashcards	`generate flashcards`	`--difficulty [easy\|medium\|hard]` , `--quantity [fewer\|standard\|more]`	.json/.md/.html

所有生成命令支持：

```
-s, --source
```
使用特定来源而非所有来源
```
--language
```
设置输出语言（默认为配置语言或'en'）
```
--json
```
机器可读输出（返回
```
task_id
```
和
```
status
```
）
```
--retry N
```
遇到速率限制时自动重试，使用指数退避策略

类型	命令	选项	下载格式
播客	`generate audio`	`--format [deep-dive\|brief\|critique\|debate]` , `--length [short\|default\|long]`	.mp3
视频	`generate video`	`--format [explainer\|brief]` , `--style [auto\|classic\|whiteboard\|kawaii\|anime\|watercolor\|retro-print\|heritage\|paper-craft]`	.mp4
幻灯片	`generate slide-deck`	`--format [detailed\|presenter]` , `--length [default\|short]`	.pdf
信息图	`generate infographic`	`--orientation [landscape\|portrait\|square]` , `--detail [concise\|standard\|detailed]`	.png
报告	`generate report`	`--format [briefing-doc\|study-guide\|blog-post\|custom]`	.md
思维导图	`generate mind-map`	同步，即时生成	.json
数据表	`generate data-table`	需要描述	.csv
测验	`generate quiz`	`--difficulty [easy\|medium\|hard]` , `--quantity [fewer\|standard\|more]`	.json/.md/.html
抽认卡	`generate flashcards`	`--difficulty [easy\|medium\|hard]` , `--quantity [fewer\|standard\|more]`	.json/.md/.html

Features Beyond the Web UI

超出网页UI的功能

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

Feature	Command	Description
Batch downloads	`download <type> --all`	Download all artifacts of a type at once
Quiz/Flashcard export	`download quiz --format json`	Export as JSON, Markdown, or HTML (web UI only shows interactive view)
Mind map extraction	`download mind-map`	Export hierarchical JSON for visualization tools
Data table export	`download data-table`	Download structured tables as CSV
Source fulltext	`source fulltext <id>`	Retrieve the indexed text content of any source
Programmatic sharing	`share` commands	Manage sharing permissions without the UI

以下功能可通过CLI实现，但NotebookLM网页界面不支持：

功能	命令	描述
批量下载	`download <type> --all`	一次性下载所有指定类型的成果物
测验/抽认卡导出	`download quiz --format json`	导出为JSON、Markdown或HTML格式（网页UI仅显示交互式视图）
思维导图提取	`download mind-map`	导出分层JSON格式以便在可视化工具中使用
数据表导出	`download data-table`	以CSV格式下载结构化表格
来源全文获取	`source fulltext <id>`	获取任何来源的索引文本内容
程序化共享	`share` 命令	无需UI即可管理共享权限

Common Workflows

常见工作流

Research to Podcast (Interactive)

研究到播客（交互式）

Time: 5-10 minutes total

notebooklm create "Research: [topic]"

— if fails: check auth with
notebooklm login

```
notebooklm source add
```
for each URL/document — if one fails: log warning, continue with others
Wait for sources:
```
notebooklm source list --json
```
until all status=READY — required before generation
```
notebooklm generate audio "Focus on [specific angle]"
```
(confirm when asked) — if rate limited: wait 5 min, retry once
Note the artifact ID returned
Check
```
notebooklm artifact list
```
later for status
```
notebooklm download audio ./podcast.mp3
```
when complete (confirm when asked)

**时间：**总计5-10分钟

notebooklm create "Research: [topic]"

— 如果失败：使用
notebooklm login
检查身份验证

为每个URL/文档运行
```
notebooklm source add
```
— 如果某一个失败：记录警告，继续添加其他来源
等待来源处理完成：
```
notebooklm source list --json
```
直到所有状态=READY — 生成前必须完成
```
notebooklm generate audio "Focus on [specific angle]"
```
（提示时确认） — 如果遇到速率限制：等待5分钟后重试一次
记录返回的成果物ID
稍后运行
```
notebooklm artifact list
```
检查状态
完成后运行
```
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):

Create notebook and add sources as usual
Wait for sources to be ready (use
```
source wait
```
or check
```
source list --json
```
)

Run

notebooklm generate audio "..." --json

→ parse

artifact_id

from output

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

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分钟，但在后台运行

当用户需要完全自动化（生成完成后自动下载）：

按常规步骤创建笔记本并添加来源
等待来源处理完成（使用
```
source wait
```
或检查
```
source list --json
```
）

运行

notebooklm generate audio "..." --json

→ 从输出中解析

artifact_id

使用Task工具启动后台Agent：

Task(
  prompt="等待笔记本{notebook_id}中的成果物{artifact_id}完成，然后下载。
          使用命令：notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
          然后运行：notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}",
  subagent_type="general-purpose"
)

主对话继续进行，同时Agent在后台等待

子Agent中的错误处理：

如果
```
artifact wait
```
返回退出码2（超时）：报告超时，建议检查
```
artifact list
```
如果下载失败：先检查成果物状态是否为COMPLETED

**优势：**非阻塞，用户可进行其他操作，完成后自动下载

Document Analysis

文档分析

Time: 1-2 minutes

```
notebooklm create "Analysis: [project]"
```
```
notebooklm source add ./doc.pdf
```
(or URLs)

notebooklm ask "Summarize the key points"

notebooklm ask "What are the main arguments?"

Continue chatting as needed

**时间：**1-2分钟

```
notebooklm create "Analysis: [project]"
```
```
notebooklm source add ./doc.pdf
```
（或URL）

notebooklm ask "Summarize the key points"

notebooklm ask "What are the main arguments?"

根据需要继续聊天

Bulk Import

批量导入

Time: Varies by source count

```
notebooklm create "Collection: [name]"
```

Add multiple sources:

bash

notebooklm source add "https://url1.com"
notebooklm source add "https://url2.com"
notebooklm source add ./local-file.pdf

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

**时间：**根据来源数量而定

```
notebooklm create "Collection: [name]"
```

添加多个来源：

bash

notebooklm source add "https://url1.com"
notebooklm source add "https://url2.com"
notebooklm source add ./local-file.pdf

```
notebooklm source list
```
验证

**来源限制：**根据套餐不同而变化——标准版：50个，增强版：100个，专业版：300个，旗舰版：600个来源/笔记本。详情请查看NotebookLM套餐。CLI不强制执行这些限制，由您的NotebookLM账户应用限制。 **支持的类型：**PDF、YouTube URL、网页URL、Google Docs、文本文件、Markdown、Word文档、音频文件、视频文件、图片

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:

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

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

Main conversation continues while agent waits
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.

**时间：**根据来源数量而定

当添加多个来源且需要等待处理完成后再进行聊天/生成时：

使用

--json

添加来源以捕获ID：

bash

notebooklm source add "https://url1.com" --json  # → {"source_id": "abc..."}
notebooklm source add "https://url2.com" --json  # → {"source_id": "def..."}

启动后台Agent等待所有来源处理完成：

Task(
  prompt="等待笔记本{notebook_id}中的来源{source_ids}处理完成。
          对每个来源运行：notebooklm source wait {id} -n {notebook_id} --timeout 120
          当所有来源就绪或有任何失败时进行报告。",
  subagent_type="general-purpose"
)

主对话继续进行，同时Agent在后台等待
来源就绪后，继续进行聊天或生成

**为什么要等待来源？**来源必须完成索引后才能进行聊天或生成。每个来源需要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:

Create notebook:
```
notebooklm create "Research: [topic]"
```

Start deep research (non-blocking):

bash

notebooklm source add-research "topic query" --mode deep --no-wait

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

Main conversation continues while agent waits
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分钟，在后台运行

深度研究可查找并分析关于某个主题的网页来源：

创建笔记本：
```
notebooklm create "Research: [topic]"
```

启动深度研究（非阻塞）：

bash

notebooklm source add-research "topic query" --mode deep --no-wait

启动后台Agent等待并导入来源：

Task(
  prompt="等待笔记本{notebook_id}中的研究完成并导入来源。
          使用命令：notebooklm research wait -n {notebook_id} --import-all --timeout 300
          报告导入的来源数量。",
  subagent_type="general-purpose"
)

主对话继续进行，同时Agent在后台等待
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
```
)

**进度更新：**每个步骤的简要状态

"正在创建笔记本'Research: 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:

Retry the operation
Skip and continue with something else
Investigate the error

Error decision tree:

Error	Cause	Action
Auth/cookie error	Session expired	Run `notebooklm auth check` then `notebooklm login`
"No notebook context"	Context not set	Use `-n <id>` or `--notebook <id>` flag (parallel), or `notebooklm use <id>` (single-agent)
"No result found for RPC ID"	Rate limiting	Wait 5-10 min, retry
`GENERATION_FAILED`	Google rate limit	Wait and retry later
Download fails	Generation incomplete	Check `artifact list` for status
Invalid notebook/source ID	Wrong ID	Run `notebooklm list` to verify
RPC protocol error	Google changed APIs	May need CLI update

失败时，为用户提供选择：

重试操作
跳过并继续其他操作
调查错误原因

错误决策树：

错误	原因	操作
身份验证/ 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` 查看状态
无效的笔记本/来源ID	ID错误	运行 `notebooklm list` 验证
RPC协议错误	Google更改了API	可能需要更新CLI

Exit Codes

退出码

All commands use consistent exit codes:

Code	Meaning	Action
0	Success	Continue
1	Error (not found, processing failed)	Check stderr, see Error Handling
2	Timeout (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 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:

Check status:
```
notebooklm artifact list
```
Retry after 5-10 minutes
Use the NotebookLM web UI as fallback

Processing times vary significantly. Use the subagent pattern for long operations:

Operation	Typical time	Suggested timeout
Source processing	30s - 10 min	600s
Research (fast)	30s - 2 min	180s
Research (deep)	15 - 30+ min	1800s
Notes	instant	n/a
Mind-map	instant (sync)	n/a
Quiz, flashcards	5 - 15 min	900s
Report, data-table	5 - 15 min	900s
Audio generation	10 - 20 min	1200s
Video generation	15 - 45 min	2700s

Polling intervals: When checking status manually, poll every 15-30 seconds to avoid excessive API calls.

**速率限制：**音频、视频、测验、抽认卡、信息图和幻灯片生成可能因Google的速率限制而失败。这是API限制，而非bug。

**可靠操作：**这些操作始终有效：

笔记本（列出、创建、删除、重命名）
来源（添加、列出、删除）
聊天/查询
思维导图、学习指南、报告、数据表生成

**不可靠操作：**这些操作可能因速率限制失败：

音频（播客）生成
视频生成
测验和抽认卡生成
信息图和幻灯片生成

**解决方法：**如果生成失败：

检查状态：
```
notebooklm artifact list
```
5-10分钟后重试
作为回退方案使用NotebookLM网页UI

**处理时间差异很大。**长时操作使用子Agent模式：

操作	典型时间	建议超时时间
来源处理	30秒 - 10分钟	600秒
快速研究	30秒 - 2分钟	180秒
深度研究	15 - 30+分钟	1800秒
笔记	即时	不适用
思维导图	即时（同步）	不适用
测验、抽认卡	5 - 15分钟	900秒
报告、数据表	5 - 15分钟	900秒
音频生成	10 - 20分钟	1200秒
视频生成	15 - 45分钟	2700秒

**轮询间隔：**手动检查状态时，每15-30秒轮询一次，避免过多API调用。

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.

bash

undefined

语言设置控制生成成果物（音频、视频等）的输出语言。

重要提示：语言是全局设置，会影响您账户中的所有笔记本。

bash

undefined

List all 80+ supported languages with native names

列出80+种支持的语言及本地名称

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:**
| Code | Language |
|------|----------|
| `en` | English |
| `zh_Hans` | 中文（简体） - Simplified Chinese |
| `zh_Hant` | 中文（繁體） - Traditional Chinese |
| `ja` | 日本語 - Japanese |
| `ko` | 한국어 - Korean |
| `es` | Español - Spanish |
| `fr` | Français - French |
| `de` | Deutsch - German |
| `pt_BR` | Português (Brasil) |

**Override per command:** Use `--language` flag on generate commands:
```bash
notebooklm generate audio --language ja   # Japanese podcast
notebooklm generate video --language zh_Hans  # Chinese video

Offline mode: Use

--local

flag to skip server sync:

bash

notebooklm language set zh_Hans --local  # Save locally only
notebooklm language get --local  # Read local config only

notebooklm language set zh_Hans # 简体中文 notebooklm language set ja # 日语 notebooklm language set en # 英语（默认）


**常用语言代码：**
| 代码 | 语言 |
|------|----------|
| `en` | 英语 |
| `zh_Hans` | 中文（简体） |
| `zh_Hant` | 中文（繁體） |
| `ja` | 日本語 |
| `ko` | 한국어 |
| `es` | Español - 西班牙语 |
| `fr` | Français - 法语 |
| `de` | Deutsch - 德语 |
| `pt_BR` | Português (Brasil) - 巴西葡萄牙语 |

**按命令覆盖：**在生成命令中使用`--language`标志：
```bash
notebooklm generate audio --language ja   # 日语播客
notebooklm generate video --language zh_Hans  # 中文视频

**离线模式：**使用

--local

标志跳过服务器同步：

bash

notebooklm language set zh_Hans --local  # 仅本地保存
notebooklm language get --local  # 仅读取本地配置

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
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 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 language --help     # 语言设置帮助

诊断身份验证：

notebooklm auth check

- 显示cookie域、存储路径、验证状态 重新验证：

notebooklm login

检查版本：

notebooklm --version

更新技能：

notebooklm skill install