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

> Learn how NotebookLM CLI authentication works. The official tool stores OAuth tokens locally after browser login for secure, direct command execution.

- Repository: [向阳乔木/qiaomu-anything-to-notebooklm](https://github.com/joeseesun/qiaomu-anything-to-notebooklm)
- Tags: deep-dive
- Published: 2026-05-16

---

**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:

```bash
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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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:

```python
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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`:

```python
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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/check_env.py) (lines 122-124), the error handler prompts for re-authentication:

```python
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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/check_env.py) by invoking `notebooklm list` and checking for a zero exit code
- **Automated workflows** in [`main.py`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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`](https://github.com/joeseesun/qiaomu-anything-to-notebooklm/blob/main/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.