name	onenote-cli
description	Make your OneNote notebooks survive in the age of AI. Search and operate OneNote from CLI via Microsoft Graph API. Use when the user wants to search OneNote notes, list notebooks, read pages, or manage OneNote content.

onenote-cli

CLI for Microsoft OneNote via Microsoft Graph. Built with Bun + yargs + MSAL.

Quick Reference

onenote auth login                    # Device code flow login
onenote auth logout                   # Clear cached tokens
onenote auth whoami                   # Show current user
onenote auth setup                    # Show OAuth setup instructions

onenote notebooks list                # List notebooks
onenote notebooks get <id>            # Get notebook by ID
onenote notebooks create <name>       # Create notebook

onenote sections list -n <nb-id>      # List sections in a notebook
onenote sections create -n <nb> --name <name>

onenote pages list -s <sec-id>        # List pages in a section
onenote pages content <id>            # Get page HTML content
onenote pages create -s <sec> -t <title> -b <html>
onenote pages delete <id>

onenote sync                          # Build local cache (.one binary + page index)
onenote search <query>                # Full-text search across cached pages
onenote search <query> --online       # Online section-level search via Graph

Setup

See docs/setup.md for full Azure AD app registration walkthrough.

Quick setup:

Register app at https://entra.microsoft.com → App registrations → New
Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
Add platform: Mobile and desktop applications, redirect URI https://login.microsoftonline.com/common/oauth2/nativeclient
Settings → Allow public client flows: Yes
API permissions → Microsoft Graph → Delegated: Notes.Read, Notes.ReadWrite, Notes.ReadWrite.All, Files.Read, Files.Read.All, Sites.Read.All

Copy Application (client) ID into .env.local:

ONENOTE_CLIENT_ID=your-client-id-here
ONENOTE_AUTHORITY=https://login.microsoftonline.com/common

How Search Works

onenote search <query> returns page-level results with official OneNote URLs that navigate directly to the matching page (bypassing OneNote Online's session caching).

The search:

Downloads .one files via OneDrive (cached locally in <package>/.onenote/cache/)
Extracts page GUIDs from the binary
Resolves official oneNoteWebUrl via /me/onenote/sections/0-{guid}/pages (works around the 5,000-item document library limit)
Searches the binary for the query (UTF-8 + UTF-16LE) and attributes matches to the correct page using context-based lookup

See docs/local-search-architecture.md for details.

File Locations

.env.local — at the package root (auto-loaded via import.meta.dir)
Token cache — ~/.onenote-cli/msal-cache.json
Config fallback — ~/.onenote-cli/config.json
Page cache — <package>/.onenote/cache/ (override with ONENOTE_CACHE_DIR)

Common Issues

Error	Fix
`AADSTS7000218`	Enable "Allow public client flows" in app Authentication settings
`AADSTS65001`	Admin consent required for API permissions, or accept consent during login
`Graph API 403: error 10008`	Document library has > 5,000 OneNote items; use `onenote sync` and local search instead
Cache empty	Run `onenote sync` (auto-runs on first search)

onenote-cli

CLI for Microsoft OneNote via Microsoft Graph. Built with Bun + yargs + MSAL.

Quick Reference

onenote auth login # Device code flow login onenote auth logout # Clear cached tokens onenote auth whoami # Show current user onenote auth setup # Show OAuth setup instructions onenote notebooks list # List notebooks onenote notebooks get <id> # Get notebook by ID onenote notebooks create <name> # Create notebook onenote sections list -n <nb-id> # List sections in a notebook onenote sections create -n <nb> --name <name> onenote pages list -s <sec-id> # List pages in a section onenote pages content <id> # Get page HTML content onenote pages create -s <sec> -t <title> -b <html> onenote pages delete <id> onenote sync # Build local cache (.one binary + page index) onenote search <query> # Full-text search across cached pages onenote search <query> --online # Online section-level search via Graph

Setup

See docs/setup.md for full Azure AD app registration walkthrough.

Quick setup:

Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"

Add platform: Mobile and desktop applications, redirect URI https://login.microsoftonline.com/common/oauth2/nativeclient

Settings → Allow public client flows: Yes

API permissions → Microsoft Graph → Delegated: Notes.Read, Notes.ReadWrite, Notes.ReadWrite.All, Files.Read, Files.Read.All, Sites.Read.All

Copy Application (client) ID into .env.local:

ONENOTE_CLIENT_ID=your-client-id-here
ONENOTE_AUTHORITY=https://login.microsoftonline.com/common

How Search Works

onenote search <query> returns page-level results with official OneNote URLs that navigate directly to the matching page (bypassing OneNote Online's session caching).

The search:

Downloads .one files via OneDrive (cached locally in <package>/.onenote/cache/)

Extracts page GUIDs from the binary

Resolves official oneNoteWebUrl via /me/onenote/sections/0-{guid}/pages (works around the 5,000-item document library limit)

Searches the binary for the query (UTF-8 + UTF-16LE) and attributes matches to the correct page using context-based lookup

File Locations

.env.local — at the package root (auto-loaded via import.meta.dir)

Token cache — ~/.onenote-cli/msal-cache.json

Config fallback — ~/.onenote-cli/config.json

Page cache — <package>/.onenote/cache/ (override with ONENOTE_CACHE_DIR)

Common Issues

Error

Fix

AADSTS7000218

Enable "Allow public client flows" in app Authentication settings

AADSTS65001

Admin consent required for API permissions, or accept consent during login

Graph API 403: error 10008

Document library has > 5,000 OneNote items; use onenote sync and local search instead

Cache empty

Run onenote sync (auto-runs on first search)