version: "1.0.0" name: notion-cli description: Use the official Notion CLI (ntn) to call the Notion API, create/read/update pages, query data sources, upload files, and manage Notion Workers. Use when Codex needs to run or explain ntn commands, inspect Notion API endpoints, deploy or execute Workers, manage Worker secrets, or automate Notion CLI workflows from a terminal.

Notion CLI

Overview

Use this skill for terminal workflows built around the official Notion CLI, ntn. Prefer live CLI help and official docs over memorized syntax because the CLI is self-documenting and the API surface changes over time.

First Checks

Before answering with command syntax or running ntn, check the local environment:

command -v ntn
ntn --version
if [ -n "${NOTION_API_TOKEN:-}" ]; then echo "NOTION_API_TOKEN is set"; else echo "NOTION_API_TOKEN is not set"; fi

Do not print token values. If NOTION_API_TOKEN is set, prefer it over asking the user to run ntn login. If ntn is missing, see references/authentication.md for installation options.

Lookup Rule

Always prefer these commands before guessing syntax:

ntn api ls
ntn api <path> --help
ntn api <path> --docs
ntn api <path> --spec
ntn <command> --help

When an endpoint supports multiple methods, include -X GET, -X POST, -X PATCH, or the method being inspected.

Task Guide

• Authentication, installation, environment variables, PATs, and keychain behavior: read references/authentication.md.
• Generic Notion API calls, inline body syntax, query params, headers, endpoint docs, and verbose debugging: read references/api-requests.md.
• Data source lookup, query, pagination, filters, and schema updates: read references/datasources.md.
• Local file uploads, external URL imports, upload status checks, and attaching uploads: read references/files.md.
• Workers scaffolding, deploy, exec, sync, secrets, OAuth, logs, and tool authoring: read references/workers.md.
• Compact command list and flags: read references/cli-reference.md.

Safety

Treat Notion workspaces as private user data. Confirm before destructive or externally visible actions, including deleting Workers, trashing pages, updating page content, pushing secrets, deploying Workers, or sending webhooks. Never reveal API tokens, PATs, OAuth tokens, .env contents, or unredacted verbose logs. Use --verbose only when debugging, and avoid --unsafe-verbose unless the user explicitly accepts the token exposure risk in a controlled local context.

Common Examples

# List API endpoints
ntn api ls
 
# Read a page as Markdown
ntn pages get <page-id>
 
# Create a page from Markdown
ntn pages create --parent page:<page-id> --content "## Heading"
 
# Query a data source
ntn datasources query <data-source-id> --limit 50 --json
 
# Upload a local file
ntn files create --json < ./image.png
 
# Deploy and execute a Worker capability
ntn workers deploy
ntn workers exec <capability-key> -d '{"example": true}'