run-notebooklm

name	run-notebooklm
description	Run, verify, and troubleshoot the NotebookLM CLI integration (notebooklm-py). Use when asked to run/test/smoke the NotebookLM CLI, check NotebookLM auth, set up NotebookLM on a new machine or headless server, or debug "not authenticated" errors.

Run: NotebookLM CLI integration

The "app" here is the notebooklm CLI (from notebooklm-py), which automates Google NotebookLM. It is driven entirely from the shell — the driver is smoke.sh next to this SKILL.md. When this skill loads, Claude Code announces its base directory; use that path to invoke the driver (the CLAUDE_PLUGIN_ROOT variable is only set for hook processes, not in the agent's shell — do not rely on it in commands).

Prerequisites

pip install "notebooklm-py[browser]"     # pip3 / python3 -m pip on Debian/Ubuntu
# Only needed before interactive 'notebooklm login' (not for env-var auth):
playwright install chromium              # ~130 MB, one-time

Run (agent path)

bash "<this skill's base directory>/smoke.sh"
# Fallback if the base directory isn't shown:
bash "$(find ~/.claude/plugins -path '*notebooklm*' -name smoke.sh 2>/dev/null | head -1)"

Exit codes:

Code	Meaning	Next step
0	Installed + authenticated, live notebooklm list round-trip passed	Use /notebooklm skill for real work
2	Installed but not authenticated (or cookies expired / list timed out)	See Auth below
3	CLI missing/broken	Re-run the pip install above
1	Unexpected script error (e.g. set -u abort)	Read the output; report a bug

A WARN about the Artifact Actions heading is informational only — upstream may rename help sections between releases; it does not affect the exit code.

Quick diagnostics (both verified working unauthenticated):

notebooklm doctor       # profile/auth/migration table; exit 1 if unauthenticated
notebooklm auth check   # cookie-level detail; add --test for a live token fetch

Auth

Two paths, in order of preference for this environment:

1. Headless / CI / remote container (this repo's normal case): export the contents of a storage_state.json produced by logging in on a machine with a browser:

   export NOTEBOOKLM_AUTH_JSON="$(cat storage_state.json)"
   

   Verified: notebooklm auth check then reports Storage exists ✓ NOTEBOOKLM_AUTH_JSON. The JSON must contain the Google cookies including __Secure-1PSIDTS — a partial cookie set fails with Missing required cookies: __Secure-1PSIDTS.

2. Interactive machine: playwright install chromium once, then notebooklm login (opens a browser window; useless in this headless container — do not attempt here).

Test

The package ships no test suite in the installed wheel; the smoke script above is the verification. After auth, the real end-to-end check is:

notebooklm list                      # round-trip to NotebookLM
notebooklm use <notebook-id>         # set context
notebooklm ask "one-line summary?"   # grounded chat

Gotchas

• pip install "notebooklm-py[browser]" installs the Playwright package but not the Chromium binary — notebooklm login and browser-based auth refresh fail with Executable doesn't exist until you run playwright install chromium. Env-var auth needs no browser at all.
• notebooklm login cannot be used while NOTEBOOKLM_AUTH_JSON is set — the env var takes precedence and login refuses to run. Unset it first.
• notebooklm doctor exits 1 when unauthenticated, but notebooklm auth check exits 0 even on failure — gate scripts on doctor's exit code (the smoke script does). Don't grep doctor's table output: rich wraps cell text under narrow COLUMNS and the words split across lines.
• The [cookies] extra (rookiepy, for --browser-cookies extraction) fails to build on Python 3.13+. Skip it there; this container (3.11) can use it.
• Chrome 127+ App-Bound Encryption can cause silent partial cookie reads when using --browser-cookies chrome; symptom is the Missing required cookies error above. Fall back to notebooklm login.
• Auth files live under ~/.notebooklm/profiles/<profile>/storage_state.json; the container is ephemeral, so env-var auth (or re-login) is needed each fresh session unless a SessionStart hook restores it.
• On Debian/Ubuntu images only pip3 may exist; the SessionStart hook script falls back through pip → pip3 → python3 -m pip.

Troubleshooting

Symptom	Fix
'notebooklm' CLI not on PATH	pip install "notebooklm-py[browser]" (or pip3 / python3 -m pip)
Storage file not found: .../storage_state.json	Not logged in — use one of the Auth paths above
Missing required cookies: __Secure-1PSIDTS	Cookie set incomplete; regenerate via full notebooklm login on a desktop
Executable doesn't exist at .../chrome...	playwright install chromium
Authenticated but list fails/times out	notebooklm auth refresh (needs Chromium, see above), then re-run smoke

Maintenance

This is the plugin mirror of the canonical skill at .claude/skills/run-notebooklm/ in the source repository; edit there and run plugins/notebooklm/scripts/sync-skills.sh (smoke.sh is synced verbatim, this SKILL.md intentionally differs only in how the driver is located).