# Nlm Skill

> Expert guide for the NotebookLM CLI (`nlm`) and MCP server - interfaces for Google NotebookLM. Use this skill when users want to interact with NotebookLM programmatically, including: creating/managing notebooks, adding sources (URLs, YouTube, text, Google Drive), generating content (podcasts, reports, quizzes, flashcards, mind maps, slides, infographics, videos, data tables), conducting research,…

- **Type:** Skill
- **Install:** `agentstack add skill-jacob-bd-notebooklm-mcp-cli-data`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jacob-bd](https://agentstack.voostack.com/s/jacob-bd)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jacob-bd](https://github.com/jacob-bd)
- **Source:** https://github.com/jacob-bd/notebooklm-mcp-cli/tree/main/src/notebooklm_tools/data

## Install

```sh
agentstack add skill-jacob-bd-notebooklm-mcp-cli-data
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# NotebookLM CLI & MCP Expert

This skill provides comprehensive guidance for using NotebookLM 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  --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. **⚠️ 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.
4. **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.
5. **Research needs a destination**: Pass `--notebook-id ` for an existing notebook or `--title ` to create one.
6. **Capture IDs from output**: Create/start commands return IDs needed for subsequent operations
7. **Use aliases**: Simplify long UUIDs with `nlm alias set  `
8. **Check aliases before creating**: Run `nlm alias list` before creating a new alias to avoid conflicts with existing names.
9. **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.
10. **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.
11. **Use `--help` when unsure**: Run `nlm  --help` to see available options and flags for any command.
12. **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:** 39 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  --url "https://..."
│   ├─► From YouTube → nlm source add  --url "https://youtube.com/..."
│   ├─► From pasted text → nlm source add  --text "content" --title "Title"
│   ├─► From Google Drive → nlm source add  --drive  --type doc
│   └─► Discover new sources → nlm research start "query" --notebook-id 
│
├─► Generate content from sources (→ Studio Prompting for optimal focus_prompt)
│   ├─► Podcast/Audio → nlm audio create  --confirm
│   ├─► Written summary → nlm report create  --confirm
│   ├─► Study materials → nlm quiz/flashcards create  --confirm
│   ├─► Visual content → nlm mindmap/slides/infographic create  --confirm
│   ├─► Video → nlm video create  --confirm
│   └─► Extract data → nlm data-table create  "description" --confirm
│
├─► Refactor, critique, or improve a draft document
│   └─► See Workflow 15 in references/workflows.md
│
├─► Ask questions about sources
│   └─► nlm notebook query  "question"
│       (Use --conversation-id for follow-ups)
│       ⚠️ Do NOT use `nlm chat start` - it's a REPL for humans only
│
├─► Check generation status
│   └─► nlm studio status 
│
└─► Manage/cleanup
    ├─► List notebooks → nlm notebook list
    ├─► List sources → nlm source list 
    ├─► Delete source → nlm source delete  --confirm
    └─► Delete notebook → nlm notebook delete  --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="")
```
```

#### 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           # Switch the default profile
nlm login profile list              # List all profiles with email addresses
nlm login profile delete      # Delete a profile
nlm login profile rename   # 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 `. 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                   # Get notebook details
nlm notebook describe              # AI-generated summary + suggested topics
nlm notebook query  "question"     # One-shot Q&A with sources
nlm notebook rename  "New Title"   # Rename notebook
nlm notebook delete  --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  --url "https://..."           # Web page
nlm source add  --url "https://youtube.com/..." # YouTube video
nlm source add  --text "content" --title "X"  # Pasted text
nlm source add  --drive               # Defaults to Drive doc
nlm source add  --drive  --type slides # Explicit type
nlm source add  --file "/path/to/diagram.png" --wait # Local file upload (images, PDFs, documents, audio, video)

# Listing and viewing
nlm source list                 # Table of sources
nlm source list  --drive        # Show Drive sources with freshness
nlm source list  --drive -S     # Skip freshness checks (faster)
nlm source get              # Source metadata
nlm source describe         # AI summary + keywords
nlm source content          # Raw text content
nlm source content  -o file.txt  # Export to file

# Drive sync (for stale sources)
nlm source stale                # List outdated Drive sources
nlm source sync  --confirm      # Sync all stale sources
nlm source sync  --source-ids  --confirm  # Sync specific

# Rename
nlm source rename  "New Title" --notebook 
nlm rename source  "New Title" --notebook   # verb-first

# Deletion
nlm source delete  --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               # Fast web (~30s)
nlm research start "query" --title "New Research"           # Create destination notebook
nlm research start "query" --notebook-id  --mode deep  # Deep web (~5min)
nlm research start "query" --notebook-id  --source drive  # Drive search
nlm research start "query" --notebook-id  --mode deep --auto-import

# Check progress
nlm research status                    # Poll until done
nlm research status  --max-wait 0      # Single check, no waiting
nlm research status  --task-id    # Check specific task
nlm research status  --full            # Full details

# Import discovered sources
nlm research import              # Import all
nlm research import   --indices 0,2,5  # Import specific
nlm research import   --cited-only      # Import cited sources
nlm research import   --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, `visual_style`: auto_select/classic/whiteboard/kawaii/anime/watercolor/retro_print/heritage/paper_craft (not for cinematic), `video_style_prompt` |
| `report` | `report_format`: Briefing Doc/Study Guide/Blog Post/Create Your Own, `custom_prompt` |
| `quiz` | `question_count`, `difficulty`: easy/medium/hard |
| `flashcards` | `difficulty`: easy/medium/hard |
| `mind_map` | `title` |
| `slide_deck` | `slide_format`: detailed_deck/presenter_slides, `slide_length`: short/default |
| `infographic` | `orientation`: landscape/portrait/square, `detail_level`: concise/standard/detailed, `infographic_style`: auto_select/sketch_note/professional/bento_grid/editorial/instructional/bricks/clay/anime/kawaii/scientific |
| `data_table` | `description` (REQUIRED) |

**Common options**: `source_ids`, `language` (BCP-47 code, including regional
locales such as `es-419`), `focus_prompt`

**Audio accent:** NotebookLM has been observed using the `language` region
subtag, not the prompt, to choose the Audio Overview accent. For example,
`es`/`es-ES` produces Spain Spanish, while `es-US`/`es-419` produces
Latin-American Spanish. `NOTEBOOKLM_HL` can set the same regional locale as
the default. Treat this as observed upstream behavior, not a guaranteed API
contract.

**Revise Slides:** Use `studio_revise` to revise individual slides in an existing slide deck.
- Requires `artifact_id` (from `studio_status`) and `slide_instructions`
- Creates a NEW artifact — the original is not modified
- Slide numbers are 1-based (slide 1 = first slide)
- Poll `studio_status` after calling to check when the new deck is ready

#### CLI Commands

All generation commands share `--confirm`, `--source-ids`, and `--profile`.
`--language` is available for audio, report, slides, infographic, video, and
data-table:
- `--confirm` or `-y`: **REQUIRED** to execute
- `--source-ids `: Limit to specific sources
- `--language `: BCP-47 code (`en`, `es-ES`, `es-US`, `es-419`, `fr`, etc.)

```bash
# Audio (Podcast)
nlm audio create  --confirm
nlm audio create  --format deep_dive --length default --confirm
nlm audio create  --format brief --focus "key topic" --confirm
# Formats: deep_dive, brief, critique, debate
# Lengths: short, default, long

# Report
nlm report create  --confirm
nlm report create  --format "Study Guide" --confirm
nlm report create  --format "Create Your Own" --prompt "Custom..." --confirm
# Formats: "Briefing Doc", "Study Guide", "Blog Post", "Create Your Own"

# Quiz
nlm quiz create  --confirm
nlm quiz create  --c

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jacob-bd](https://github.com/jacob-bd)
- **Source:** [jacob-bd/notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jacob-bd-notebooklm-mcp-cli-data
- Seller: https://agentstack.voostack.com/s/jacob-bd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.