--- name: nlm description: "Manages Google NotebookLM notebooks via the nlm CLI. Use for creating notebooks, listing and syncing sources, uploading files/URLs/text, chatting with sources, generating reports/audio/video/slides, running research, managing labels, editing notebook metadata (title/emoji/description/cover), and managing notebook content." when_to_use: "User mentions NotebookLM, nlm, notebook IDs, source upload/sync, chat with sources, report/audio/video/slides generation, research, labels/autolabel clusters, notebook metadata (rename/emoji/description/cover), or managing NotebookLM notes/artifacts." allowed-tools: Bash(*), Read, Glob, Grep, Write argument-hint: "[action] [args...]" --- # nlm — NotebookLM CLI ## Command Discovery Run `nlm --help` for the canonical command tree. Run `nlm --help` for command-local flags. The stable surface is noun-first: `notebook`, `source`, `note`, `artifact`, and `chat` groups. For a compact command map, read `reference/commands.md` only when needed. Always prefer live help output when it disagrees with the reference. ## Interpreting $ARGUMENTS | Argument | Action | |----------|--------| | (empty) | Run `nlm notebook list`, then ask what to do | | `create` or `new` | Create a notebook with `nlm notebook create` | | `upload` or `add` | Add one-off sources with `nlm source add` | | `sync` | Sync a directory as a managed source with `nlm source sync` | | `chat` | Start, resume, or run one-shot chat | | `research` | Run `nlm research` and choose fast/deep mode if needed | | `audio` / `video` / `slides` / `report` | Use the corresponding create or generation command | | `status` | Show notebook, sources, artifacts, and recent chats | | a notebook ID | Show details for that notebook | | a file path or glob | Upload that file/pattern to a notebook | ## Critical Practices - Surface full UUIDs for notebooks, sources, conversations, notes, and artifacts in responses. Follow-up commands need them. - Use `-y` for destructive operations in non-interactive contexts, for example `nlm -y notebook delete `. - Use `nlm auth --authuser N` or `NLM_AUTHUSER=N` for non-default Google accounts. - Use `--direct-rpc` for `audio download`; if the direct fetch is unavailable, it prints the NotebookLM browser URL. `video download` enables the required direct-RPC path itself and uses the same browser fallback. - Prefer canonical grouped commands in all new guidance. ## Common Workflows **List notebooks** ```bash nlm notebook list nlm notebook list --limit 25 nlm notebook list --all ``` **Add one-off sources** — use `source add` for files, URLs, and direct text. Pass `-` to read newline-delimited source references from stdin. ```bash nlm source add https://example.com/article nlm source add ./paper.pdf nlm source add --name "API notes" ./notes.txt printf '%s\n' ./a.pdf https://example.com/b | nlm source add - ``` **Sync a directory as one source** — `source sync` packs files into txtar, quotes nested txtar markers, chunks large payloads, and skips unchanged chunks using a content-hash cache. Use it whenever the same tree will be re-uploaded. Use `source add` for one-shot single-file/URL uploads. ```bash nlm source sync src/ nlm source sync --name "project: src/" src/ nlm source sync --dry-run . nlm source sync --force ./docs ./notes nlm source sync --json . ``` **Preview what sync will upload** — `source pack` writes the exact txtar bytes sync would upload, no network. Pipe through `txtar --list` or `txtar -x` to inspect: ```bash nlm source pack src/ | txtar --list nlm source pack src/ > preview.txtar nlm source pack --chunk 2 src/ > pt2.txtar ``` **Focus on specific sources** — `--source-ids` and `--source-match` scope chat, `generate-chat`, `generate-report`, `source-guide`, and content transforms. `--source-match` is a Go regex matched against titles and UUIDs. ```bash nlm chat --source-match 'internal/sync' "What changed?" nlm generate-chat --source-ids a,b,c "Summarize these" nlm summarize --source-match '^spec/' nlm source list | grep Q3 | nlm chat --source-ids - "Risks?" ``` **Chat and continuation** ```bash nlm chat nlm chat "What are the main conclusions?" nlm generate-chat --conversation "Follow up" nlm chat show --citations tail ``` **Research** ```bash nlm research "What changed in the source set?" nlm research --mode fast "Which docs should I read first?" nlm research --md "Write a concise brief" > report.md nlm research --import "Find source material" ``` **Content creation** — creation may take time. Poll with `artifact list`, `audio list`, or `video list`. ```bash nlm create-audio "Conversational, focus on key decisions" nlm create-video "Whiteboard walkthrough" nlm create-slides "Presentation summary" nlm generate-report --sections 3 nlm artifact list nlm --direct-rpc audio download output.wav nlm --direct-rpc video download output.mp4 ``` **Rename after stdin upload** — stdin text defaults to "Pasted Text"; use `--name` during upload or rename after: ```bash nlm source rename "descriptive name" ``` **Notebook metadata** — title, emoji, description, and cover are separate commands. `cover` takes a built-in preset ID; `cover-image` uploads a custom image. `unrecent` only hides from the recents list, it does not delete. ```bash nlm notebook rename "New Title" nlm notebook emoji "📓" nlm notebook description "One-line summary" echo "long description" | nlm notebook description nlm notebook cover 4 nlm notebook cover-image ./cover.png nlm notebook unrecent ``` **Labels (autolabel clusters)** — labels are server-side clusters over sources. `generate` and `relabel-all` are heavy server jobs (relabel-all can exceed the 60s deadline on large notebooks); `unlabeled` only touches sources without a label. `attach` takes one source per call. ```bash nlm label list nlm label generate nlm label create "Important" "⭐" nlm label rename "New Name" nlm label emoji "🐛" nlm label delete [...] nlm label unlabeled nlm label relabel-all nlm label attach ``` **Discover sources vs chat** — `discover-sources` calls a server-driven source-discovery RPC (Es3dTe) that returns ranked source IDs for a query. If the server rejects it (error or transient code-13), the CLI falls back to a regular chat call asking the model to list relevant sources. Use it to pick `--source-ids` for a follow-up; use `nlm chat` when you want a narrative answer rather than just IDs. ```bash nlm discover-sources "Q3 revenue assumptions" ``` ## Source Freshness Strategy Pick the lightest tool that does the job: - `nlm source check [notebook-id]` — Drive-only. Asks Google whether the indexed copy is still current. No re-index, no upload. Use to decide whether anything else is needed. - `nlm source refresh ` — Drive-only. Re-indexes the existing source in place. Use when `check` reports stale and the source is still a Google Drive document. - Re-upload — for non-Drive sources (files, URLs, pasted text) `check` and `refresh` do not apply. Use `nlm source delete` then `nlm source add`, or for a synced tree run `nlm source sync` (it auto-detects changed chunks; `--force` to re-upload unchanged content). **Binary upload workarounds** — if a binary upload fails, convert to text: ```bash pdftotext paper.pdf - | nlm source add --name "paper text" - plutil -convert xml1 -o - file.plist | nlm source add --name "plist text" - ``` ## Error Recovery | Error | Fix | |-------|-----| | "Authentication required" | Run `nlm auth` | | "Service unavailable" on upload | Retry after a few seconds (rate limit) | | "source limit reached" or "Failed precondition" on add | Remove unused sources or use a smaller target notebook | | "upload init failed (status 500)" | Try text extraction workaround | | `--source-match matched no sources` | Re-run `nlm source list ` and adjust the regex |