Skip to content

configuration.md

Latest commit

 

History

History
407 lines (291 loc) · 11.4 KB

configuration.md

File metadata and controls

407 lines (291 loc) · 11.4 KB

Configuration

Status: Active Last Updated: 2026-01-20

This guide covers storage locations, environment settings, and configuration options for notebooklm-py.

File Locations

All data is stored under ~/.notebooklm/ by default, organized by profile:

~/.notebooklm/
├── active_profile        # Tracks the current profile name
├── profiles/
│   ├── default/          # Default profile (auto-created)
│   │   ├── storage_state.json    # Authentication cookies and session
│   │   ├── context.json          # CLI context (active notebook, conversation)
│   │   └── browser_profile/      # Persistent Chromium profile
│   ├── work/             # Named profile example
│   │   ├── storage_state.json
│   │   ├── context.json
│   │   └── browser_profile/
│   └── personal/
│       └── ...

Legacy layout: If upgrading from a pre-profile version, the first run auto-migrates flat files into profiles/default/. The legacy flat layout continues to work as a fallback.

You can relocate all files by setting NOTEBOOKLM_HOME:

export NOTEBOOKLM_HOME=/custom/path
# All files now go to /custom/path/profiles/<profile>/

Storage State (storage_state.json)

Contains the authentication data extracted from your browser session:

{
  "cookies": [
    {
      "name": "SID",
      "value": "...",
      "domain": ".google.com",
      "path": "/",
      "expires": 1234567890,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    },
    ...
  ],
  "origins": []
}

Required cookies: SID, HSID, SSID, APISID, SAPISID, __Secure-1PSID, __Secure-3PSID

Override location:

notebooklm --storage /path/to/storage_state.json list

Context File (context.json)

Stores the current CLI context (active notebook and conversation):

{
  "notebook_id": "abc123def456",
  "conversation_id": "conv789"
}

This file is managed automatically by notebooklm use and notebooklm clear.

Browser Profile (browser_profile/)

A persistent Chromium user data directory used during notebooklm login.

Why persistent? Google blocks automated login attempts. A persistent profile makes the browser appear as a regular user installation, avoiding bot detection.

To reset: Delete the browser_profile/ directory and run notebooklm login again.

Environment Variables

Variable Description Default
NOTEBOOKLM_HOME Base directory for all files ~/.notebooklm
NOTEBOOKLM_PROFILE Active profile name default
NOTEBOOKLM_AUTH_JSON Inline authentication JSON (for CI/CD) -
NOTEBOOKLM_LOG_LEVEL Logging level: DEBUG, INFO, WARNING, ERROR WARNING
NOTEBOOKLM_DEBUG_RPC Legacy: Enable RPC debug logging (use LOG_LEVEL=DEBUG instead) false

NOTEBOOKLM_HOME

Relocates all configuration files to a custom directory:

export NOTEBOOKLM_HOME=/custom/path

# All files now go here:
# /custom/path/profiles/<profile>/storage_state.json
# /custom/path/profiles/<profile>/context.json
# /custom/path/profiles/<profile>/browser_profile/

Use cases:

  • Per-project isolation
  • Custom storage locations

NOTEBOOKLM_PROFILE

Selects the active profile without changing the persisted default:

export NOTEBOOKLM_PROFILE=work
notebooklm list   # Uses ~/.notebooklm/profiles/work/

Equivalent to passing -p work on every command. The CLI flag takes precedence over the env var.

NOTEBOOKLM_AUTH_JSON

Provides authentication inline without writing files. Ideal for CI/CD:

export NOTEBOOKLM_AUTH_JSON='{"cookies":[...]}'
notebooklm list  # Works without any file on disk

Precedence:

  1. --storage CLI flag (highest)
  2. NOTEBOOKLM_AUTH_JSON environment variable
  3. Profile-aware path: $NOTEBOOKLM_HOME/profiles/<profile>/storage_state.json
  4. ~/.notebooklm/profiles/default/storage_state.json (default)
  5. ~/.notebooklm/storage_state.json (legacy fallback)

Note: Cannot run notebooklm login when NOTEBOOKLM_AUTH_JSON is set.

CLI Options

Global Options

Option Description Default
--storage PATH Path to storage_state.json $NOTEBOOKLM_HOME/profiles/<profile>/storage_state.json
-p, --profile NAME Use a named profile Active profile or default
-v, --verbose Enable verbose output -
--version Show version -
--help Show help -

Viewing Configuration

See where your configuration files are located:

notebooklm status --paths

Output:

                Configuration Paths
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ File            ┃ Path                                     ┃ Source    ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ Profile         │ default                                  │ active    │
│ Home Directory  │ /home/user/.notebooklm                   │ default   │
│ Storage State   │ .../profiles/default/storage_state.json  │           │
│ Context         │ .../profiles/default/context.json        │           │
│ Browser Profile │ .../profiles/default/browser_profile     │           │
└─────────────────┴──────────────────────────────────────────┴───────────┘

Session Management

Session Lifetime

Authentication sessions are tied to Google's cookie expiration:

  • Sessions typically last several days to weeks
  • Google may invalidate sessions for security reasons
  • Rate limiting or suspicious activity can trigger earlier expiration

Refreshing Sessions

Automatic Refresh: CSRF tokens and session IDs are automatically refreshed when authentication errors are detected. This handles most "session expired" errors transparently.

Manual Re-authentication: If your session cookies have fully expired (automatic refresh won't help), re-authenticate:

notebooklm login

Multiple Accounts

Profiles (recommended): Use named profiles to manage multiple Google accounts under a single home directory:

# Create and authenticate profiles
notebooklm profile create work
notebooklm -p work login
notebooklm -p work list

notebooklm profile create personal
notebooklm -p personal login
notebooklm -p personal list

# Switch the active profile
notebooklm profile switch work
notebooklm list   # Uses work profile

# List all profiles
notebooklm profile list

# Use env var for session-wide override
export NOTEBOOKLM_PROFILE=personal
notebooklm list   # Uses personal profile

Each profile stores its own storage_state.json, context.json, and browser_profile/ under ~/.notebooklm/profiles/<name>/.

Alternative: NOTEBOOKLM_HOME still works for full directory-level isolation:

export NOTEBOOKLM_HOME=~/.notebooklm-work
notebooklm login

One-off override with --storage:

notebooklm --storage /path/to/account.json list

CI/CD Configuration

GitHub Actions (Recommended)

Use NOTEBOOKLM_AUTH_JSON for secure, file-free authentication:

jobs:
  notebook-task:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install notebooklm-py
        run: pip install notebooklm-py

      - name: List notebooks
        env:
          NOTEBOOKLM_AUTH_JSON: ${{ secrets.NOTEBOOKLM_AUTH_JSON }}
        run: notebooklm list

Benefits:

  • No file writes needed
  • Secret stays in memory only
  • Clean, simple workflow

Obtaining the Secret Value

  1. Run notebooklm login locally
  2. Copy the contents of ~/.notebooklm/storage_state.json
  3. Add as a GitHub repository secret named NOTEBOOKLM_AUTH_JSON

Alternative: File-Based Auth

If you prefer file-based authentication:

- name: Setup NotebookLM auth
  run: |
    mkdir -p ~/.notebooklm/profiles/default
    echo "${{ secrets.NOTEBOOKLM_AUTH_JSON }}" > ~/.notebooklm/profiles/default/storage_state.json
    chmod 600 ~/.notebooklm/profiles/default/storage_state.json

- name: List notebooks
  run: notebooklm list

For profile-specific CI auth:

- name: Setup work profile auth
  run: |
    mkdir -p ~/.notebooklm/profiles/work
    echo "${{ secrets.WORK_AUTH_JSON }}" > ~/.notebooklm/profiles/work/storage_state.json
    chmod 600 ~/.notebooklm/profiles/work/storage_state.json

- name: List notebooks (work)
  run: notebooklm -p work list

Session Expiration

CSRF tokens are automatically refreshed during API calls. However, the underlying session cookies still expire. For long-running CI pipelines:

  • Update the NOTEBOOKLM_AUTH_JSON secret every 1-2 weeks
  • Monitor for persistent auth failures (these indicate cookie expiration)

Debugging

Enable Verbose Output

Some commands support verbose output via Rich console:

# Most errors are printed to stderr with details
notebooklm list 2>&1 | cat

Enable RPC Debug Logging

NOTEBOOKLM_DEBUG_RPC=1 notebooklm list

Check Authentication

Verify your session is working:

# Should list notebooks or show empty list
notebooklm list

# If you see "Unauthorized" or redirect errors, re-login
notebooklm login

Check Configuration Paths

# See where files are being read from
notebooklm status --paths

Network Issues

The CLI uses httpx for HTTP requests. Common issues:

  • Timeout: Google's API can be slow; large operations may time out
  • SSL errors: Ensure your system certificates are up to date
  • Proxy: Set standard environment variables (HTTP_PROXY, HTTPS_PROXY) if needed

Platform Notes

macOS

Works out of the box. Chromium is downloaded automatically by Playwright.

Linux

# Install Playwright dependencies
playwright install-deps chromium

# Then install Chromium
playwright install chromium

Windows

Works with PowerShell or CMD. Use backslashes for paths:

notebooklm --storage C:\Users\Name\.notebooklm\storage_state.json list

Or set environment variable:

$env:NOTEBOOKLM_HOME = "C:\Users\Name\custom-notebooklm"
notebooklm list

WSL

Browser login opens in the Windows host browser. The storage file is saved in the WSL filesystem.

Headless Servers & Containers

Playwright is only required for the notebooklm login command. All other operations use standard HTTP requests via httpx.

This means you can run notebooklm on headless servers, Docker containers, and CI/CD environments without Playwright—just copy a valid storage_state.json or use NOTEBOOKLM_AUTH_JSON.

# On headless machine - no Playwright needed
pip install notebooklm-py

# Copy auth from local machine, or use env var
scp ~/.notebooklm/storage_state.json user@server:~/.notebooklm/
# OR
export NOTEBOOKLM_AUTH_JSON='{"cookies": [...]}'

# All commands work except 'login'
notebooklm list
notebooklm ask "Summarize the sources"