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**: Look for tools starting with `mcp__notebooklm-mcp__*` or `mcp_notebooklm_*` 2. **If BOTH MCP tools AND CLI are available**: **ASK the user** which they prefer to use before proceeding 3. **If only MCP tools are available**: Use them directly (refer to tool docstrings for parameters) 4. **If only CLI is available**: Use `nlm` CLI commands via Bash **Decision Logic:** ``` has_mcp_tools = check_available_tools() # Look for mcp__notebooklm-mcp__* or mcp_notebooklm_* has_cli = check_bash_available() # Can run nlm commands if has_mcp_tools and has_cli: # ASK USER: "I can use either MCP tools or the nlm CLI. Which do you prefer?" user_preference = ask_user() else if has_mcp_tools: # Use MCP tools directly mcp__notebooklm-mcp__notebook_list() else: # Use CLI via Bash bash("nlm notebook list") ``` This skill documents BOTH approaches. Choose the appropriate one based on tool availability and **user preference**. ## 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 ``` ## 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 3x server error retries. Most errors are handled automatically. You only need to manually run `nlm login` if all recovery layers fail. 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)**. **Current MCP surface:** 43 tools. Consolidated action tools include `note`, `label`, `studio_status`, `batch`, `pipeline`, and `tag`. Consolidated type tools include `source_add`, `studio_create`, and `download_artifact`. ## 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> │ ├─► 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 │ ├─► 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__notebooklm-mcp__refresh_auth() # 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__notebooklm-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 --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 ``` **Multi-Profile Support**: Each profile gets its own isolated browser session (supports Chrome, Arc, Brave, Edge, Chromium, 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**: The MCP server always uses the active default profile. If you need to switch which Google account the MCP server is communicating with, you MUST use the CLI: run `nlm login switch <name>`. Your next MCP tool call will instantly use the new account. **Note**: Both MCP and CLI share the same authentication backend, so authenticating with one works for both. ### 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`. For large notebooks or long-running questions, call `notebook_query_start`, then poll `notebook_query_status(query_id)` until completed or errored. #### 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 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. Failures preserve the concrete reason and include a host-path hint. Supported: `PDF, TXT, MD, DOCX, CSV, EPUB, MP3, M4A, WAV, AAC, OGG, OPUS, MP4, JPG, JPEG, PNG, GIF, WEBP`. - `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 `source_delete`. Bulk URL add uses `source_add(source_type="url", urls=[...])`; bulk delete uses `source_delete(source_ids=[...], confirm=True)`. MCP Drive sync requires explicit source UUIDs: list first, select stale IDs, then call `source_sync_drive(source_ids=[...], confirm=True)`. #### Source Labels Use `label` with actions `auto`, `list`, `reorganize`, `create`, `rename`, `set_emoji`, `move_source`, and `delete`. Full reorganization and deletion require `confirm=True`; `reorganize(unlabeled_only=True)` does not. #### CLI Commands ```bash # Adding sources nlm source add <nb-id> --url "https://..." # Web page nlm source add <nb-id> --url "https://youtube.com/..." # YouTube video nlm source add <nb-id> --text "content" --title "X" # Pasted text nlm source add <nb-id> --drive <doc-id> # Defaults to Drive doc nlm source add <nb-id> --drive <doc-id> --type slides # Explicit type nlm source add <nb-id> --file "/path/to/diagram.png" --wait # Local file upload (images, PDFs, documents, audio, video) # Listing and viewing nlm source list <nb-id> # Table of sources nlm source list <nb-id> --drive # Show Drive sources with freshness nlm source list <nb-id> --drive -S # Skip freshness checks (faster) nlm source get <source-id> # Source metadata nlm source describe <source-id> # AI summary + keywords nlm source content <source-id> # Raw text content nlm source content <source-id> -o file.txt # Export to file # Drive sync (for stale sources) nlm source stale <nb-id> # List outdated Drive sources nlm source sync <nb-id> --confirm # Sync all stale sources nlm source sync <nb-id> --source-ids <ids> --confirm # Sync specific # Rename nlm source rename <source-id> "New Title" --notebook <nb-id> nlm rename source <source-id> "New Title" --notebook <nb-id> # verb-first # Deletion nlm source delete <source-id> --confirm ``` **Drive types**: `doc`, `slides`, `sheets`, `pdf` ### 4. Research (Source Discovery) Research finds NEW sources from the web or Google Drive. #### MCP Tools Use `research_start` with: - `source`: `web` or `drive` - `mode`: `fast` (~30s) or `deep` (~5min, web only) Preferred workflow: `research_start` → `research_status(auto_import=True)`. For manual source selection, poll without auto-import and then call `research_import`. `research_start` accepts either `notebook_id` or `title` to create a destination notebook. MCP status defaults to a 900-second wait with 30-second polling. #### CLI Commands ```bash # Start research in an existing notebook or create one with --title nlm research start "query" --notebook-id <id> # Fast web (~30s) nlm research start "query" --title "New Research" # Create destination notebook nlm research start "query" --notebook-id <id> --mode deep # Deep web (~5min) nlm research start "query" --notebook-id <id> --source drive # Drive search nlm research start "query" --notebook-id <id> --mode deep --auto-import # Check progress nlm research status <nb-id> # Poll until done nlm research status <nb-id> --max-wait 0 # Single check, no waiting nlm research status <nb-id> --task-id <tid> # Check specific task nlm research status <nb-id> --full # Full details # Import discovered sources nlm research import <nb-id> <task-id> # Import all nlm research import <nb-id> <task-id> --indices 0,2,5 # Import specific nlm research import <nb-id> <task-id> --cited-only # Import cited sources nlm research import <nb-id> <task-id> --timeout 600 # Custom timeout (default: 300s) ``` **Modes**: `fast` (~30s, ~10 sources) | `deep` (~5min, ~40+ sources, web only) ### 5. Content Generation (Studio) #### MCP Tools (Unified Creation) Use `studio_create` with `artifact_type` and type-specific options. All require `confirm=True`. `studio_create` runs a pre-flight auth check before firing the request, so stale auth fails immediately with an `nlm login` hint instead of returning a fake success that collapses seconds later. | artifact_type | Key Options | |--------------|-------------| | `audio` | `audio_format`: deep_dive/brief/critique/debate, `audio_length`: short/default/long | | `video` | `video_format`: explainer/brief/cinematic/short, `visual_style`: auto_select/classic/whiteboard/kawaii/anime/watercolor/retro_print/heritage/paper_craft (not for cinematic/short), `video_style_prompt` | | `report` | `report_format`: Briefing Doc/Study Guide/Blog Post/Create Your Own, `custom_prompt` | | `quiz` | `question_count`, `difficulty`: easy/medium/hard |