nblm-rs

Unofficial NotebookLM Enterprise API client

🦀 Rust CLI: Command-line tool for shell scripting and automation 🐍 Python SDK: Python bindings for integration in Python applications

[!IMPORTANT] This project targets the NotebookLM Enterprise API only. Google hasn’t published an API for the consumer edition or general Google Workspace tenants as of 2025-10-25.

Motivation

In September 2025, Google released the NotebookLM Enterprise API, enabling programmatic access to NotebookLM features for the first time.

While you can interact with the API using simple curl commands, this approach has several limitations that this project addresses:

Challenges with Direct API Calls

• Authentication complexity

  • Problem: Managing OAuth tokens, handling token refresh, and ensuring secure credential storage
  • Solution: Seamless gcloud CLI integration with automatic token caching and refresh

• Manual request construction

  • Problem: Writing JSON payloads by hand, managing resource names, and handling API versioning
  • Solution: Type-safe CLI flags and Python SDK with intelligent defaults and validation

• Error handling

  • Problem: Cryptic HTTP error codes without context or recovery suggestions
  • Solution: Clear, actionable error messages with automatic retries for transient failures

• Repeated operations

  • Problem: Writing boilerplate loops for fetch/add/delete sequences
  • Solution: Higher-level client helpers and CLI flags that wrap single API calls (with retries built in) so scripts stay concise

• Output parsing

  • Problem: Manual JSON parsing and extracting specific fields from responses
  • Solution: Structured response objects in the Python SDK and --json output in the CLI for easy integration with tools like jq

Project Goals

This project provides production-ready tools that make the NotebookLM API accessible and reliable:

• Rust CLI: Fast, cross-platform binary for shell scripting and automation
• Python SDK: Idiomatic Python bindings for application integration
• Type safety: Compile-time checks prevent common API usage errors
• Developer experience: Intuitive commands and clear documentation

Installation

CLI

# macOS
brew tap k-dash/nblm https://github.com/K-dash/homebrew-nblm
brew install k-dash/nblm/nblm

# Linux (prebuilt binaries)
# Download from Releases page: https://github.com/K-dash/nblm-rs/releases

# From source
cargo install nblm-cli

Python SDK

pip install nblm
# or
uv add nblm

Prerequisite: a Google Cloud project with the NotebookLM Enterprise API enabled and either gcloud auth login or an OAuth token ready for NBLM_ACCESS_TOKEN.

For detailed installation instructions and troubleshooting, see the Installation Guide.

Quick Start

CLI

# 1. Authenticate
gcloud auth login

# 2. Set environment variables
export NBLM_PROJECT_NUMBER="123456789012"  # Get from GCP console
export NBLM_LOCATION="global"
export NBLM_ENDPOINT_LOCATION="global"

# 3. Create a notebook
nblm notebooks create --title "My Notebook"

# 4. Add a source
nblm sources add \
  --notebook-id YOUR_NOTEBOOK_ID \
  --web-url "https://example.com" \
  --web-name "Example"

Python

from nblm import NblmClient, GcloudTokenProvider, WebSource

# Initialize client
client = NblmClient(
    token_provider=GcloudTokenProvider(),
    project_number="123456789012"
)

# Create a notebook
notebook = client.create_notebook(title="My Notebook")

# Add sources
response = client.add_sources(
    notebook_id=notebook.notebook_id,
    web_sources=[WebSource(url="https://example.com", name="Example")]
)

Features

[!NOTE] The NotebookLM API is currently in alpha. Some features may not work as documented due to API limitations. See the complete feature list in the documentation.

nblm-rs supports the following NotebookLM API operations:

• Notebooks: Create, list, and delete notebooks
• Sources: Add web URLs, text, videos (YouTube), Google Drive files, and upload files
• Audio Overview: Create and delete audio overviews
• Sharing: Share notebooks with users (CLI only, untested)

For detailed feature status and limitations, see the Features documentation.

Documentation

Complete guides and API references:

📖 Full Documentation - Complete guides, API references, and examples

• Getting Started - Installation, authentication, configuration
• CLI Reference - All commands, options, and examples
• Python SDK Reference - API reference and usage patterns

Known API Issues

[!NOTE] The NotebookLM API is currently in alpha and has several known limitations. See API Limitations for details.

Related Resources

• NotebookLM API Documentation - Official API documentation
• NotebookLM API Reference - API reference

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

License

MIT