notebooklm

Files (200)

• .dockerignore
• .env.example
• .gitattributes
• bug_report.md · .github/ISSUE_TEMPLATE/
• config.yml · .github/ISSUE_TEMPLATE/
• feature_request.md · .github/ISSUE_TEMPLATE/
• PULL_REQUEST_TEMPLATE.md · .github/
• codeql-config.yml · .github/
• dependabot.yml · .github/
• auth-patch-audit.yml · .github/workflows/
• claude.yml · .github/workflows/
• codeql.yml · .github/workflows/
• dependency-audit.yml · .github/workflows/
• fault-stress.yml · .github/workflows/
• nightly-checks.yml · .github/workflows/
• nightly.yml · .github/workflows/
• offline-qualification.yml · .github/workflows/
• pages.yml · .github/workflows/
• publish-docker.yml · .github/workflows/
• publish-mcpb.yml · .github/workflows/
• publish.yml · .github/workflows/
• rpc-health.yml · .github/workflows/
• test.yml · .github/workflows/
• testpypi-publish.yml · .github/workflows/
• verify-package.yml · .github/workflows/
• .gitignore
• .pre-commit-config.yaml
• AGENTS.md
• CHANGELOG.md
• CLAUDE.md
• CONTRIBUTING.md
• LICENSE
• Makefile
• README.md
• SECURITY.md
• SKILL.md
• .env.example · deploy/
• .gitignore · deploy/
• Dockerfile · deploy/
• Makefile · deploy/
• README.md · deploy/
• docker-compose.build.yml · deploy/
• docker-compose.yml · deploy/
• setup.sh · deploy/
• funnel.json · deploy/tailscale/
• .mcpbignore · desktop-extension/
• README.md · desktop-extension/
• manifest.json · desktop-extension/
• run_server.py · desktop-extension/
• 0000-template.md · docs/adr/
• 0001-layered-core-seams-and-property-bridge-policy.md · docs/adr/
• 0002-capability-protocol-pattern.md · docs/adr/
• 0003-auth-facade-write-through.md · docs/adr/
• 0004-loop-affinity-contract.md · docs/adr/
• 0005-idempotency-taxonomy.md · docs/adr/
• 0006-vcr-scrubber-strategy.md · docs/adr/
• 0007-test-monkeypatch-policy.md · docs/adr/
• 0008-cli-services-extraction-pattern.md · docs/adr/
• 0009-middleware-chain.md · docs/adr/
• 0010-session-kernel-split.md · docs/adr/
• …and 140 more

SKILL.md (first lines)

# 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:

```bash
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](https://github.com/teng-lin/notebooklm-py/blob/main/docs/installation.md).

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

```bash
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:

```bash
notebooklm --help
notebooklm source --help
notebooklm research --help
notebooklm generate --help
notebooklm artifact --help

From teng-lin/notebooklm-py, MIT.

More from teng-lin/notebooklm-py