| 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]"
playwright install chromium
Run (agent path)
bash "<this skill's base directory>/smoke.sh"
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
notebooklm auth check
Auth
Two paths, in order of preference for this environment:
-
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.
-
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
notebooklm use <notebook-id>
notebooklm ask "one-line summary?"
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).
