はじめに

hkob の雑記録の第492回目(連続65日目)は、Notion Developer Platform の司令塔である ntn コマンドについて見ていきます。

インストール

インストールは最近のツールによくある curl で取得したスクリプトを bash で実行するものです。

curl -fsSL https://ntn.dev | bash

実行すると以下のようにインストールが実行されました。

curl -fsSL https://ntn.dev | bash
==> Downloading v0.14.0 for darwin-arm64
ntn-aarch64-apple-darwin.tar.gz: OK

  ▄▄▄▄▄▄▄▄▖
 ██▄▄▄▄▄▄▄▟▙▖
 ███ ▄▄  ▄▄▐▌
 ███ ▐█▙ ▐▌▐▌
 ███ ▐▌▜▙▐▌▐▌
 ███ ▟▙ ▀█▌▐▌
  ▀█▄▄▄▄▄▄▄▞▘

  Notion CLI (Beta)

  Installed ntn v0.14.0 to /usr/local/bin/ntn

  Get started:

    ntn login              Log in to your Notion workspace
    ntn workers new        Create a new worker
    ntn datasources query  Query a data source
    ntn pages create       Create a page from Markdown
    ntn api                Call the Notion API directly
    ntn --help             See all available commands

  Add the Notion skill for your agents:

    npx skills add makenotion/skills

全体ヘルプ

ntn --help を実行すると全体のヘルプが表示されました。

ntn --help
Notion CLI (Beta)

Usage: ntn [OPTIONS] <COMMAND>

Commands:
  api          Call the public Notion API (beta)
  datasources  Manage data sources
  files        Manage file uploads (beta)
  pages        Manage pages
  login        Log in to Notion
  logout       Log out of Notion
  completions  Generate shell completions
  doctor       Check the health of your Notion CLI setup
  update       Update ntn to the latest version
  workers      Manage workers (Beta)
  help         Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose
          Show full error details including source chains

      --workers-config-file <WORKERS_CONFIG_FILE>
          Path to workers.json config file (overrides default CWD lookup)

          [env: NOTION_WORKERS_CONFIG_FILE=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Environment Variables:
  NOTION_API_BASE_URL         Base URL for separate API-host requests (default varies by --env)
  NOTION_API_TOKEN            API token for authentication (overrides keychain)
  NOTION_BASE_URL             Base URL for login and workers requests (default varies by --env)
  NOTION_ENV                  Environment to target: local, dev, stg, prod (same as --env)
  NOTION_KEYRING              Set to 0 to use file-based auth (~/.config/notion/auth.json) instead of OS keychain
  NOTION_WORKERS_CONFIG_FILE  Path to workers.json config file (same as --workers-config-file)
  NOTION_WORKSPACE_ID         Workspace ID to operate on (overrides config default)

ntn login すると認証が入り、個人用アクセストークン(PAT)が生成されます。PAT 自体は開発者ポータルで確認できます。漏えいなどの問題があった場合には、ここで取り消すことも可能です。

PAT が有効な間は2回目以降はワークスペースの切り替えになるだけです。Authenticate with new workspace を選ぶと別のワークスペースとの認証をすることができます。

ntn login
? Select a workspace ›
❯ hkob's ambassador workspace
  Authenticate with new workspace

すでに認証済みのワークスペースを選ぶと何も起こりません。

ntn login
✔ Select a workspace · hkob's ambassador workspace
✔ Switched to workspace hkob's ambassador workspace

ntn pages

ntn api はこれまで通りの API アクセスなので、それ以外のコマンドをいくつか実行してみます。最初は pages です。まずヘルプを確認してみます。

ntn pages --help
Manage pages

Usage: ntn pages [OPTIONS] <COMMAND>

Commands:
  trash   Trash a page
  get     Retrieve a page as Markdown
  create  Create a page from Markdown content
  update  Update a page's content from Markdown
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose
          Show full error details including source chains

      --workers-config-file <WORKERS_CONFIG_FILE>
          Path to workers.json config file (overrides default CWD lookup)

          [env: NOTION_WORKERS_CONFIG_FILE=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Scope:
  `ntn pages` supports retrieving, creating, and updating pages as Markdown content.

Examples:
  ntn pages get <page-id>
  ntn pages get <page-id> --json
  ntn pages create --content '# Title\n\nBody'
  ntn pages create --parent data-source:01234567-89ab-cdef-0123-456789abcdef < page.md
  ntn pages create                                                           # opens $EDITOR
  ntn pages update <page-id> --content '# Updated body'
  ntn pages update <page-id> < page.md
  ntn pages update <page-id>                                                 # opens $EDITOR

Notes:
  - `ntn pages get` prints page Markdown with page properties prepended as frontmatter by default.
  - If `ntn pages get` returns truncated Markdown, stderr will suggest using `--json` to inspect `unknown_block_ids`.
  - Provide Markdown with `--content`, stdin, or interactively via `$EDITOR`.
  - `--parent` (create only) is optional: `page:<id>`, `database:<id>`, or `data-source:<id>`.
  - When no content source is given in a TTY, `$VISUAL` / `$EDITOR` / `vi` is opened.
  - For properties, templates, or the full Pages API surface, use `ntn api v1/pages`.

Environment Variables:
  EDITOR                      Editor opened for interactive Markdown editing (fallback: vi)
  VISUAL                      Preferred editor (checked before $EDITOR)
  NOTION_API_BASE_URL         Base URL for public API requests (default varies by --env)
  NOTION_API_DOCS_BASE_URL    Base URL for OpenAPI lookups used to resolve the latest version
  NOTION_API_TOKEN            Public API integration token for authentication (required today for `ntn pages`)
  NOTION_API_VERSION          Notion-Version header to send (same as --notion-version)
  NOTION_ENV                  Environment to target for other CLI commands (same as --env)
  NOTION_HOME                 Override the CLI state root for cache and config
  XDG_CACHE_HOME              XDG base directory for cached OpenAPI specs (fallback)
  XDG_CONFIG_HOME             XDG base directory for config/auth state (fallback)

とりあえず、試しに get を実行してみました。テキストが markdown で取得されます。なお、markdown で表現できないブロックは unknown で示されるようです。

ntn pages get 3600ce2a6520812d93efc0a3f64e700e
---
Assignee: []
Date:
  end: null
  start: '2026-05-15'
  time_zone: null
Difference in minutes: 920
Display status: '--- no time info ---'
Link: https://outlook.office.com/mail/
Map:
- '1f70ce2a-6520-80b6-8887-d48d6354eb5d'
Next step: false
Ready?: true
Remain: null
Reset (Someday): {}
Sprint:
- '34e0ce2a-6520-8196-bf35-f0ff451175da'
Status: Not Started
Summary: 荒川管理職会議と荒川コース長会議が予定されており、校長、副校長、専攻長などが参加する。次のステップは未定で、進捗はまだ始まっていない。
Task ID:
  number: 2454
  prefix: TASK
Task name: '5月15日の日報'
Update date: ''
Update date preview: null
Week id: '2026-20'
Work now: {}
blocked by: []
blocking: []
---

 ```python
1. 荒川管理職会議、荒川コース長会議
2. 校長、副校長、専攻長、荒川教務主事、荒川学生主事、管理課長、庶務係長
3. 上記会議にて連絡報告
 ```
<unknown url="https://www.notion.so/3600ce2a6520812d93efc0a3f64e700e#d8c0ce2a6520838181940148635bc29c" alt="bookmark"/>
warning: Page content was truncated. Re-run `ntn pages get 3600ce2a6520812d93efc0a3f64e700e --json` to inspect `unknown_block_ids` for follow-up fetches.
<unknown url="https://www.notion.so/3600ce2a6520812d93efc0a3f64e700e#6620ce2a6520831a998601ed304eef6f" alt="bookmark"/>⏎