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>; most MCP tools use the active default profile. 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.

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 3x server error retries. Most errors are handled automatically. You only need to manually run nlm login if all recovery layers fail. For unattended machines, nlm auth refresh refreshes a session non-interactively (headless) from a scheduler so it never lapses between jobs.
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.
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: 50 tools. Consolidated action tools include note, label, studio_status, batch, pipeline, and tag. 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:

# Run the CLI authentication (works for both CLI and MCP)
nlm login

# Then reload tokens in MCP
mcp__gemini-notebook-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):

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

Content truncated.