NotebookLM Automation

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.

Use PyPI or a release tag, not an unreleased main checkout. When available, consult the installation guide.

Before a workflow, verify real authentication rather than merely parsing the cookie file:

notebooklm auth check --test --json

Require .status == "ok" and .checks.token_fetch == true. If validation fails:

• With a display, run notebooklm login and validate again.
• In a headless environment, install [cookies] and use notebooklm login --browser-cookies <browser>. Use notebooklm auth inspect --browser <browser> first when account selection is unclear.
• If previously valid cookies became stale, try notebooklm auth refresh; use notebooklm auth refresh --browser-cookies <browser> after signing back into the browser.

The normal --test preflight may heal and persist refreshed cookies. Add --passive when the check must be strictly read-only, including the failure-diagnosis workflow below.

notebooklm status reports selected-notebook context, not authentication.

Treat both auth files as bearer credentials: never print, log, or commit them. A master token is a durable full-account credential that survives password changes; use a dedicated account, protect it in a secret store and as 0600 on disk, and explicitly revoke it if exposed.

Operating Invariants

1. Use --json for discovery and mutations, then retain the returned full UUIDs. Important envelopes are .notebook.id from create, .source.id from source add, and .task_id from asynchronous generators. generate mind-map instead returns mind_map, note_id, and kind; both kinds return a finished result with no task ID or separate artifact wait step.
2. Pass -n/--notebook <id> on every notebook-scoped command in automation or concurrent work. Do not rely on notebooklm use. For every concurrent run, also set a unique NOTEBOOKLM_PROFILE=agent-<id> so context and profile writes are isolated. A new profile has no credentials: put a master_token.json copy in that profile and mint its storage before use. Never share one writable storage_state.json across agents.
3. After adding sources, retain every .source.id, then run source wait for each before chat or generation. The add envelope has no status. Require wait exit 0 and status == "ready"; let the waiter handle media-specific transient error rows.
4. After an asynchronous generator returns a task/artifact ID, pass it positionally to artifact wait with -n <notebook_id>. Download that exact artifact with -a <artifact_id> -n <notebook_id>; never select the latest visible artifact. Mind-map generation returns its completed result directly and does not need artifact wait.
5. For overlapping research runs, always pass --run-id <research_run_id>.
6. Use a host's background facility only when it actually exists. Keep wait and dependent download commands in one sequential job, and download only after the wait exits 0. Otherwise run in the foreground or return exact ID-pinned commands to the user.

Authorization Boundaries

Safe inspection and explicitly requested creation, source addition, chat, and prompt suggestion can run directly. Diagnose failures with read-only commands before attempting recovery.

Obtain confirmation immediately before an action when it was not already clearly authorized:

• destructive commands such as notebook/source/note/artifact/label/profile deletion, sharing removal, logout, clear, research cancellation, and ask --new;
• language set, because the default mode changes the account-global output language (prefer a generation command's --language override);
• generation or long foreground waits, which can take minutes and be rate-limited;
• downloads, which write files;
• research wait --import-all, which imports sources;
• ask --save-as-note and history --save, which create notes.

User intent, not the presence of a CLI prompt, is the authorization boundary. After authorization, pass --yes/-y where supported. Most destructive JSON commands refuse to prompt without it, but some, including ask --new --json and share remove --json, execute without prompting. Never treat prompt absence as consent.

research cancel is fire-and-forget. After an authorized cancellation, verify the exact run with notebooklm research status -n <notebook_id> --run-id <research_run_id> --json.

Command Discovery

Use the installed CLI's help as the version-matched source of truth instead of guessing flags:

notebooklm --help
notebooklm source --help
notebooklm research --help
notebooklm generate --help
notebooklm artifact --help
notebooklm download --help

Also inspect notebooklm --version and drill down to the exact command, such as notebooklm generate audio --help, whenever its help differs from this skill.

Common operations:

For the full surface, consult the installed command help or, when available, the CLI reference. For application code, use the baseline below and, when available, the Python API guide.

Canonical Source-to-Artifact Workflow

Keep {notebook_id}, every {source_id}, and {artifact_id} from JSON output:

An explicit request for this completed workflow authorizes its normal prerequisite waits, requested generation, and requested output file. Confirm only work not already authorized by that request.

1. notebooklm create "Research: topic" --json
2. notebooklm source add <input> -n {notebook_id} --json for each input.
3. Once the foreground wait is authorized, run notebooklm source wait {source_id} -n {notebook_id} --timeout 600 for every captured source.
4. Once generation is authorized, generate the requested type. For audio: notebooklm generate audio "instructions" -n {notebook_id} -s {source_id} --json. Repeat -s for each selected source and capture .task_id as {artifact_id}.
5. Once the foreground wait is authorized, run notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 1200.
6. Once the output write is authorized, run notebooklm download audio ./podcast.m4a -a {artifact_id} -n {notebook_id}.

For analysis without generation, replace steps 4-6 with an ID-pinned chat command only after every source is ready:

notebooklm ask "Summarize the key arguments" -n {notebook_id} --json