Gemini Notebook Automation

Use the notebooklm CLI for agent workflows. Prefer --json and explicit IDs so every operation is inspectable and safe under concurrency. Use the typed async Python API only when the user requests application code or the CLI cannot express the workflow. The readiness, identity, authorization, and credential-handling rules below apply to both interfaces.

Setup and Authentication

Requires Python 3.10+. Install the package in the user's existing environment; do not create a separate environment unless requested:

pip install "notebooklm-py[browser]"
pip install "notebooklm-py[cookies]"  # optional browser-cookie extraction

If system pip reports externally-managed-environment, do not use --break-system-packages. For CLI-only use, offer uv tool install "notebooklm-py[browser]" or the equivalent pipx command; for application code, use the user's active project environment.

For unattended or headless work, prefer durable profile-backed master-token auth over a copied cookie snapshot. Install pip install "notebooklm-py[headless]"; the one-time automatic OAuth capture also needs [browser]. On a trusted workstation run notebooklm login --master-token --account <email>, then deploy master_token.json, not storage_state.json, to the selected profile. NOTEBOOKLM_HOME selects the private base directory and NOTEBOOKLM_PROFILE selects its profile; defaults resolve to ~/.notebooklm/profiles/default/master_token.json.

In CI, NOTEBOOKLM_MASTER_TOKEN_JSON is a secret-transport convention, not an environment variable the package reads directly. Write its exact value to the selected profile's master_token.json with mode 0600, unset it, then run notebooklm auth refresh to mint storage_state.json. A sibling master token can automatically re-mint expired file-backed cookies. Inline NOTEBOOKLM_AUTH_JSON is only a short-lived fallback; it bypasses this recovery path.