# Notion

Notion CLI/API for pages, Markdown content, data sources, files, comments, search...

- Repository: https://github.com/OpenBMB/PilotDeck (4947 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add OpenBMB/PilotDeck --skill notion -g -a claude-code -y`
Codex: `npx skills add OpenBMB/PilotDeck --skill notion -g -a codex -y`
Cursor: `npx skills add OpenBMB/PilotDeck --skill notion -g -a cursor -y`
Gemini CLI: `npx skills add OpenBMB/PilotDeck --skill notion -g -a gemini-cli -y`

## Description

Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Notion

Prefer official `ntn` CLI. Use curl only when `ntn` is unavailable or a raw request is clearer.

## Setup

```bash
npm install -g ntn
ntn --version
ntn login
```

Script/headless auth:

```bash
export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11
```

`ntn api` sets `Authorization` and `Notion-Version` automatically. It uses CLI login by default, or `NOTION_API_TOKEN` when set.

## Inspect

```bash
ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST
```

## Pages

Markdown-first helpers:

```bash
ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Title\n\nBody'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# Updated'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes
```

Notes:

- `pages get` prints Markdown with page properties as frontmatter.
- Content input: `--content`, stdin, or editor in a TTY.
- Parent refs: `page:<id>`, `database:<id>`, `data-source:<id>`.
- For properties/templates/full Pages API, use `ntn api v1/pages`.

## Data sources

```bash
ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort 'Date desc'
ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'
```

Use `resolve` when you have a database ID. Query needs a data source ID.

## Raw API

The rest: https://github.com/OpenBMB/PilotDeck/blob/HEAD/skills/notion/SKILL.md