nlm-skill

# Gemini Notebook CLI & MCP Expert This skill provides comprehensive guidance for using Gemini Notebook via both the `nlm` CLI and MCP tools. ## Tool Detection (CRITICAL - Read First!) **ALWAYS check which tools are available before proceeding:** 1. **Check for MCP tools**: Tool names vary by host; look for `mcp__gemini-notebook-mcp__*`, `mcp__notebooklm_mcp__*`, or `mcp_gemini_notebook_mcp_*`. 2. **Follow an explicit surface choice**: If the user asks for MCP or CLI, use it. 3. **Choose by task when both are available**: Use MCP for notebook operations and downloads inside its configured download directory. Use the CLI for an explicit `--profile` without changing the MCP default account, or for a user-directed output path outside the MCP download directory. Ask only if the choice would materially change the result and the user's preference is unclear. 4. **Use the available surface** when only MCP or only CLI is callable; read its tool docstring or `nlm <command> --help` before supplying unfamiliar options. **Decision Logic:** ``` has_mcp_tools = check_available_tools() # Look for any NotebookLM MCP tool name above has_cli = check_bash_available() # Can run nlm commands if user_named_mcp_or_cli: use_that_surface() elif needs_workspace_output_outside_mcp_root or needs_explicit_profile_without_switching_default: use_cli() elif has_mcp_tools: use_mcp() elif has_cli: use_cli() ``` Check the active account before a mutation when more than one profile is saved: `nlm login profile list` shows accounts, and `nlm config get auth.default_profile` shows the MCP default. CLI commands can use `--profile <name>`. MCP tools use the active profile: call the `profile` tool (`action=list`, then `action=switch` with `name=...`) to change it for this MCP server until it restarts (add `make_default=true` only when the user asks to change their default). While a switch is active, tool results carry `active_profile_note`; tell the user which account is in use. `usage_get(profile=...)` is an account-specific read and does not switch other MCP tools. ## Quick Reference **Run `nlm --ai` to get comprehensive AI-optimized documentation** - this provides a complete view of all CLI capabilities. ```bash nlm --help # List all commands nlm <command> --help # Help for specific command nlm --ai # Full AI-optimized documentation (RECOMMENDED) nlm --version # Check installed version nlm usage # Check rolling and weekly plan usage and reset times nlm usage --json # Return usage data as machine-readable JSON ``` ## Critical Rules (Read First!) 1. **Authenticate when needed**: Run `nlm login` for first-time setup or confirmed stale/missing credentials. Saved cookies often remain usable for weeks. 2. **Do not confuse network failures with expired auth**: `auth_status="unverified"` means the probe was inconclusive. Check connectivity or try an API call before asking the user to log in again. 3. **Auto-Authentication Recovery**: The CLI includes automatic 3-layer auth recovery (CSRF refresh -> Token reload -> Headless Auth) and retries for explicitly classified read-only requests. Mutations are not replayed after ambiguous server errors. Most errors are handled automatically. You only need to manually run `nlm login` if all recovery layers fail. Automatic browser recovery has a per-process cooldown and failure budget; concurrent requests share an active recovery. Explicit `nlm auth refresh` bypasses these limits. Use `--http-only` when a browser must not open; it cannot renew browser-dependent PSIDTS cookies or revive a fully expired login. 4. **⚠️ ALWAYS ASK USER BEFORE DELETE**: Before executing ANY delete command, ask the user for explicit confirmation. Deletions are **irreversible**. Show what will be deleted and warn about permanent data loss. 5. **Always obtain approval before generation or deletion**: Direct `studio_create` and delete operations enforce `--confirm` / `confirm=True`. The current MCP batch Studio path does not enforce its confirm parameter, so the agent must preserve the approval gate. 6. **Research needs a destination**: Pass `--notebook-id <id>` for an existing notebook or `--title <title>` to create one. 7. **Capture IDs from output**: Create/start commands return IDs needed for subsequent operations 8. **Use aliases**: Simplify long UUIDs with `nlm alias set <name> <uuid>` 9. **Check aliases before creating**: Run `nlm alias list` before creating a new alias to avoid conflicts with existing names. 10. **DO NOT launch REPL**: Never use `nlm chat start` - it opens an interactive REPL that AI tools cannot control. Use `nlm notebook query` for one-shot Q&A instead. 11. **Choose output format wisely**: Default output (no flags) is compact and token-efficient—use it for status checks. Use `--quiet` to capture IDs for piping. Only use `--json` when you need to parse specific fields programmatically. 12. **Use `--help` when unsure**: Run `nlm <command> --help` to see available options and flags for any command. 13. **Studio: fast track by default**: Infer format/style/prompt silently—one compact line, then `studio_create(confirm=True)`. No intake questionnaires. Fast track reduces clarifying questions, not the confirm gate. **Cinematic video is always guided** (quota-limited). Full preview only when vague, high-stakes, cinematic, or user asks. See **[references/studio-prompting-guide.md](references/studio-prompting-guide.md)**. 14. **Check plan usage before quota-limited work**: Run `nlm usage` (MCP: `usage_get`) before expensive chat or Studio work when budget availability matters. It reports measured compute usage, remaining percentage, and UTC reset times for the rolling and weekly windows. If the check returns an authentication error, refresh the session instead of treating the allowance as exhausted. **Current MCP surface:** 55 tools. Consolidated action tools include `note`, `label`, `studio_status`, `batch`, `pipeline`, `tag`, `profile`, and `alias`. Consolidated type tools include `source_add`, `studio_create`, and `download_artifact`. The read-only `usage_get` tool reports rolling and weekly plan usage windows. ## Workflow Decision Tree Use this to determine the right sequence of commands: ``` User wants to... │ ├─► Work with NotebookLM for the first time │ └─► nlm login → nlm notebook create "Title" │ ├─► Add content to a notebook │ ├─► From a URL/webpage → nlm source add <nb-id> --url "https://..." │ ├─► From YouTube → nlm source add <nb-id> --url "https://youtube.com/..." │ ├─► From pasted text → nlm source add <nb-id> --text "content" --title "Title" │ ├─► From Google Drive → nlm source add <nb-id> --drive <doc-id> --type doc │ └─► Discover new sources → nlm research start "query" --notebook-id <nb-id> │ ├─► Check plan usage or quota availability │ └─► nlm usage (MCP: usage_get) │ (Use --json when a script needs percentages or reset timestamps) │ ├─► Generate content from sources (→ Studio Prompting for optimal focus_prompt) │ ├─► Podcast/Audio → nlm audio create <nb-id> --confirm │ ├─► Written summary → nlm report create <nb-id> --confirm │ ├─► Study materials → nlm quiz/flashcards create <nb-id> --confirm │ ├─► Visual content → nlm mindmap/slides/infographic create <nb-id> --confirm │ ├─► Video → nlm video create <nb-id> --confirm │ └─► Extract data → nlm data-table create <nb-id> "description" --confirm │ ├─► Refactor, critique, or improve a draft document │ └─► See Workflow 15 in references/workflows.md │ ├─► Ground a notebook in bounded public X research │ └─► See Workflow 16 in references/workflows.md │ ├─► Build a lesson-style interactive report with embedded elements │ └─► See Workflow 17 in references/workflows.md │ (create -> read markdown -> generate elements via the report view) │ ├─► Ask questions about sources │ └─► nlm notebook query <nb-id> "question" │ (Use --conversation-id for follow-ups) │ ⚠️ Do NOT use `nlm chat start` - it's a REPL for humans only │ ├─► Review or export a past chat │ └─► nlm chats list <nb-id> → nlm chats get/export <nb-id> [conversation-id] │ ├─► Check generation status │ └─► nlm studio status <nb-id> │ └─► Manage/cleanup ├─► List notebooks → nlm notebook list ├─► List sources → nlm source list <nb-id> ├─► Delete source → nlm source delete <source-id> --confirm └─► Delete notebook → nlm notebook delete <nb-id> --confirm ``` ## Command Categories ### 1. Authentication #### MCP Authentication If using MCP tools and encountering authentication errors: ```bash # Run the CLI authentication (works for both CLI and MCP) nlm login # Then reload tokens in MCP mcp__gemini-notebook-mcp__refresh_auth() # Refresh a specific saved account without switching the active account: mcp__gemini-notebook-mcp__refresh_auth(profile="work") # Returns status: "success" (valid), "expired" (tokens dead, run `nlm login`), # or "error". `nlm login` is the only recovery path for "expired". ``` Or manually save cookies via MCP (fallback): ```python # Extract cookies from Chrome DevTools and save mcp__gemini-notebook-mcp__save_auth_tokens(cookies="<cookie_header>") ``` ```` #### CLI Authentication ```bash nlm login # Launch browser, extract cookies (primary method) nlm login --check # Validate current session nlm login --storage protected # New profile: store the login encrypted (or 'file'); skips the question nlm login --profile work # Use named profile for multiple accounts nlm login --provider openclaw --cdp-url http://127.0.0.1:18800 # External CDP provider nlm login switch <profile> # Switch the default profile nlm login profile list # List all profiles with email addresses nlm login profile delete <name> # Delete a profile nlm login profile rename <old> <new> # Rename a profile nlm auth refresh # Non-interactive headless refresh (schedulers/unattended) nlm auth refresh --profile work # Refresh a named saved account nlm auth refresh --http-only # Validate and save without opening a browser nlm auth storage status # Check credential storage mode (file or protected) nlm auth storage set protected # Encrypt credentials using OS credential store (--profile X or --all) nlm auth storage set file # Decrypt credentials back to plain files (downgrade prep) nlm auth storage resolve file # Resolve conflict: keep plain files, discard encrypted nlm auth storage resolve protected # Resolve conflict: keep encrypted, discard plain files nlm auth storage relocate # Re-bind credentials after moving storage directory ```` > **Agent Note**: Document and support `nlm auth storage` when diagnosing auth issues or when requested by the user, but do not proactively nag or prompt users to switch storage modes. **Multi-Profile Support**: Each profile gets its own isolated browser session (supports Chrome, Arc, Dia, Comet, Brave, Edge, Chromium, Firefox, and more), so you can be logged into multiple Google accounts simultaneously. **Auth status:** `configured` means usable; `stale` means run `nlm login`; `not_configured` means first-time setup is required; `unverified` means the probe was inconclusive; `error` means the health check itself failed. **Switching MCP Accounts**: Call the `profile` tool: `profile(action="list")` shows saved accounts, `profile(action="switch", name="<name>")` uses that account for every later MCP call until the MCP server restarts (apps that share one server across chats, like Claude Desktop, apply it to every open chat). Add `make_default=true` ONLY if the user asks to change their default account; it also changes the CLI default. From a terminal, `nlm login switch <name>` changes the saved default and the next MCP call uses it. **Note**: Both MCP and CLI share the same authentication backend, so authenticating with one works for both. **Login completion (v0.15.3+):** Builtin Chromium/CDP login waits up to 300 seconds for signed-in Google cookies and the actual CSRF token. A Notebook URL, HTTP 200, or an anonymous `NID` cookie is not proof of authentication. If an older version saved only `NID` and reported success, upgrade and retry `nlm login --profile <name>`, then verify with `nlm login --check --profile <name>`. Keep the same profile; do not delete it or invent tokens to repair this failure. Builtin login closes its browser after completion; externally managed CDP browsers remain open. See [login recovery](references/troubleshooting.md#browser-closes-before-sign-in-or-reports-false-success). **Headless refresh & CDP port fallback (v0.15.4+):** `nlm auth refresh` surfaces actionable failure diagnostics (explaining signed-out profiles, missing browser profiles, or candidate credential rejection) rather than silently returning empty tokens. Headless authentication also automatically falls back to an OS-assigned ephemeral port when default ports conflict. **Refresh safety (v0.15.5+):** `--http-only` forces HTTP transport even when `NOTEBOOKLM_RPC_TRANSPORT=cdp` is configured and saves credentials only after a valid authenticated API response. It remains available when `NOTEBOOKLM_DISABLE_HEADLESS_REFRESH=1` disables browser recovery. On accounts where reopening the browser revokes the session, keep browser recovery disabled; an HTTP-only failure may still require interactive `nlm login`. Automatic browser recovery defaults to a 900-second cooldown and three failures per profile within each process. Set `NOTEBOOKLM_AUTH_RECOVERY_COOLDOWN_SECONDS` or `NOTEBOOKLM_AUTH_MAX_HEADLESS_FAILURES` to 0 to disable that limit. A new credential revision or changed file-mode cookies resets the budget; success clears the failure count. Concurrent callers wait up to 60 seconds for the same recovery result. Separate processes serialize Chromium recovery with a per-profile lock. Explicit CLI/MCP refresh bypasses the automatic budget. ### Plan Usage and Quotas Gemini Notebook meters chat and Studio usage as compute against two simultaneous windows: a short rolling window (about five hours) and a weekly cap. The API reports the measured percentage used, percentage remaining, and reset timestamp; the client does not estimate cost from request counts. #### MCP Tool Call `usage_get()` for a read-only account-level usage report. It returns: - `windows`: `rolling` and `weekly` entries, sorted in that order - `percent_used`: percentage consumed (0.0 when the backend confirms a full allowance) - `percent_remaining`: percentage left - `resets_at`: ISO 8601 UTC reset timestamp - `tier`: subscription tier when available To check separate accounts, call `usage_get(profile="work")` and `usage_get(profile="personal")` using their saved profile names. Each call uses that account without switching the default or affecting other MCP tools. An explicit profile overrides `NOTEBOOKLM_COOKIES`; a missing profile returns an error instead of falling back to another account. The API may return windows in either order, so consumers should use the window name. If the usage request fails with an authentication error, refresh with `nlm auth refresh` or `nlm login`; do not interpret the failure as zero quota. #### CLI ```bash nlm usage # Human-readable table in the local timezone nlm usage --json # Machine-readable JSON; reset timestamps stay in UTC nlm usage --profile work # Check work without changing the default account nlm usage -p personal # Check personal separately ``` Use this check before quota-limited chat or Studio work when the remaining budget or reset time affects the decision. ### 2. Notebook Management #### MCP Tools Use `notebook_list`, `notebook_create`, `notebook_get`, `notebook_describe`, `notebook_query`, `notebook_rename`, and `notebook_delete`. The get/describe/query/rename/delete tools require `notebook_id`; list and create do not. Delete requires `confirm=True`. Queries use a 120-second wall-clock budget by default. Source-heavy notebooks or long-running questions may need a larger budget, for example `timeout=180`. For those queries, call `notebook_query_start`, then poll `notebook_query_status(query_id)` until completed or errored. By default, `notebook_query` continues the notebook's persistent chat when `conversation_id` is omitted. For an independent question, pass `new_conversation=True` (or use `--new-conversation` with the CLI). **Collections (MCP only):** Native home-page collections group whole notebooks, separate from source labels. Use `collection_list`, `collection_create`, `collection_edit`, `collection_set_emoji`, and `collection_delete`. Editing takes the complete notebook list and sends only the delta; an unknown `collection_id` raises. Deletion requires `confirm=True` and never deletes the notebooks inside. #### CLI Commands ```bash nlm notebook list # List all notebooks nlm notebook list --json # JSON output for parsing nlm notebook list --quiet # IDs only (for scripting) nlm notebook create "Title" # Create notebook, returns ID nlm notebook create "Title" --json # Stable machine-readable ID capture nlm notebook get <id> # Get notebook details nlm notebook describe <id> # AI-generated summary + suggested topics nlm notebook query <id> "question" # One-shot Q&A with sources nlm notebook query <id> "question" --new-conversation # Start a fresh chat nlm notebook rename <id> "New Title" # Rename notebook nlm notebook delete <id> --confirm # PERMANENT deletion ``` ### 3. Source Management #### MCP Tools Use `source_add` with these `source_type` values: - `url` - Web page or YouTube URL (`url` param) - `text` - Pasted content (`text` + `title` params) - `file` - Server-local file upload (`file_path` param). The path must exist on the machine running the MCP server, not merely on the client host. Local admission is case-insensitive and follows the official 43-extension contract: OFFICIAL_FILE_EXTENSIONS: .pdf, .txt, .md, .docx, .csv, .pptx, .epub, .avif, .bmp, .gif, .heic, .heif, .ico, .jp2, .jpe, .jpeg, .jpg, .png, .tif, .tiff, .webp, .3g2, .3gp, .aac, .aif, .aifc, .aiff, .amr, .au, .avi, .cda, .m4a, .mid, .mp3, .mp4, .mpeg, .ogg, .opus, .ra, .ram, .snd, .wav, .wma Admission does not guarantee provider processing success. Corrupt, misleading, inaccessible, or reference-only files can still fail during NotebookLM ingestion. - `drive` - Google Drive doc (`document_id` + `doc_type` params) Other tools: `source_list_drive` (`skip_freshness=True` reports `stale/is_stale=null`, meaning unknown, not fresh), `source_describe`, `source_get_content`, `source_rename`, `source_sync_drive`, and