notebooklm by teng-lin/notebooklm-py
npx skills add https://github.com/teng-lin/notebooklm-py --skill notebooklm实现对 Google NotebookLM 的完整程序化访问——包括 Web 界面中未公开的功能。创建笔记本、添加来源(URL、YouTube、PDF、音频、视频、图像)、与内容聊天、生成所有工件类型,并以多种格式下载结果。
从 PyPI 安装(推荐):
pip install notebooklm-py
从 GitHub 安装(使用最新的发布标签,而非 main 分支):
# 获取最新的发布标签(使用 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}"
⚠️ 请勿从 main 分支安装 (pip install git+https://github.com/teng-lin/notebooklm-py)。main 分支可能包含未发布/不稳定的更改。除非您正在测试未发布的功能,否则请始终使用 PyPI 或特定的发布标签。
技能安装方法:
notebooklm skill install 将此技能安装到 CLI 管理的受支持本地代理目录中。npx skills add teng-lin/notebooklm-py 将此技能从 GitHub 仓库安装到兼容的代理技能目录中。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
CLI 管理的安装:
notebooklm skill install
重要提示: 在使用任何命令之前,您必须进行身份验证:
notebooklm login # 打开浏览器进行 Google OAuth 认证
notebooklm list # 验证身份验证是否有效
如果命令因身份验证错误而失败,请重新运行 notebooklm login。
对于自动化环境、多账户或并行代理工作流:
| 变量 | 用途 |
|---|---|
NOTEBOOKLM_HOME | 自定义配置目录(默认:~/.notebooklm) |
NOTEBOOKLM_AUTH_JSON | 内联身份验证 JSON - 无需写入文件 |
CI/CD 设置: 从包含您 storage_state.json 内容的密钥设置 NOTEBOOKLM_AUTH_JSON。
多账户: 为每个账户使用不同的 NOTEBOOKLM_HOME 目录。
并行代理: CLI 将笔记本上下文存储在共享文件 (~/.notebooklm/context.json) 中。多个并发代理使用 notebooklm use 可能会相互覆盖上下文。
并行工作流的解决方案:
-n <notebook_id>(用于 wait/download 命令)或 --notebook <notebook_id>(用于其他命令),而不是依赖 use。NOTEBOOKLM_HOME:export NOTEBOOKLM_HOME=/tmp/agent-$ID在开始工作流之前,验证 CLI 是否准备就绪:
notebooklm status → 应显示 "Authenticated as: email@..."notebooklm list --json → 应返回有效的 JSON(即使笔记本列表为空)notebooklm login显式激活: 用户说 "/notebooklm"、"use notebooklm" 或提及工具名称
意图检测: 识别以下请求:
自动运行(无需确认):
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 - 等待工件完成(在子代理上下文中)notebooklm source wait - 等待来源处理(在子代理上下文中)notebooklm research status - 检查研究状态notebooklm research wait - 等待研究(在子代理上下文中)notebooklm use <id> - 设置上下文(⚠️ 仅限单代理 - 在并行工作流中使用 -n 标志)notebooklm create - 创建笔记本notebooklm ask "..." - 聊天查询(不带 --save-as-note)notebooklm history - 显示对话历史记录(只读)notebooklm source add - 添加来源运行前询问:
notebooklm delete - 破坏性操作notebooklm generate * - 长时间运行,可能失败notebooklm download * - 写入文件系统notebooklm artifact wait - 长时间运行(在主对话中时)notebooklm source wait - 长时间运行(在主对话中时)notebooklm research wait - 长时间运行(在主对话中时)notebooklm ask "..." --save-as-note - 写入笔记notebooklm history --save - 写入笔记| 任务 | 命令 |
|---|---|
| 身份验证 | 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 |
| 按 ID 删除来源 | notebooklm source delete <source_id> |
| 按精确标题删除来源 | notebooklm source delete-by-title "Exact Title" |
| 等待来源处理 | 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" -s src_id1 -s src_id2 |
| 聊天(带引用) | notebooklm ask "question" --json |
| 聊天(将答案保存为笔记) | notebooklm ask "question" --save-as-note |
| 聊天(保存并指定标题) | notebooklm ask "question" --save-as-note --note-title "Title" |
| 显示对话历史记录 | notebooklm history |
| 将所有历史记录保存为笔记 | notebooklm history --save |
| 继续特定对话 | notebooklm ask "question" -c <conversation_id> |
| 保存历史记录并指定标题 | notebooklm history --save --note-title "My Research" |
| 获取来源全文 | 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 report --format briefing-doc |
| 生成报告(附加指令) | notebooklm generate report --format study-guide --append "Target audience: beginners" |
| 生成测验 | notebooklm generate quiz |
| 修订幻灯片 | notebooklm generate revise-slide "prompt" --artifact <id> --slide 0 |
| 检查工件状态 | notebooklm artifact list |
| 等待完成 | notebooklm artifact wait <artifact_id> |
| 下载音频 | notebooklm download audio ./output.mp3 |
| 下载视频 | notebooklm download video ./output.mp4 |
| 下载幻灯片(PDF) | notebooklm download slide-deck ./slides.pdf |
| 下载幻灯片(PPTX) | notebooklm download slide-deck ./slides.pptx --format pptx |
| 下载报告 | 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。对于聊天,使用 -c <conversation_id> 来定位特定对话。
部分 ID: 使用 UUID 的前 6 个或更多字符。必须是唯一的前缀(如果不明确则会失败)。适用于基于 ID 的命令,如 use、source delete 和 wait。对于精确的按标题删除来源,请使用 source delete-by-title "Title"。对于自动化,建议使用完整的 UUID 以避免歧义。
带有 --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() 来定位引用:
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
提取 ID: 从 JSON 输出中解析 id、source_id 或 task_id 字段。
所有生成命令都支持:
-s, --source 以使用特定来源而非所有来源--language 以设置输出语言(默认为配置的语言或 'en')--json 用于机器可读的输出(返回 task_id 和 status)--retry N 以在遇到速率限制时自动重试,并采用指数退避| 类型 | 命令 | 选项 | 下载 |
|---|---|---|---|
| 播客 | generate audio | `--format [deep-dive | brief |
| 视频 | generate video | `--format [explainer | brief], --style [auto |
| 幻灯片 | generate slide-deck | `--format [detailed | presenter], --length [default |
| 幻灯片修订 | generate revise-slide "prompt" --artifact <id> --slide N | --wait, --notebook | (重新下载父幻灯片) |
| 信息图 | generate infographic | `--orientation [landscape | portrait |
| 报告 | generate report | `--format [briefing-doc | study-guide |
| 思维导图 | generate mind-map | (同步,即时) | .json |
| 数据表 | generate data-table | 需要描述 | .csv |
| 测验 | generate quiz | `--difficulty [easy | medium |
| 抽认卡 | generate flashcards | `--difficulty [easy | medium |
这些功能可通过 CLI 使用,但在 NotebookLM 的 Web 界面中不可用:
| 功能 | 命令 | 描述 |
|---|---|---|
| 批量下载 | download <type> --all | 一次性下载某种类型的所有工件 |
| 测验/抽认卡导出 | download quiz --format json | 导出为 JSON、Markdown 或 HTML(Web 界面仅显示交互式视图) |
| 思维导图提取 | download mind-map | 导出为分层 JSON,用于可视化工具 |
| 数据表导出 | download data-table | 将结构化表格下载为 CSV |
| 幻灯片导出为 PPTX | download slide-deck --format pptx | 将幻灯片下载为可编辑的 .pptx 文件(Web 界面仅提供 PDF) |
| 幻灯片修订 | generate revise-slide "prompt" --artifact <id> --slide N | 使用自然语言提示修改单个幻灯片 |
| 报告模板附加 | generate report --format study-guide --append "..." | 将自定义指令附加到内置格式模板,而不会丢失格式类型 |
| 来源全文 | source fulltext <id> | 检索任何来源的索引文本内容 |
| 将聊天保存为笔记 | ask "..." --save-as-note / history --save | 将问答答案或对话历史记录保存为笔记本笔记 |
| 程序化共享 | share 命令 | 无需 UI 即可管理共享权限 |
时间: 总计 5-10 分钟
notebooklm create "Research: [topic]" — 如果失败:使用 notebooklm login 检查身份验证notebooklm source add 为每个 URL/文档 — 如果某个失败:记录警告,继续处理其他notebooklm source list --json 直到所有状态=READY — 生成前必需notebooklm generate audio "Focus on [specific angle]"(询问时确认) — 如果速率受限:等待 5 分钟,重试一次notebooklm artifact list 获取状态notebooklm download audio ./podcast.mp3 当完成时(询问时确认)时间: 5-10 分钟,但在后台继续
当用户想要完全自动化(生成并在就绪时下载):
照常创建笔记本并添加来源
等待来源就绪(使用 source wait 或检查 source list --json)
运行 notebooklm generate audio "..." --json → 从输出中解析 artifact_id
使用 Task 工具生成后台代理:
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"
)
主对话在代理等待时继续
子代理中的错误处理:
artifact wait 返回退出码 2(超时):报告超时,建议检查 artifact list优点: 非阻塞,用户可以处理其他工作,完成后自动下载
时间: 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?"时间: 根据来源数量而异
notebooklm create "Collection: [name]"
添加多个来源:
notebooklm source add "https://url1.com"
notebooklm source add "https://url2.com"
notebooklm source add ./local-file.pdf
notebooklm source list 以验证
来源限制: 因计划而异——标准版:50,Plus 版:100,Pro 版:300,Ultra 版:600 个来源/笔记本。详情请参阅 NotebookLM 计划。CLI 不强制执行这些限制;它们由您的 NotebookLM 账户应用。支持的类型: PDF、YouTube URL、网页 URL、Google 文档、文本文件、Markdown、Word 文档、音频文件、视频文件、图像
时间: 根据来源数量而异
当添加多个来源并需要在聊天/生成前等待处理时:
使用 --json 添加来源以捕获 ID:
notebooklm source add "https://url1.com" --json # → {"source_id": "abc..."}
notebooklm source add "https://url2.com" --json # → {"source_id": "def..."}
生成后台代理以等待所有来源:
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"
)
主对话在代理等待时继续
一旦来源就绪,继续聊天或生成
为什么要等待来源? 来源必须在聊天或生成前被索引。每个来源需要 10-60 秒。
时间: 2-5 分钟,在后台运行
深度研究查找并分析关于某个主题的网络来源:
创建笔记本:notebooklm create "Research: [topic]"
开始深度研究(非阻塞):
notebooklm source add-research "topic query" --mode deep --no-wait
生成后台代理以等待并导入:
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"
)
主对话在代理等待时继续
当代理完成时,来源会自动导入
替代方案(阻塞): 对于简单情况,省略 --no-wait:
notebooklm source add-research "topic" --mode deep --import-all
# 阻塞最多 5 分钟
何时使用每种模式:
--mode fast:特定主题,需要快速概览(5-10 个来源,几秒钟)--mode deep:广泛主题,需要全面分析(20+ 个来源,2-5 分钟)研究来源:
--from web:搜索网络(默认)--from drive:搜索 Google Drive进度更新: 每个步骤的简要状态
长时间操作的即发即弃:
artifact wait 的子代理JSON 输出: 使用 --json 标志获取机器可读的输出:
notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json
JSON 模式(关键字段):
notebooklm list --json:
{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}
notebooklm auth check --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:
{"sources": [{"id": "...", "title": "...", "status": "ready|processing|error"}]}
notebooklm artifact list --json:
{"artifacts": [{"id": "...", "title": "...", "type": "Audio Overview", "status": "in_progress|pending|completed|unknown"}]}
状态值:
processing → ready(或 error)pending 或 in_progress → completed(或 unknown)失败时,为用户提供选择:
错误决策树:
| 错误 | 原因 | 操作 |
|---|---|---|
| 身份验证/Cookie 错误 | 会话过期 | 运行 notebooklm auth check 然后 notebooklm login |
| "无笔记本上下文" | 上下文未设置 | 使用 -n <id> 或 --notebook <id> 标志(并行),或 notebooklm use <id>(单代理) |
| "未找到 RPC ID 的结果" | 速率限制 | 等待 5-10 分钟,重试 |
GENERATION_FAILED | Google 速率限制 | 稍后等待并重试 |
| 下载失败 | 生成未完成 | 检查 artifact list 获取状态 |
| 无效的笔记本/来源 ID | 错误的 ID | 运行 notebooklm list 以验证 |
| RPC 协议错误 | Google 更改了 API | 可能需要 CLI 更新 |
所有命令使用一致的退出码:
| 代码 | 含义 | 操作 |
|---|---|---|
| 0 | 成功 | 继续 |
| 1 | 错误(未找到,处理失败) | 检查 stderr,参见错误处理 |
| 2 | 超时(仅限等待命令) | 延长超时时间或手动检查状态 |
示例:
source wait 如果来源未找到或处理失败,则返回 1artifact wait 如果在完成前达到超时,则返回 2generate 如果速率受限,则返回 1(检查 stderr 获取详情)速率限制: 音频、视频、测验、抽认卡、信息图和幻灯片生成可能因 Google 的速率限制而失败。这是 API 限制,而非错误。
可靠操作: 这些始终有效:
不可靠操作: 这些可能因速率限制而失败:
解决方法: 如果生成失败:
notebooklm artifact list处理时间差异很大。 对于长时间操作,请使用子代理模式:
| 操作 | 典型时间 | 建议超时 |
|---|---|---|
| 来源处理 | 30秒 - 10 分钟 | 600秒 |
| 研究(快速) | 30秒 - 2 分钟 | 180秒 |
| 研究(深度) | 15 - 30+ 分钟 | 1800秒 |
| 笔记 | 即时 | 不适用 |
| 思维导图 | 即时(同步) | 不适用 |
| 测验,抽认卡 | 5 - 15 分钟 | 900秒 |
| 报告,数据表 | 5 - 15 分钟 | 900秒 |
| 音频生成 | 10 - 20 分钟 | 1200秒 |
| 视频生成 | 15 - 45 分钟 | 2700秒 |
轮询间隔: 手动检查状态时,每 15-30 秒轮询一次,以避免过多的 API 调用。
语言设置控制生成工件(音频、视频等)的输出语言。
重要提示: 语言是一个全局设置,会影响您账户中的所有笔记本。
# 列出所有 80+ 种支持的语言及其本地名称
notebooklm language list
# 显示当前语言设置
notebooklm language get
# 为工件生成设置语言
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 标志:
notebooklm generate audio --language ja # 日语播客
notebooklm generate video --language zh_Hans # 中文视频
离线模式: 使用 --local 标志跳过服务器同步:
notebooklm language set zh_Hans --local # 仅本地保存
notebooklm language get --local # 仅读取本地配置
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 刷新 CLI 管理的安装: notebooklm skill install
每周安装次数
934
仓库
GitHub Stars
7.5K
首次出现
Jan 21, 2026
安全审计
安装于
opencode903
codex893
gemini-cli891
cursor881
github-copilot863
kimi-cli848
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.
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.
Skill install methods:
notebooklm skill install installs this skill into the supported local agent directories managed by the CLI.npx skills add teng-lin/notebooklm-py installs this skill from the GitHub repository into compatible agent skill directories.CLI-managed install:
notebooklm skill install
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.
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:
-n <notebook_id> (for wait/download commands) or --notebook <notebook_id> (for others) instead of relying on useNOTEBOOKLM_HOME per agent: export NOTEBOOKLM_HOME=/tmp/agent-$IDBefore 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)notebooklm loginExplicit: User says "/notebooklm", "use notebooklm", or mentions the tool by name
Intent detection: Recognize requests like:
Run automatically (no confirmation):
notebooklm status - check contextnotebooklm auth check - diagnose auth issuesnotebooklm list - list notebooksnotebooklm source list - list sourcesnotebooklm artifact list - list artifactsnotebooklm language list - list supported languagesnotebooklm language get - get current languagenotebooklm language set - set language (global setting)notebooklm artifact wait - wait for artifact completion (in subagent context)Ask before running:
notebooklm delete - destructivenotebooklm generate * - long-running, may failnotebooklm download * - writes to filesystemnotebooklm 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 notenotebooklm history --save - writes a note| 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> |
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.
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:
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.
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 |
| Video | generate video | `--format [explainer | brief], --style [auto |
| Slide Deck | generate slide-deck | `--format [detailed | presenter], --length [default |
| Slide Revision |
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 |
Time: 5-10 minutes total
notebooklm create "Research: [topic]" — if fails: check auth withnotebooklm loginnotebooklm source add for each URL/document — if one fails: log warning, continue with othersnotebooklm source list --json until all status=READY — required before generationnotebooklm generate audio "Focus on [specific angle]" (confirm when asked) — if rate limited: wait 5 min, retry oncenotebooklm artifact list later for statusnotebooklm download audio ./podcast.mp3 when complete (confirm when asked)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:
artifact wait returns exit code 2 (timeout): Report timeout, suggest checking artifact listBenefits: Non-blocking, user can do other work, automatic download on completion
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?"Time: Varies by source count
notebooklm create "Collection: [name]"
Add multiple sources:
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
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:
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.
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):
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:
notebooklm source add-research "topic" --mode deep --import-all
# Blocks for up to 5 minutes
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 DriveProgress updates: Brief status for each step
Fire-and-forget for long operations:
artifact waitJSON output: Use --json flag for machine-readable output:
notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json
JSON schemas (key fields):
notebooklm list --json:
{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}
notebooklm auth check --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:
{"sources": [{"id": "...", "title": "...", "status": "ready|processing|error"}]}
notebooklm artifact list --json:
{"artifacts": [{"id": "...", "title": "...", "type": "Audio Overview", "status": "in_progress|pending|completed|unknown"}]}
Status values:
processing → ready (or error)pending or in_progress → completed (or unknown)On failure, offer the user a choice:
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 |
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 failedartifact wait returns 2 if timeout reached before completiongenerate returns 1 if rate limited (check stderr for details)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:
Unreliable operations: These may fail with rate limiting:
Workaround: If generation fails:
notebooklm artifact listProcessing 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.
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.
# List all 80+ supported languages with native names
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 |
Override per command: Use --language flag on generate commands:
notebooklm generate audio --language ja # Japanese podcast
notebooklm generate video --language zh_Hans # Chinese video
Offline mode: Use --local flag to skip server sync:
notebooklm language set zh_Hans --local # Save locally only
notebooklm language get --local # Read local config only
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 Refresh a CLI-managed install: notebooklm skill install
Weekly Installs
934
Repository
GitHub Stars
7.5K
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketFailSnykWarn
Installed on
opencode903
codex893
gemini-cli891
cursor881
github-copilot863
kimi-cli848
超能力技能使用指南:AI助手技能调用优先级与工作流程详解
37,500 周安装
Gemini Interactions API 指南:统一接口、智能体交互与服务器端状态管理
833 周安装
Apollo MCP 服务器:让AI代理通过GraphQL API交互的完整指南
834 周安装
智能体记忆系统构建指南:分块策略、向量存储与检索优化
835 周安装
Scrapling官方网络爬虫框架 - 自适应解析、绕过Cloudflare、Python爬虫库
836 周安装
抽奖赢家选取器 - 随机选择工具,支持CSV、Excel、Google Sheets,公平透明
838 周安装
Medusa 前端开发指南:使用 SDK、React Query 构建电商商店
839 周安装
notebooklm source wait - wait for source processing (in subagent context)notebooklm research status - check research statusnotebooklm 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 notebooknotebooklm ask "..." - chat queries (without --save-as-note)notebooklm history - display conversation history (read-only)notebooklm source add - add sources| 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 |
generate revise-slide "prompt" --artifact <id> --slide N |
--wait, --notebook |
| (re-downloads parent deck) |
| Infographic | generate infographic | `--orientation [landscape | portrait |
| Report | generate report | `--format [briefing-doc | study-guide |
| Mind Map | generate mind-map | (sync, instant) | .json |
| Data Table | generate data-table | description required | .csv |
| Quiz | generate quiz | `--difficulty [easy | medium |
| Flashcards | generate flashcards | `--difficulty [easy | medium |
| Slide deck as PPTX | download slide-deck --format pptx | Download slide deck as editable .pptx (web UI only offers PDF) |
| Slide revision | generate revise-slide "prompt" --artifact <id> --slide N | Modify individual slides with a natural-language prompt |
| Report template append | generate report --format study-guide --append "..." | Append custom instructions to built-in format templates without losing the format type |
| Source fulltext | source fulltext <id> | Retrieve the indexed text content of any source |
| Save chat to note | ask "..." --save-as-note / history --save | Save Q&A answers or conversation history as notebook notes |
| Programmatic sharing | share commands | Manage sharing permissions without the UI |
| 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 |
| Français - French |
de | Deutsch - German |
pt_BR | Português (Brasil) |