Notebooklm

NotebookLM Skill

Provides agent access to Google's NotebookLM through the notebooklm tool.

Prerequisites

1. Install the upstream CLI:

   uv tool install "notebooklm-py[browser]"
   

   See notebooklm-py docs for pipx/venv alternatives.

2. Authenticate in a terminal (one-time):

   notebooklm login    # auto-installs Chromium on first run
   notebooklm auth check --test --json
   

   If playwright install chromium fails during login, run it manually:

   uv tool run --from 'notebooklm-py[browser]' playwright install chromium
   

Tool usage

Single notebooklm tool with argument array:

notebooklm args=["list", "--json"]
notebooklm args=["auth", "check", "--test", "--json"]
notebooklm args=["create", "Research Notebook", "--json"]
notebooklm args=["source", "add", "https://...", "-n", "<notebook-id>", "--json"]
notebooklm args=["source", "add", "Inline text content...", "-n", "<notebook-id>", "--json"]
notebooklm args=["ask", "Summarize findings", "-n", "<notebook-id>", "--json"]
notebooklm args=["generate", "audio", "-n", "<notebook-id>"]
notebooklm args=["artifact", "wait", "<task-id>", "-n", "<notebook-id>", "--json"]
notebooklm args=["download", "audio", "-a", "<artifact-id>", "output.mp3"]

Command map (v0.7.3)

Rules

• Navigation: always key on full IDs. The created_at field returned by list/metadata/use/status is not the real creation time — it mutates nearly every call (tracks "last touched"), and status even returns a date-only value. Do not sort, order, or dedup by created_at. The list order and the index field are unstable too (order swaps between calls), so never reference a notebook/source/artifact by index — always use the full id. Partial-prefix IDs also work for use and source/artifact IDs (e.g. use eadca411 resolves to eadca411-…). Root cause is upstream (notebooklm-py); see "Known upstream limitations" below.
• Use full notebook IDs and explicit -n in parallel agent workflows. Shared notebooklm use context can race across calls.
• Wait for sources before chat or generation: source wait <src-id> -n <id> --json or check with source list -n <id> --json.
• Async generation: call generate <type> -n <id> → get task ID → poll with artifact poll <task-id> -n <id> --json or block with artifact wait.
• Destructive operations (delete, clean, remove, logout, clear, conversation reset) require confirm: true. Most also need -y/--yes in args to avoid a hanging prompt (auth logout, clear, skill uninstall, and history --clear are exceptions — CLI v0.7.3 does not support -y/--yes for those).
• Start a new conversation: ask --new is destructive (discards server-side conversation). Requires confirm: true and -y/--yes.
• File overwrites: download, source fulltext -o <path>, or skill install with --force overwrites workspace files — requires confirm: true.
• Authentication stays in NotebookLM CLI's own storage. Never pass cookies through Pi.

JSON output

Add --json for machine-readable output. Key shapes:

• ask --json: {"answer": "...", "references": [{"source_id": "...", "cited_text": "...", "citation_number": 1}], "conversation_id": "...", "turn_number": 1}
• list --json: {"notebooks": [...], "count": N}
• auth check --test --json: {"status": "ok", "checks": {...}}
• source list --json: {"sources": [...], "count": N}
• source wait --json: {"source_id": "...", "status": "ready", "status_code": 2}

Error routing

Known upstream limitations

• created_at and list ordering are unstable in notebooklm-py (upstream). The created_at value changes across list/metadata/use/status calls for the same notebook, and list index order shifts between calls. Key on full IDs only — never sort, dedup, or reference by index/created_at. See "Navigation: always key on full IDs" in Rules.