notebooklm

Unofficial TypeScript/JavaScript client for Google NotebookLM API.

Disclaimer: This is an unofficial client that uses undocumented Google APIs. It may break at any time if Google changes their API. Use at your own risk.

Features

• Notebook Management - Create, list, rename, and delete notebooks
• Source Management - Add URLs, files, and text as sources
• Chat Interface - Query your notebooks with AI-powered conversations
• Content Generation - Generate podcasts, videos, reports, quizzes, and more
• Research Mode - Discover and import web/Drive sources
• CLI Tool - Full-featured command-line interface
• TypeScript Support - Full type definitions included

Installation

# Using npx (no install required)
npx notebooklm login

# Using npm
npm install -g notebooklm

# Using bun
bun add -g notebooklm

Install Playwright for Authentication

The login command requires Playwright to automate browser authentication:

# Install Playwright browsers
npx playwright install chromium

Quick Start

1. Authenticate

First, authenticate with your Google account:

npx notebooklm login

This opens a browser window for you to log in. After successful login, press Enter in the terminal to save your session.

2. Use the CLI

# List all notebooks
npx notebooklm list

# Create a new notebook
npx notebooklm notebook create "My Research"

# Add a source
npx notebooklm source add <notebook-id> https://example.com/article

# Ask a question
npx notebooklm ask <notebook-id> "Summarize the main points"

3. Use the API

import { NotebookLMClient } from 'notebooklm';

// Create client from saved session
const client = await NotebookLMClient.fromStorage();

// List notebooks
const notebooks = await client.notebooks.list();
console.log(notebooks);

// Create a notebook
const notebook = await client.notebooks.create('My Research');

// Add a source
const source = await client.sources.addUrl(notebook.id, 'https://example.com');

// Ask a question
const response = await client.chat.ask(notebook.id, 'What is this about?');
console.log(response.answer);

CLI Reference

Authentication

# Login with Google account (opens browser)
notebooklm login

# Login with custom storage path
notebooklm login --output ~/.config/notebooklm/session.json

# Login in headless mode (not recommended)
notebooklm login --headless

Notebooks

# List all notebooks
notebooklm list
notebooklm notebook list

# Create a notebook
notebooklm create "Title"
notebooklm notebook create "Title"

# Get notebook info
notebooklm notebook info <notebook-id>

# Rename a notebook
notebooklm notebook rename <notebook-id> "New Title"

# Delete a notebook
notebooklm notebook delete <notebook-id>
notebooklm notebook delete <notebook-id> --force  # Skip confirmation

Sources

# List sources in a notebook
notebooklm source list <notebook-id>

# Add a URL source
notebooklm source add <notebook-id> https://example.com
notebooklm source add <notebook-id> https://example.com --wait  # Wait for processing

# Add a file source
notebooklm source add-file <notebook-id> ./document.pdf
notebooklm source add-file <notebook-id> ./document.pdf --wait

# Add text source
notebooklm source add-text <notebook-id> "Title" --content "Text content..."
notebooklm source add-text <notebook-id> "Title" --file ./content.txt

# Delete a source
notebooklm source delete <notebook-id> <source-id>

# Rename a source
notebooklm source rename <notebook-id> <source-id> "New Title"

# Refresh a URL/Drive source
notebooklm source refresh <notebook-id> <source-id>

Chat

# Ask a question
notebooklm ask <notebook-id> "Your question here"

# Interactive chat mode
notebooklm chat <notebook-id>

Content Generation

# Generate audio podcast
notebooklm generate audio <notebook-id>
notebooklm generate audio <notebook-id> --wait  # Wait for completion

# Generate video
notebooklm generate video <notebook-id>

# Generate report
notebooklm generate report <notebook-id> --format briefing
notebooklm generate report <notebook-id> --format study-guide
notebooklm generate report <notebook-id> --format blog

# Generate quiz
notebooklm generate quiz <notebook-id>
notebooklm generate quiz <notebook-id> --difficulty hard

Research

# Start web research
notebooklm research web <notebook-id> "search query"

# Start Drive research
notebooklm research drive <notebook-id> "search query"

Global Options

# Enable debug logging
notebooklm --debug <command>

# Show version
notebooklm --version

# Show help
notebooklm --help
notebooklm <command> --help

API Reference

NotebookLMClient

The main client class for interacting with NotebookLM.

import { NotebookLMClient } from 'notebooklm';

// Create from saved session (default path: ~/.notebooklm/storage-state.json)
const client = await NotebookLMClient.fromStorage();

// Create from custom path
const client = await NotebookLMClient.fromStorage('/path/to/session.json');

// Create from environment variable
process.env.NOTEBOOKLM_STORAGE_STATE = JSON.stringify(storageState);
process.env.NOTEBOOKLM_STORAGE_PATH = ':inline:';
const client = await NotebookLMClient.fromStorage();

Notebooks API

// List all notebooks
const notebooks = await client.notebooks.list();

// Create a notebook
const notebook = await client.notebooks.create('Title');

// Get notebook details
const notebook = await client.notebooks.get('notebook-id');

// Get notebook description and suggested topics
const description = await client.notebooks.getDescription('notebook-id');

// Rename a notebook
await client.notebooks.rename('notebook-id', 'New Title');

// Delete a notebook
await client.notebooks.delete('notebook-id');

// Share/unshare a notebook
await client.notebooks.share('notebook-id', true);  // Make public
await client.notebooks.share('notebook-id', false); // Make private

// Get share URL
const url = await client.notebooks.getShareUrl('notebook-id');

Sources API

// List sources
const sources = await client.sources.list('notebook-id');

// Add URL source
const source = await client.sources.addUrl('notebook-id', 'https://example.com');

// Add file source
const content = await Bun.file('./document.pdf').arrayBuffer();
const source = await client.sources.addFile(
  'notebook-id',
  'document.pdf',
  new Uint8Array(content),
  'application/pdf'
);

// Add text source
const source = await client.sources.addText('notebook-id', 'Title', 'Content...');

// Wait for source processing
const ready = await client.sources.waitUntilReady('notebook-id', 'source-id');

// Get source guide (AI-generated summary)
const guide = await client.sources.getGuide('notebook-id', 'source-id');

// Get source full text
const fulltext = await client.sources.getFulltext('notebook-id', 'source-id');

// Delete source
await client.sources.delete('notebook-id', 'source-id');

// Rename source
await client.sources.rename('notebook-id', 'source-id', 'New Title');

// Refresh URL/Drive source
await client.sources.refresh('notebook-id', 'source-id');

Chat API

// Ask a question
const response = await client.chat.ask('notebook-id', 'Your question');
console.log(response.answer);
console.log(response.references); // Source citations

// Continue conversation
const followUp = await client.chat.ask(
  'notebook-id',
  'Follow-up question',
  response.conversationId
);

// Get chat history
const history = await client.chat.getHistory('notebook-id');

// Configure chat mode
await client.chat.configure('notebook-id', {
  mode: 'guided',      // 'default' | 'guided' | 'critical'
  responseLength: 'comprehensive'  // 'concise' | 'balanced' | 'comprehensive'
});

Artifacts API

// List artifacts (generated content)
const artifacts = await client.artifacts.list('notebook-id');

// Generate audio podcast
const audio = await client.artifacts.generateAudio('notebook-id', {
  format: 'mp3',
  length: 'medium',
  instructions: 'Focus on key findings'
});

// Generate video
const video = await client.artifacts.generateVideo('notebook-id', {
  style: 'documentary'
});

// Generate report
const report = await client.artifacts.generateReport('notebook-id', {
  format: 'briefing'
});

// Generate quiz
const quiz = await client.artifacts.generateQuiz('notebook-id', {
  difficulty: 'medium',
  questionCount: 10
});

// Wait for generation to complete
const completed = await client.artifacts.waitForGeneration('notebook-id', 'artifact-id');

// Download generated content
const audioBuffer = await client.artifacts.downloadAudio('notebook-id', 'artifact-id');
const videoBuffer = await client.artifacts.downloadVideo('notebook-id', 'artifact-id');

Research API

// Start web research
const research = await client.research.startWeb('notebook-id', 'search query');

// Start Drive research
const research = await client.research.startDrive('notebook-id', 'search query');

// Poll research status
const status = await client.research.poll('notebook-id', research.id);

// Import discovered sources
await client.research.importSources('notebook-id', research.id, ['source-1', 'source-2']);

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NOTEBOOKLM_STORAGE_PATH | Path to session storage file | ~/.notebooklm/storage-state.json | | NOTEBOOKLM_STORAGE_STATE | Inline JSON storage state (use with :inline: path) | - | | LOG_LEVEL | Logging level (debug, info, warn, error) | info |

Storage Paths

The client stores authentication data in the following locations:

| Platform | Default Path | |----------|--------------| | macOS | ~/.notebooklm/storage-state.json | | Linux | ~/.notebooklm/storage-state.json | | Windows | %USERPROFILE%\.notebooklm\storage-state.json |

TypeScript Types

import type {
  Notebook,
  Source,
  Artifact,
  AskResult,
  ChatReference,
  GenerationStatus,
  NotebookDescription,
} from 'notebooklm';

Error Handling

import { RPCError, AuthError, SourceError } from 'notebooklm';

try {
  await client.notebooks.list();
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Authentication failed. Please run: notebooklm login');
  } else if (error instanceof RPCError) {
    console.error('API error:', error.message, error.rpcId);
  } else {
    throw error;
  }
}

Development

# Clone the repository
git clone https://github.com/kaelen/notebooklm.git
cd notebooklm

# Install dependencies
bun install

# Run CLI in development
bun run cli list

# Type check
bun run type-check

# Build for distribution
bun run build

# Run tests
bun test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

This project is a TypeScript port of notebooklm-py.

Disclaimer

This is an unofficial project and is not affiliated with, officially maintained, authorized, or sponsored by Google. The NotebookLM API is undocumented and may change at any time. Use this library at your own risk.