How NotebookLM Authentication Works with the CLI: A Complete Technical Guide

NotebookLM CLI authentication is handled entirely by the official Google notebooklm CLI tool, which stores OAuth tokens locally after an initial browser-based login, allowing the Python wrapper to execute commands without handling credentials directly.

The joeseesun/qiaomu-anything-to-notebooklm repository automates NotebookLM workflows by wrapping the official Google CLI. Understanding how NotebookLM CLI authentication functions is critical because the Python code never touches user credentials—it simply invokes the CLI and relies on its locally stored OAuth tokens. This architecture delegates all security concerns to Google's official tool while providing a seamless automation layer.

Initial Setup and Browser-Based Login

Before running any automated scripts, you must authenticate once using the official CLI. The repository does not implement its own authentication logic; instead, it depends on the notebooklm tool's built-in OAuth flow.

Run the initial login command:

notebooklm login

This opens a browser window where you sign in with your Google account. Upon success, the CLI stores an OAuth access token and refresh token in your home directory, typically under $HOME/.config/notebooklm/. Subsequent CLI commands automatically reuse these tokens, eliminating the need for repeated browser authentication unless the token expires or is revoked.

Verifying Authentication in check_env.py

The repository includes a dedicated verification routine in check_env.py to ensure the CLI is properly authenticated before proceeding with operations. Rather than inspecting token files directly, the script invokes notebooklm list to verify credentials through the CLI itself.

Lines 109-122 implement this check by executing:

import subprocess

def check_notebooklm_auth():
    result = subprocess.run(
        ["notebooklm", "list"],
        capture_output=True,
        text=True,
        timeout=10,
    )
    if result.returncode == 0:
        print("✅ NotebookLM 已认证")
    else:
        print("⚠️ NotebookLM 未认证（请运行 notebooklm login）")

If the command returns a zero exit code, the authentication is valid. A non-zero return indicates the user needs to run notebooklm login again.

Authentication in the Main Workflow

All NotebookLM operations in the automation workflow rely on the CLI's stored credentials. In main.py, the upload_to_notebooklm function (lines 72-90) demonstrates how the repository delegates authentication to the CLI through subprocess.run calls.

Because these subprocess commands execute under the same user environment, they automatically pick up the tokens stored by notebooklm login:

def upload_to_notebooklm(file_path, title):
    # Create a notebook using stored credentials

    subprocess.run(['notebooklm', 'create', title], capture_output=True, text=True)
    
    # Add source file—the CLI handles authentication automatically

    subprocess.run(
        ['notebooklm', 'source', 'add', file_path, '--title', title],
        capture_output=True,
        text=True,
    )

This pattern extends to all operations, including notebooklm ask for deep analysis queries. The Python code never extracts or transmits tokens; it merely triggers commands that the CLI executes using its cached OAuth session.

Handling Token Expiration and Errors

When stored tokens are missing, expired, or revoked, the CLI returns a non-zero exit code rather than failing silently. The repository detects these failures and surfaces clear warnings to the user.

In check_env.py (lines 122-124), the error handler prompts for re-authentication:

if result.returncode != 0:
    print("⚠️ NotebookLM 未认证（请运行 notebooklm login）")
    # Additional error handling logic...

This design ensures that credential issues are caught early in the workflow, preventing silent failures during automated uploads or analysis requests.

Security Model and Credential Isolation

The repository implements a strict credential isolation policy. The Python automation layer never handles secrets directly—all credential management remains confined to the official notebooklm CLI tool. This architecture provides several security benefits:

• No hardcoded tokens: Scripts contain no API keys or OAuth secrets
• Standardized storage: Tokens reside in the CLI's designated configuration directory
• Automatic refresh: The CLI manages token refresh cycles without script intervention
• Scope limitation: The Python wrapper operates with the same permissions as the authenticated CLI session, inheriting Google's security model

Summary

• NotebookLM CLI authentication requires a one-time notebooklm login that stores OAuth tokens in $HOME/.config/notebooklm/
• Verification occurs via check_env.py by invoking notebooklm list and checking for a zero exit code
• Automated workflows in main.py use subprocess.run to execute CLI commands, automatically inheriting the stored credentials
• Error handling detects expired or missing tokens through non-zero exit codes and prompts for re-authentication
• Security is maintained by keeping all credentials within the official CLI, ensuring the Python wrapper never handles sensitive tokens

Frequently Asked Questions

What happens if I try to run the script without running notebooklm login first?

The check_env.py verification will detect the missing authentication when notebooklm list returns a non-zero exit code. The script will print a warning message prompting you to run notebooklm login and exit before attempting any NotebookLM operations, preventing unauthorized API calls.

Where exactly are the OAuth tokens stored on my system?

The official notebooklm CLI stores tokens in your user configuration directory, typically located at $HOME/.config/notebooklm/ on Linux and macOS systems. The repository never reads these files directly; it only verifies authentication by executing CLI commands that internally access these stored credentials.

How can I tell if my NotebookLM authentication has expired?

Run notebooklm list manually in your terminal. If the command successfully lists your notebooks, your authentication is valid. If it returns an error or non-zero exit code, your token has expired or been revoked, and you must run notebooklm login again to refresh the credentials. The automated check_env.py script performs this same check programmatically.

Is it safe to use CLI authentication with automated scripts?

Yes, because the repository never extracts or stores the OAuth tokens in its own code. The Python scripts act as a thin wrapper that invokes the official CLI, which handles all token storage and transmission securely. This approach means your credentials remain within Google's official tooling while the automation simply triggers pre-authenticated commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}