Use OneNote from a terminal

Why a terminal client

Microsoft does not ship OneNote for Linux, and many workplaces will not let you install it at all. The web app covers reading, but it is a poor fit for the thing people actually want from a shell: capturing what just happened without leaving the shell.

Install

The client is published to npm as onenotesystem ↗, and its source is at onenote-terminal ↗. It needs Node.js 18.17 or newer and has no other dependencies.

npm install -g onenotesystem

That installs two commands: onenotesystem and the shorter alias ons. To try it without installing anything, run npx onenotesystem --help.

Getting help

Every command documents itself, so you should rarely need this page once it is installed. --help and -h work at the top level and on each command, and help <command> does the same thing.

onenotesystem --help              # commands, configuration, exit codes
onenotesystem capture --help      # every flag capture accepts, with examples
onenotesystem help append         # the same, spelled the other way

Aliases resolve too, so onenotesystem new -h shows the capture help.

Configure

You need your deployment address and an API key from Setup Step 5 — the same key a Shortcut would use. One key can be shared by both, though a separate key per device is easier to revoke.

$ onenotesystem configure
OneNote System deployment URL: https://my-onenote-system.vercel.app
API key (input hidden):
Checking the deployment...
Reached onenote-system.
Saved configuration to /home/you/.config/onenotesystem/config.json

The key is saved to a file only your user account can read: ~/.config/onenotesystem/config.json on Linux and macOS, or %APPDATA%\onenotesystem\config.json on Windows. It is never printed back to the terminal.

Configuring without prompts

Pass the values as flags when you are setting up a server or a container:

onenotesystem configure --url https://my-onenote-system.vercel.app --api-key "$KEY" --default-page "Quick Inbox"

Or skip the file entirely. Environment variables take precedence over it, which is what you want in CI:

Check that it works

doctor tests the deployment, its database, and your API key separately, so a failure tells you which one is wrong.

$ onenotesystem doctor
Deployment URL: https://my-onenote-system.vercel.app  (from config file)
API key:        set (from config file)
Default page:   Quick Inbox  (from config file)
Service:        onenote-system
Database:       reachable
Key:            accepted

Create a page

capture creates a new page in the OneNote section you chose during setup. It calls POST /api/capture — the same endpoint as the Capture to OneNote Shortcut.

# A page with just a title
onenotesystem capture "Standup notes"

# A page with a body
onenotesystem capture "Standup notes" --content "Shipped the CLI"

# A page from a file, with a source link
onenotesystem capture "Article" --file notes.md --url https://example.com/article

# A page from whatever another command printed
git log -1 --stat | onenotesystem capture "Today's commit" --stdin

Pages carry a title, plain text, and an optional source link — the same small, reliable format the Shortcuts use. Line breaks are preserved. Markdown is not rendered; it arrives as literal text. Content is limited to 100,000 characters and titles to 200, both checked before anything is uploaded.

Append to a page

append adds text to a page that already exists — a running inbox, a daily log, a project page. It calls POST /api/append.

# Add to a page by its exact title
onenotesystem append "Ask about the Q3 budget" --page-title "Quick Inbox"

# Add to a page by ID, from any section
onenotesystem append "Deploy finished" --page-id "1-abc123!..."

# Add whatever another command printed
dmesg | tail -20 | onenotesystem append --stdin --page-title "Server log"

# Set a default page once, then leave the flag off
onenotesystem configure --default-page "Quick Inbox"
onenotesystem append "A thought"

--page-title must match a page title exactly, and that page must be in your configured default section. If two pages share the title the command stops and asks for --page-id, because quietly appending to the wrong one would be worse than failing. A page ID can reach any section the connected Microsoft account can see.

Microsoft To Do

todo creates and completes Microsoft To Do tasks through the same deployment and the same API key. Calls /api/todo.

# Add a task to your default To Do list
onenotesystem todo add "Renew the domain" --due +7d

# A specific list, with a note and a reminder
onenotesystem todo add "Call the bank" --list Errands --due tomorrow --note "Ask about the fee"

# See what is open, then close one out
onenotesystem todo list
onenotesystem todo done AAMkAG...

Dates are sent with your computer's time zone, so a bare date stays the day you meant rather than shifting for anyone west of UTC. todo list prints each task's ID underneath it, which is what todo done takes.

Scripting

Progress messages go to stderr and --json goes to stdout alone, so onenotesystem capture … --json | jq always works.

#!/usr/bin/env bash
# Log a failed nightly build to OneNote without opening a browser.
if ! make nightly > build.log 2>&1; then
  onenotesystem capture "Nightly build failed $(date -I)" --file build.log
fi

Every command returns a stable exit code, so a script can tell an expired key apart from a dropped connection:

if ! onenotesystem append "$LINE" --page-title "Log"; then
  case $? in
    2) echo "Key expired; run onenotesystem configure" ;;
    4) echo "Offline; queueing locally" ;;
  esac
fi

Security

Your API key is sent only to the deployment address you configured, as an Authorization: Bearer header. It is never printed, logged, or included in an error message — including the unauthorized one. The config file is written with owner-only permissions.

Deployment addresses must use HTTPS. Plain http:// is accepted only for localhost and 127.0.0.1, so a typo cannot quietly send your key over an unencrypted connection.

Your note content passes through your own deployment to Microsoft Graph and nowhere else. The client has no telemetry and no runtime dependencies.

Terminal troubleshooting

For deployment and Microsoft errors, continue with the full troubleshooting guide →