Search pages, list users, view page activity, and explore trending content — all from the command line. All commands output JSON.
# Install (see Installation section for registry setup)
npm install -g @dotbrains/notion-cli
# Set up your credentials
notion init
# Search for pages
notion search "onboarding guide"
# List all pages
notion pages
# Get a specific page
notion page <page-id>
# List trending pages
notion trending
# List workspace users
notion users
# View page activity
notion page-activity <page-id>
# View user activity
notion user-activity- Reads your credentials from
~/.config/notion/config.json. - Uses Notion's internal API (
/api/v3/) to fetch data. - Paginates automatically with
--all— list commands fetch every page. - Outputs raw JSON to stdout for easy piping into
jq, scripts, or other tools.
This package is published to GitHub Packages, not npmjs. One-time setup is required:
# 1. Point the @dotbrains scope at GitHub Packages
npm config set @dotbrains:registry https://npm.pkg.github.com
# 2. Authenticate with a GitHub personal access token (needs read:packages scope)
npm config set //npm.pkg.github.com/:_authToken <YOUR_GITHUB_PAT>Tip: If you have the GitHub CLI installed, you can use
gh auth tokeninstead of a PAT:npm config set //npm.pkg.github.com/:_authToken $(gh auth token)
Then install globally:
npm install -g @dotbrains/notion-cliOr install from source:
git clone https://github.com/dotbrains/notion-cli.git
cd notion-cli
npm install
npm link| Command | Description |
|---|---|
notion init |
Set up notion by configuring your credentials |
notion search <query> |
Search for pages |
notion pages |
List available pages (sort by: views, edited, title) |
notion page <id> |
Get details for a specific page |
notion trending |
List trending pages by view count |
notion users |
List workspace users |
notion page-activity <id> |
Show visitor activity for a page |
notion user-activity |
Show where users are most active |
All commands support --json for raw JSON output, --limit <n> for result limits, and --all for automatic pagination.
# First-time setup
notion initThis prompts for your credentials and writes the config to ~/.config/notion/config.json.
To get your credentials, open Notion in your browser and:
- Open DevTools (Cmd+Option+I / Ctrl+Shift+I)
- Go to the Network tab and find any request to
www.notion.so/api/ - token — In the request headers, find the "Cookie" header and copy the value of
token_v2 - spaceId — In the request headers, copy the value of
x-notion-space-id - userId — In the request headers, copy the value of
x-notion-active-user-header
To reconfigure, run notion init --force.
This repo includes an agent skill at .claude/skills/notion/SKILL.md that is automatically discovered by Warp and Claude Code. When working in this repo, the agent can use notion whenever you ask about Notion pages or documents.
With the skill active, you can say things like:
Find every page related to onboarding that has been viewed more than 50 times. For each one, show me who has been most active on that page.
The agent will use notion to search for pages, inspect activity, and present the results — all autonomously.
See SPEC.md for the full technical specification — every command, its options, step-by-step behavior, authentication flow, pagination strategy, and error handling.
Tests use Node.js built-in node:test runner and node:assert — no external test framework. Coverage is tracked with c8.
# Run tests
npm test
# Run tests with coverage
npm run test:coverageCore modules (src/config.js, src/helpers.js) have 100% coverage. Command modules test the exported API functions (search, searchAll, getRecord, getVisibleUsers, getPageVisitors, etc.) using temp config files and mocked fetch. The register* functions (Commander wiring) are tested via integration by running the CLI.
This project is licensed under the PolyForm Shield License 1.0.0 — see LICENSE for details.