1# NotebookLM Skill API Reference
2 
3Complete API documentation for all NotebookLM skill modules.
4 
5## Important: Always Use run.py Wrapper
6 
7**All commands must use the `run.py` wrapper to ensure proper environment:**
8 
9```bash
10# ✅ CORRECT:
11python scripts/run.py [script_name].py [arguments]
12 
13# ❌ WRONG:
14python scripts/[script_name].py [arguments]  # Will fail without venv!
15```
16 
17## Core Scripts
18 
19### ask_question.py
20Query NotebookLM with automated browser interaction.
21 
22```bash
23# Basic usage
24python scripts/run.py ask_question.py --question "Your question"
25 
26# With specific notebook
27python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
28 
29# With direct URL
30python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
31 
32# Show browser (debugging)
33python scripts/run.py ask_question.py --question "..." --show-browser
34```
35 
36**Parameters:**
37- `--question` (required): Question to ask
38- `--notebook-id`: Use notebook from library
39- `--notebook-url`: Use URL directly
40- `--show-browser`: Make browser visible
41 
42**Returns:** Answer text with follow-up prompt appended
43 
44### notebook_manager.py
45Manage notebook library with CRUD operations.
46 
47```bash
48# Smart Add (discover content first)
49python scripts/run.py ask_question.py --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" --notebook-url "[URL]"
50# Then add with discovered info
51python scripts/run.py notebook_manager.py add \
52  --url "https://notebooklm.google.com/notebook/..." \
53  --name "Name" \
54  --description "Description" \
55  --topics "topic1,topic2"
56 
57# Direct add (when you know the content)
58python scripts/run.py notebook_manager.py add \
59  --url "https://notebooklm.google.com/notebook/..." \
60  --name "Name" \
61  --description "What it contains" \
62  --topics "topic1,topic2"
63 
64# List notebooks
65python scripts/run.py notebook_manager.py list
66 
67# Search notebooks
68python scripts/run.py notebook_manager.py search --query "keyword"
69 
70# Activate notebook
71python scripts/run.py notebook_manager.py activate --id notebook-id
72 
73# Remove notebook
74python scripts/run.py notebook_manager.py remove --id notebook-id
75 
76# Show statistics
77python scripts/run.py notebook_manager.py stats
78```
79 
80**Commands:**
81- `add`: Add notebook (requires --url, --name, --topics)
82- `list`: Show all notebooks
83- `search`: Find notebooks by keyword
84- `activate`: Set default notebook
85- `remove`: Delete from library
86- `stats`: Display library statistics
87 
88### auth_manager.py
89Handle Google authentication and browser state.
90 
91```bash
92# Setup (browser visible for login)
93python scripts/run.py auth_manager.py setup
94 
95# Check status
96python scripts/run.py auth_manager.py status
97 
98# Re-authenticate
99python scripts/run.py auth_manager.py reauth
100 
101# Clear authentication
102python scripts/run.py auth_manager.py clear
103```
104 
105**Commands:**
106- `setup`: Initial authentication (browser MUST be visible)
107- `status`: Check if authenticated
108- `reauth`: Clear and re-setup
109- `clear`: Remove all auth data
110 
111### cleanup_manager.py
112Clean skill data with preservation options.
113 
114```bash
115# Preview cleanup
116python scripts/run.py cleanup_manager.py
117 
118# Execute cleanup
119python scripts/run.py cleanup_manager.py --confirm
120 
121# Keep library
122python scripts/run.py cleanup_manager.py --confirm --preserve-library
123 
124# Force without prompt
125python scripts/run.py cleanup_manager.py --confirm --force
126```
127 
128**Options:**
129- `--confirm`: Actually perform cleanup
130- `--preserve-library`: Keep notebook library
131- `--force`: Skip confirmation prompt
132 
133### run.py
134Script wrapper that handles environment setup.
135 
136```bash
137# Usage
138python scripts/run.py [script_name].py [arguments]
139 
140# Examples
141python scripts/run.py auth_manager.py status
142python scripts/run.py ask_question.py --question "..."
143```
144 
145**Automatic actions:**
1461. Creates `.venv` if missing
1472. Installs dependencies
1483. Activates environment
1494. Executes target script
150 
151## Python API Usage
152 
153### Using subprocess with run.py
154 
155```python
156import subprocess
157import json
158 
159# Always use run.py wrapper
160result = subprocess.run([
161    "python", "scripts/run.py", "ask_question.py",
162    "--question", "Your question",
163    "--notebook-id", "notebook-id"
164], capture_output=True, text=True)
165 
166answer = result.stdout
167```
168 
169### Direct imports (after venv exists)
170 
171```python
172# Only works if venv is already created and activated
173from notebook_manager import NotebookLibrary
174from auth_manager import AuthManager
175 
176library = NotebookLibrary()
177notebooks = library.list_notebooks()
178 
179auth = AuthManager()
180is_auth = auth.is_authenticated()
181```
182 
183## Data Storage
184 
185Location: `~/.claude/skills/notebooklm/data/`
186 
187```
188data/
189├── library.json       # Notebook metadata
190├── auth_info.json     # Auth status
191└── browser_state/     # Browser cookies
192    └── state.json
193```
194 
195**Security:** Protected by `.gitignore`, never commit.
196 
197## Environment Variables
198 
199Optional `.env` file configuration:
200 
201```env
202HEADLESS=false           # Browser visibility
203SHOW_BROWSER=false       # Default display
204STEALTH_ENABLED=true     # Human behavior
205TYPING_WPM_MIN=160       # Typing speed
206TYPING_WPM_MAX=240
207DEFAULT_NOTEBOOK_ID=     # Default notebook
208```
209 
210## Error Handling
211 
212Common patterns:
213 
214```python
215# Using run.py prevents most errors
216result = subprocess.run([
217    "python", "scripts/run.py", "ask_question.py",
218    "--question", "Question"
219], capture_output=True, text=True)
220 
221if result.returncode != 0:
222    error = result.stderr
223    if "rate limit" in error.lower():
224        # Wait or switch accounts
225        pass
226    elif "not authenticated" in error.lower():
227        # Run auth setup
228        subprocess.run(["python", "scripts/run.py", "auth_manager.py", "setup"])
229```
230 
231## Rate Limits
232 
233Free Google accounts: 50 queries/day
234 
235Solutions:
2361. Wait for reset (midnight PST)
2372. Switch accounts with `reauth`
2383. Use multiple Google accounts
239 
240## Advanced Patterns
241 
242### Parallel Queries
243 
244```python
245import concurrent.futures
246import subprocess
247 
248def query(question, notebook_id):
249    result = subprocess.run([
250        "python", "scripts/run.py", "ask_question.py",
251        "--question", question,
252        "--notebook-id", notebook_id
253    ], capture_output=True, text=True)
254    return result.stdout
255 
256# Run multiple queries simultaneously
257with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
258    futures = [
259        executor.submit(query, q, nb)
260        for q, nb in zip(questions, notebooks)
261    ]
262    results = [f.result() for f in futures]
263```
264 
265### Batch Processing
266 
267```python
268def batch_research(questions, notebook_id):
269    results = []
270    for question in questions:
271        result = subprocess.run([
272            "python", "scripts/run.py", "ask_question.py",
273            "--question", question,
274            "--notebook-id", notebook_id
275        ], capture_output=True, text=True)
276        results.append(result.stdout)
277        time.sleep(2)  # Avoid rate limits
278    return results
279```
280 
281## Module Classes
282 
283### NotebookLibrary
284- `add_notebook(url, name, topics)`
285- `list_notebooks()`
286- `search_notebooks(query)`
287- `get_notebook(notebook_id)`
288- `activate_notebook(notebook_id)`
289- `remove_notebook(notebook_id)`
290 
291### AuthManager
292- `is_authenticated()`
293- `setup_auth(headless=False)`
294- `get_auth_info()`
295- `clear_auth()`
296- `validate_auth()`
297 
298### BrowserSession (internal)
299- Handles browser automation
300- Manages stealth behavior
301- Not intended for direct use
302 
303## Best Practices
304 
3051. **Always use run.py** - Ensures environment
3062. **Check auth first** - Before operations
3073. **Handle rate limits** - Implement retries
3084. **Include context** - Questions are independent
3095. **Clean sessions** - Use cleanup_manager