google2api-cli

让 NotebookLM 回到你真正工作的浏览器里。 Bring NotebookLM back to the browser you actually work in.

NotebookLM upgrade path with live Chrome identity reuse via CDP.

Language: 中文 | English

中文

是什么

google2api-cli 是 notebooklm-cdp-cli 的升级命名版本。

当前仓库主打的是更宽的 Google 工作流入口，但现阶段仍保持 notebooklm / gemini-web / colab 这些现有命令不变。

你可以把它理解成：

仓库品牌升级为 google2api-cli
NotebookLM 仍然是当前最成熟、最清晰的主入口
对老用户继续兼容 notebooklm-cdp-cli 的安装和命令习惯

一句话：这是一个以 NotebookLM 为起点、向更广 Google 工作流延展的 CLI 升级版。

当前兼容策略

GitHub 仓库名已经升级为 google2api-cli
Python 包名暂时仍为 notebooklm-cdp-cli
主命令暂时仍为 notebooklm
gemini-web 和 colab 保持现有入口

这样做的目的是先完成品牌整理，不立刻打断已有脚本、文档和用户环境。

NotebookLM 升级版定位

如果你之前把它看成“一个只服务 NotebookLM 的 CDP CLI”，现在可以把它更新理解为：

NotebookLM 是第一主入口
Gemini / Flow / Colab 已经并入同一命令体系
真实浏览器身份复用仍然是整套设计的核心
未来仓库命名不再限制在单产品叙事里

它保留 CLI / RPC 的效率，但把认证思路从 Playwright 的 storage_state.json，换成 CDP 直连真实 Chrome 登录态。

一句话概括：命令行负责操作，CDP 负责接入，真实浏览器才是认证锚点。

为什么要做这个

很多自动化方案默认把 Playwright 的登录态文件当成"身份真相"。

临时脚本，可以。长期工作，不够。

因为一旦你真的把 NotebookLM 当成办公助手来用，问题就会很明显：

真实浏览器是一套身份，自动化环境又是一套身份
登录态漂移，维护成本上升
你真正工作的浏览器里明明已经登录，自动化这边却还在守着一份状态文件
最后，NotebookLM 被锁进了终端，而不是融入你的真实工作流

这个项目不是反对 Playwright。它反对的是另一件事：不该把离线状态文件，当成长期认证模型。

适合谁

这个项目主要面向这样的用户：

你已经在本地 Chrome / Chromium 中长期登录 Google / NotebookLM
你希望复用这套真实身份，而不是维护一份自动化专用登录态
你希望 NotebookLM 的主要操作仍然走 CLI / RPC
你希望自动化能力尽量贴近真实浏览器，而不是依赖重 DOM 流程

如果你想要的是：

完全隔离的自动化专用浏览器
DOM 自动化优先
以 Playwright session 为核心设计

那这可能不是你的主路径。

当前能力

目前 CLI 覆盖的范围包括：

browser attach / browser status
auth check 等认证诊断
notebook、source、chat、notes、share、research
artifact 列表与管理
report / audio / video / slide / infographic 的生成与下载流程
三个正式产品入口：
notebooklm 负责 NotebookLM
gemini-web 负责 Gemini / Flow
colab 负责 Colab

命令矩阵与稳定性

Product	Command families	Stability
NotebookLM	`browser`, `auth`, `doctor`, `notebook`, `source`, `chat` / `ask`, `notes`, `share`, `research`, `artifact`, `generate`, `download`, `language`	supported
Gemini	`gemini-web generate text`, `gemini-web ask`, `gemini-web generate image`, `gemini-web generate vision`	supported
Gemini	`gemini-web deep-research`, `gemini-web generate video`, `gemini-web chat ...`	experimental
Flow	`gemini-web flow open`, `gemini-web flow text-to-video`, `gemini-web flow image-to-video`, `gemini-web flow screenshot`	experimental
Colab	`colab notebook list/select/current/open/info/summary`, `colab cell count/run/run-file`, `colab runtime status`	supported
Colab	`colab file upload/list/download`, `colab artifact list/latest/get/download`, `colab notebook export`	best-effort

Stability 语义：

supported 表示 CLI contract 和回归测试覆盖稳定输出结构。
experimental 表示依赖浏览器 UI 或弱选择器，输出会显式带 stability: "experimental"。
best-effort 表示能力存在，但依赖 Colab 页面内 API、DOM 链接、浏览器 fetch 或 DOM 重建；输出会显式带 stability: "best_effort" 或 stability: "best-effort" 等价文案时按 JSON 字段为准。

Colab file / artifact / export 的边界：

文件上传是浏览器页内 best-effort 提交；大文件传输不承诺稳定。
文件和 artifact 下载只支持可从页面上下文 fetch 的 HTTP(S) URL；blob:、data:、缺失 URL 会返回结构化 unsupported error。
Notebook export 是 DOM 重建的 best-effort 导出，不承诺与 Colab 原生导出完全一致。
JSON 输出会区分 CLI status 和操作状态，例如 upload.state、download.state、export.state，并提供 evidence / uncertainty。

共享 target 解析层仍保留在整合命令面中，例如 notebooklm targets ... --product colab，但它是 secondary route，不是 Colab 的主公开入口。

迁移说明

旧入口	新入口
独立 NotebookLM CLI	保持 `notebooklm notebook/source/chat/research/artifact/generate/download ...`
`gemini-web-cli generate text`	正式入口：`gemini-web generate text`；整合入口：`notebooklm gemini generate text`
`gemini-web-cli ask`	正式入口：`gemini-web ask`；整合入口：`notebooklm gemini ask`
`gemini-web-cli generate image/vision/video`	正式入口：`gemini-web generate image/vision/video`；整合入口：`notebooklm gemini generate image/vision/video`，其中 video 为 experimental
`gemini-web-cli flow ...`	正式入口：`gemini-web flow ...`；整合入口：`notebooklm flow ...`，当前 Flow 命令为 experimental
`colab-cdp-cli notebook list/select/current/open/info/summary`	正式入口：`colab notebook ...`
`colab-cdp-cli cell/runtime/file/artifact/notebook export`	正式入口：`colab cell/runtime/file/artifact/notebook export ...`

旧仓只作为迁移来源；使用本仓不需要安装旧 Gemini/Colab 仓库。在合并仓里，gemini-web 和 colab 都是正式产品入口，不是兼容补丁命名。

发布范围

Linux：supported，当前首发目标
Windows：experimental / deferred，当前不承诺稳定可用

这不是一句模糊的"跨平台支持中"，而是明确的产品边界：

Linux 已经足够接近发布形态
Windows 仍在重构与稳定性治理阶段
因此当前不把 Windows 当作首发承诺平台

安装

uv sync
uv run notebooklm --help

已验证的 Linux 服务器链路

这条链路已经在全新 Linux VPS 上从 0 验证过一遍：

Xvfb :99
  -> 持久 Chrome profile
  -> CDP on 127.0.0.1:9222
  -> x11vnc + noVNC
  -> google2api-cli / notebooklm --host/--port

Chrome 的关键启动方式：

DISPLAY=:99 google-chrome-stable \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.browser-login/google-chrome-user-data \
  --no-sandbox

实测建议：

Linux 是当前稳定主路径
主 attach 路径优先 --host 127.0.0.1 --port 9222
不要依赖 DevToolsActivePort 自动发现
登录恢复优先走同 profile 的 noVNC 接管

完整 runbook 见 docs/linux-server-runbook.md。

仓库现在自带的 Linux helper scripts

这版仓库直接附带了服务器侧脚本：

scripts/install-base-linux.sh
scripts/start-chrome-cdp-linux.sh
scripts/start-novnc-linux.sh
scripts/verify-linux-host.sh
scripts/harden-ssh-linux.sh

这些脚本的目标不是替代 CLI，而是把 Linux 服务器上的浏览器身份底座固定下来。

快速开始

你需要：

一个可复用的 Chrome / Chromium profile
对应浏览器实例可通过 CDP 连接

1）显式指定 Chrome profile 路径

uv run notebooklm browser attach \
  --user-data-dir "/path/to/your/chrome-profile"

uv run notebooklm auth check
uv run notebooklm notebook list

2）通过环境变量提供 profile 路径

export NOTEBOOKLM_CDP_USER_DATA_DIR="/path/to/your/chrome-profile"

uv run notebooklm browser attach
uv run notebooklm auth check

3）直接连接已知的 CDP host / port

uv run notebooklm --host 127.0.0.1 --port 9222 browser status
uv run notebooklm --host 127.0.0.1 --port 9222 auth check

示例流程

uv run notebooklm browser attach --user-data-dir "/path/to/your/chrome-profile"
uv run notebooklm auth check
uv run notebooklm notebook list
uv run notebooklm source list --notebook <notebook-id>
uv run notebooklm ask "Summarize the main ideas in Chinese." --notebook <notebook-id>

报告与生成

generate report --format 当前支持的值：

briefing_doc
study_guide
blog_post
custom

当你使用 --format custom 时，需要同时提供 --prompt。

summary 不是合法的 report format。如果你要 notebook summary，请使用：

uv run notebooklm notebook summary --notebook <notebook-id>

示例：

uv run notebooklm generate report \
  --notebook <notebook-id> \
  --format briefing_doc \
  --json

Pending 生成任务

当一次生成请求已经被接受、但 artifact 仍处于 pending 时，CLI 会做一次短暂的 best-effort 检查：

如果已经能识别到新 artifact，会尽量直接返回 artifact id
如果还不能确定，则保持 pending，并给出后续命令提示

本地 ledger 路径：~/.notebooklm-cdp/pending_submissions.json

常用命令：

uv run notebooklm artifact pending --json
uv run notebooklm artifact resolve-pending <submission-id> --json

artifact resolve-pending 只有在当前 artifact 列表里存在唯一强候选时才会自动解析；否则会返回候选项，而不是假装确定。

设计取舍

这个项目不是在重新发明 NotebookLM client。它做的是一层更贴近真实使用的身份对齐：

真实浏览器继续是真实浏览器
CLI 继续是 CLI
CDP 把两者接起来

而不是再造一个只属于自动化的平行身份世界。

与 notebooklm-py 的关系

本项目是一个独立 CLI，但当前 NotebookLM client / RPC 能力建立在 notebooklm-py 之上。

大致分工如下：

本仓库负责：

live Chrome identity via CDP
CLI surface
本地状态管理

notebooklm-py 负责：

NotebookLM client
RPC types
后端调用能力

本项目刻意不把 notebooklm-py 的 Playwright / storage_state.json 登录流当作主认证模型。

向上游项目致谢。第三方组件与补充说明见 THIRD_PARTY.md。

License

MIT. See LICENSE.

English

What this is

google2api-cli is the renamed and broadened evolution of notebooklm-cdp-cli.

The repository name now reflects a wider Google-facing CLI surface, while the current installed package and commands remain compatible with the existing notebooklm, gemini-web, and colab entry points.

In practice, this means:

the repository brand is now google2api-cli
NotebookLM is still the clearest and most mature primary entry
existing command habits do not break immediately

This is best read as a NotebookLM-first upgrade path, not a sudden rewrite of the CLI contract.

Compatibility policy

GitHub repository: google2api-cli
Python package name: still notebooklm-cdp-cli for now
main command: still notebooklm
gemini-web and colab remain valid product commands

The goal is to clean up branding first without breaking existing scripts and environments.

It keeps the speed of CLI / RPC workflows, but moves auth away from Playwright's storage_state.json and toward a live Chrome identity over CDP.

In one line:

CLI for operations. CDP for attachment. Real Chrome as the auth anchor.

Why this exists

Many automation flows effectively treat Playwright auth state as the source of truth.

That works for scripts. It breaks down for real daily work.

Once NotebookLM becomes part of an actual workflow, the pain becomes obvious:

your real browser is one identity
your automation environment is another
login state drifts
your browser is already logged in, yet automation still depends on a separate state file
NotebookLM ends up trapped in a terminal silo instead of living inside your real browser workflow

This project is not anti-Playwright.

Its objection is narrower:

an offline state file should not be treated as the long-term identity model.

Who this is for

This project is for you if:

you already have a long-lived Google / NotebookLM login in Chrome or Chromium
you want to reuse that real identity instead of maintaining a separate automation-only auth state
you want NotebookLM operations to stay primarily CLI / RPC-driven
you want automation to stay close to your real browser workflow rather than depend on heavy DOM flows

It is probably not your primary path if you want:

a fully isolated automation-only browser world
DOM automation first
a Playwright-session-first design

Current scope

The CLI currently covers:

browser attach / browser status
auth diagnostics such as auth check
notebook, source, chat, notes, share, research
artifact listing and management
generation / download flows for report, audio, video, slide, and infographic
three primary product commands: notebooklm for NotebookLM; gemini-web for Gemini / Flow; colab for Colab.

Command Matrix And Stability

Product	Command families	Stability
NotebookLM	`browser`, `auth`, `doctor`, `notebook`, `source`, `chat` / `ask`, `notes`, `share`, `research`, `artifact`, `generate`, `download`, `language`	supported
Gemini	`gemini-web generate text`, `gemini-web ask`, `gemini-web generate image`, `gemini-web generate vision`	supported
Gemini	`gemini-web deep-research`, `gemini-web generate video`, `gemini-web chat ...`	experimental
Flow	`gemini-web flow open`, `gemini-web flow text-to-video`, `gemini-web flow image-to-video`, `gemini-web flow screenshot`	experimental
Colab	`colab notebook list/select/current/open/info/summary`, `colab cell count/run/run-file`, `colab runtime status`	supported
Colab	`colab file upload/list/download`, `colab artifact list/latest/get/download`, `colab notebook export`	best-effort

Stability means:

supported commands have stable CLI contracts and regression coverage for their output shape.
experimental commands depend on browser UI behavior or weak selectors and return stability: "experimental" in JSON.
best-effort commands exist, but depend on Colab page APIs, DOM links, browser fetch, or DOM reconstruction and return stability: "best_effort" in JSON.

Colab file / artifact / export boundaries:

File upload is a best-effort browser-page submission. Large file transfer is not guaranteed.
File and artifact download only support HTTP(S) URLs fetchable from the page context. blob:, data:, and missing URLs return structured unsupported errors.
Notebook export is a best-effort DOM reconstruction and is not promised to match Colab's native export exactly.
JSON output distinguishes CLI status from operation state, such as upload.state, download.state, and export.state, and includes evidence / uncertainty.

The shared target-resolution layer remains available through integrated routes such as notebooklm targets ... --product colab, but that is a secondary route, not Colab's primary public command surface.

Migration Notes

Old entry point	New entry point
Standalone NotebookLM CLI usage	Keep using `notebooklm notebook/source/chat/research/artifact/generate/download ...`
`gemini-web-cli generate text`	primary entrypoint: `gemini-web generate text`; integrated entrypoint: `notebooklm gemini generate text`
`gemini-web-cli ask`	primary entrypoint: `gemini-web ask`; integrated entrypoint: `notebooklm gemini ask`
`gemini-web-cli generate image/vision/video`	primary entrypoint: `gemini-web generate image/vision/video`; integrated entrypoint: `notebooklm gemini generate image/vision/video`; video is experimental
`gemini-web-cli flow ...`	primary entrypoint: `gemini-web flow ...`; integrated entrypoint: `notebooklm flow ...`; current Flow commands are experimental
`colab-cdp-cli notebook list/select/current/open/info/summary`	primary entrypoint: `colab notebook ...`
`colab-cdp-cli cell/runtime/file/artifact/notebook export`	primary entrypoint: `colab cell/runtime/file/artifact/notebook export ...`

The old Gemini and Colab repositories are migration sources only. They are not required dependencies for this package. Inside the merged repository, both gemini-web and colab are first-class product commands.

Release scope

Linux: supported, intended for release use
Windows: experimental / deferred, not currently promised as stable

This is a deliberate product boundary, not a vague "cross-platform in progress" statement.

Install

uv sync
uv run notebooklm --help

Verified Linux server flow

This repository now includes a validated Linux-first server path:

Xvfb :99
  -> persistent Chrome profile
  -> CDP on 127.0.0.1:9222
  -> x11vnc + noVNC
  -> google2api-cli / notebooklm --host/--port

Key Chrome launch pattern:

DISPLAY=:99 google-chrome-stable \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.browser-login/google-chrome-user-data \
  --no-sandbox

Practical recommendations:

Linux is the current stable path
prefer explicit --host 127.0.0.1 --port 9222
do not depend on DevToolsActivePort
use same-profile noVNC takeover for login recovery

See docs/linux-server-runbook.md for the full runbook.

Bundled Linux helper scripts

This release now ships server-side helper scripts:

scripts/install-base-linux.sh
scripts/start-chrome-cdp-linux.sh
scripts/start-novnc-linux.sh
scripts/verify-linux-host.sh
scripts/harden-ssh-linux.sh

These are meant to stabilize the Linux browser identity layer around the CLI, not replace the CLI itself.

Quick start

You need:

a reusable Chrome / Chromium profile
a browser instance reachable via CDP

1) Attach with an explicit profile path

uv run notebooklm browser attach \
  --user-data-dir "/path/to/your/chrome-profile"

uv run notebooklm auth check
uv run notebooklm notebook list

2) Provide the profile via environment variable

export NOTEBOOKLM_CDP_USER_DATA_DIR="/path/to/your/chrome-profile"

uv run notebooklm browser attach
uv run notebooklm auth check

3) Connect to an existing CDP host / port

uv run notebooklm --host 127.0.0.1 --port 9222 browser status
uv run notebooklm --host 127.0.0.1 --port 9222 auth check

Example flow

uv run notebooklm browser attach --user-data-dir "/path/to/your/chrome-profile"
uv run notebooklm auth check
uv run notebooklm notebook list
uv run notebooklm source list --notebook <notebook-id>
uv run notebooklm ask "Summarize the main ideas in Chinese." --notebook <notebook-id>

Reports and generation

Valid values for generate report --format:

briefing_doc
study_guide
blog_post
custom

When using --format custom, you must also provide --prompt.

summary is not a valid report format. If you want the notebook summary, use:

uv run notebooklm notebook summary --notebook <notebook-id>

Example:

uv run notebooklm generate report \
  --notebook <notebook-id> \
  --format briefing_doc \
  --json

Pending submissions

When a generation request has been accepted but the artifact is still pending, the CLI performs a short best-effort lookup:

if a newly created artifact can already be identified, it tries to return the artifact id directly
otherwise it keeps the result as pending and points you to follow-up commands

Local ledger path: ~/.notebooklm-cdp/pending_submissions.json

Useful commands:

uv run notebooklm artifact pending --json
uv run notebooklm artifact resolve-pending <submission-id> --json

artifact resolve-pending only auto-resolves when there is a single strong candidate. Otherwise it returns candidates instead of pretending certainty.

Design choice

This project is not trying to reinvent the NotebookLM client. It focuses on a more realistic identity alignment layer:

real browser stays real browser
CLI stays CLI
CDP connects the two

instead of creating a second automation-only identity world.

Relationship with notebooklm-py

This repository is an independent CLI, but its current NotebookLM client / RPC capability builds on top of notebooklm-py.

Roughly speaking:

this repo handles:

live Chrome identity via CDP
CLI surface
local state management

notebooklm-py handles:

NotebookLM client
RPC types
backend capability

This project intentionally does not treat the Playwright / storage_state.json login flow in notebooklm-py as its primary auth model.

With thanks to the upstream project. See THIRD_PARTY.md for third-party notices and additional details.

License

MIT. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/notebooklm_cdp_cli		src/notebooklm_cdp_cli
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
THIRD_PARTY.md		THIRD_PARTY.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

google2api-cli

中文

是什么

当前兼容策略

NotebookLM 升级版定位

为什么要做这个

适合谁

当前能力

命令矩阵与稳定性

迁移说明

发布范围

安装

已验证的 Linux 服务器链路

仓库现在自带的 Linux helper scripts

快速开始

示例流程

报告与生成

Pending 生成任务

设计取舍

与 notebooklm-py 的关系

License

English

What this is

Compatibility policy

Why this exists

Who this is for

Current scope

Command Matrix And Stability

Migration Notes

Release scope

Install

Verified Linux server flow

Bundled Linux helper scripts

Quick start

Example flow

Reports and generation

Pending submissions

Design choice

Relationship with notebooklm-py

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages