Notion x AI: Automate Databases and Page Generation with a CLI (2026 Guide)

Meeting notes, tasks, and team knowledge all live in Notion — yet the copying, sorting, and updating still happens by hand. The more central Notion is to your team, the more this "manual work inside Notion" piles up.

This guide explains how to automate Notion with AI agents. The centerpiece is the Notion CLI (ncli), a tool that runs search, database operations, page creation, and comment replies from the terminal. Combined with an AI agent, it turns routine Notion chores into automation — with the safety rules to match. The content is based on the training materials (Module 12) we use in our corporate training and online course.

For AI agent fundamentals, start with The Complete Guide to AI Agents for Business.

What you will learn

1. What the Notion CLI (ncli) is
2. Why operate Notion via CLI — and when to use MCP instead
3. Setup (install and OAuth login)
4. Database search and queries — designing the "read" side
5. Page creation and updates — the safe "write" workflow
6. In practice: summarize data → reply as a comment
7. Operational cautions (credentials, CI)

What is the Notion CLI (ncli)?

The Notion CLI (ncli) is a command-line tool for working with the official Notion API from your terminal. The package used in our course, @sakasegawa/ncli, authenticates via OAuth and is designed for coding-agent style workflows.

What ncli can do:

• Search your workspace (ncli search)
• Fetch pages and blocks (ncli fetch)
• Create pages (ncli page create) and update properties (ncli page update)
• Database operations (ncli db query / ncli db create)
• Upload files (ncli file upload)
• Create and list comments (ncli comment create / ncli comment list)
• Pipe-friendly JSON output

In short: most of what you do by clicking in the Notion UI becomes a command — which means an AI agent can execute it.

Why a CLI — and when to use MCP instead

There is another way to connect Notion and AI: an MCP (Model Context Protocol) server. The division of labor is straightforward:

The CLI's strength is that even in batch and CI contexts where chatty tools are awkward, you automate with one consistent command vocabulary. When you need in-editor workflows, pair it with Notion MCP. Building scripts and terminal automation around ncli keeps everything reproducible.

Setup

Setup takes two steps:

1. Install globally via npm — add @sakasegawa/ncli
2. Authenticate with ncli login — a one-time browser OAuth flow that connects your Notion workspace

After that, ncli whoami confirms your auth status and ncli search confirms you can find pages. Check ncli --help for flags and options.

From here on, you don't type commands yourself. Ask the AI agent in natural language — "fetch this week's tasks from the projects database and summarize them" — and the agent composes and runs the ncli commands.

Database search and queries — designing the "read" side

Notion automation starts with reading. The flow:

1. Find the database with ncli search
2. Check the schema (property structure) with ncli fetch
3. Query with filters and sorts using ncli db query
4. Format the JSON output into tables or short lists

What matters here — and what the course emphasizes — is read design:

• Cap the volume with queries and filters, working with one batch of results
• Don't paste full page bodies; choose what to quote and save tokens
• Have results returned as counts, key points, and next actions in short bullets

Notion pages get long. Fetching everything indiscriminately bloats the AI's context, hurting both accuracy and cost. "Fetch only what you need" is the golden rule of Notion x AI.

Page creation and updates — the safe "write" workflow

Once reading feels natural, move to writes: ncli page create (pages), ncli file upload (files), ncli db create (databases), and ncli page update (property updates and content appends).

Writes, unlike reads, modify your workspace. The course enforces a four-part safety workflow:

1. Practice in a sandbox — run against a draft or duplicated page first
2. Show the diff first — have the agent present the planned changes before applying them
3. Distinguish appends from updates — appending blocks and updating properties are different operations
4. Verify after execution — check before/after states with ncli fetch and know how to roll back

This "sandbox → diff → execute → verify" loop is the standard pattern for any write-capable AI agent, not just Notion.

In practice: summarize data → reply as a comment

A practical recipe combining reads and writes is "summarize and reply as a comment":

1. Fetch the target page or database content with ncli fetch
2. The AI summarizes the content
3. Add the summary as a comment on the page with ncli comment create
4. Verify with ncli comment list

Use cases: "read the weekly meeting notes and leave decisions and TODOs as a comment," or "summarize new database entries and tag the owner in a comment." Because the output lands as a comment rather than editing the body, there is no risk of corrupting the original content — a very production-friendly property.

To take this to scheduled execution, the trigger-design patterns in Automate Your Work with Google Apps Script and AI apply directly.

Operational cautions

1. Mind where credentials are stored and never commit tokens to your repository — ncli credentials are secrets
2. CI cannot do interactive login — ncli login uses browser auth, so CI environments may need a different auth strategy
3. Keep secrets out of logs — including tokens and signed URLs returned when fetching files
4. Never dump raw binary — return attachments as summaries, links, or short excerpts

For team-wide enablement with hands-on guidance, see our corporate AI agent training.

A note on illustrations: this article intentionally has none. Notion CLI work is text-centric (commands and JSON), so trying the command examples above is faster than any diagram.

Frequently asked questions

Q. How is this different from Notion AI (the built-in feature)? A. Notion AI generates and summarizes text inside the Notion UI. The approach here drives the Notion API from outside via CLI, letting an AI agent automate multi-step routine work — search, query, page creation, comments. The two are complementary, not exclusive.

Q. Do I need programming knowledge? A. You don't need to memorize commands. Once setup (install and ncli login) is done, you make natural-language requests like "fetch this week's entries from the projects database and summarize them," and the AI agent composes and runs the commands. What you do need is to clearly specify which pages or databases are in scope.

Q. Could the AI overwrite my pages by accident? A. Prevent it with operating rules. The course enforces: practice on a sandbox page, have the agent present a diff before applying, execute, then verify before/after with ncli fetch. Designing outputs as comment additions rather than body edits removes the corruption risk entirely.

Q. Should I use MCP or the CLI? A. Use MCP for interactive, in-editor work and the CLI (ncli) for batch jobs, CI, and scripted routines. Where reproducibility matters, build around the CLI and divide roles with MCP as needed — that is the course's recommendation.

Q. What should I watch out for with authentication? A. The first ncli login is a browser OAuth flow. Treat the resulting token as a secret: check where it is stored and never commit it to a Git repository. CI environments cannot do interactive login, so plan an alternative auth approach there.

Related articles

• The Complete Guide to AI Agents for Business
• AI Secretary: Automate Gmail, Google Calendar & Drive
• Automate Your Work with Google Apps Script and AI
• AI Data Analysis: EDA and Dashboards with AI Agents
• Corporate AI agent training (hands-on)

Last reviewed: 2026-06-10