Skip to content

CLI Overview

Command-line interface for the NotebookLM Enterprise API.

Command Structure

nblm [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS]

Global Options

Options that can be used with any command:

Option Description Required Default
--auth <METHOD> Authentication method: gcloud or env Yes -
--project-number <NUMBER> Google Cloud project number Yes* From env
--location <LOCATION> API location: global, us, or eu No global
--endpoint-location <LOCATION> Endpoint location (must match --location) No global
--json Output in JSON format No false
--debug-http Print raw HTTP responses to stderr No false
-h, --help Print help information No -
-V, --version Print version information No -

*Can be set via NBLM_PROJECT_NUMBER environment variable.

Commands

Command Description Documentation
doctor Run environment diagnostics doctor.md
notebooks Manage notebooks notebooks.md
sources Manage notebook sources sources.md
audio Manage audio overviews audio.md
share Share notebooks with users share.md

Authentication

Two authentication methods are supported:

gcloud auth login
nblm --auth gcloud notebooks recent
# or let environment variables fill in project details
nblm --auth gcloud --project-number "$NBLM_PROJECT_NUMBER" notebooks recent

Environment Variable

export NBLM_ACCESS_TOKEN=$(gcloud auth print-access-token)
nblm --auth env notebooks recent

See Authentication Guide for details.

Environment Variables

Reduce command verbosity by setting environment variables:

export NBLM_PROJECT_NUMBER="123456789012"
export NBLM_LOCATION="global"
export NBLM_ENDPOINT_LOCATION="global"

# Now you can omit these flags
nblm notebooks recent

Raw HTTP Logging

Use the new --debug-http flag (or set NBLM_DEBUG_HTTP=1) to print the raw JSON payload returned by the API. Logged bodies may contain sensitive data, so enable this only on trusted machines.

Output Formats

Human-Readable (Default)

nblm notebooks recent

Output:

Title: My Notebook
Notebook ID: abc123
Updated: 2025-10-25T10:30:00Z

JSON Format

nblm --json notebooks recent

Output:

{
  "notebooks": [
    {
      "title": "My Notebook",
      "notebookId": "abc123",
      "updateTime": "2025-10-25T10:30:00Z"
    }
  ]
}

The --json flag can be placed anywhere in the command:

# All equivalent
nblm --json notebooks recent
nblm notebooks recent --json

Error Handling

Exit Codes

Code Description
0 Success
1 General error
2 Authentication error

Automatic Retries

The CLI automatically retries transient failures (HTTP 429, 500, 502, 503, 504) with exponential backoff.

Error Messages

Errors are printed to stderr in a human-readable format:

Error: Failed to create notebook
Cause: API returned 403 Forbidden

In JSON mode, errors are also in JSON format:

{
  "error": "Failed to create notebook",
  "cause": "API returned 403 Forbidden"
}

Getting Help

General Help

nblm --help

Command-Specific Help

nblm notebooks --help
nblm sources add --help

Examples

Quick Start

# Set up
export NBLM_PROJECT_NUMBER="123456789012"
gcloud auth login

# Create notebook
nblm notebooks create --title "My Notebook"

# List notebooks
nblm notebooks recent

# Add source
nblm sources add \
  --notebook-id abc123 \
  --web-url "https://example.com"

JSON Output with jq

# Get all notebook titles
nblm --json notebooks recent | jq '.notebooks[].title'

# Get first notebook ID
nblm --json notebooks recent | jq -r '.notebooks[0].notebookId'

# Count notebooks
nblm --json notebooks recent | jq '.notebooks | length'

Next Steps