# Notion Agent Cli

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-jgorostegui-notion-agent-cli-notion-agent-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jgorostegui](https://agentstack.voostack.com/s/jgorostegui)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jgorostegui](https://github.com/jgorostegui)
- **Source:** https://github.com/jgorostegui/notion-agent-cli/tree/main/skills/notion-agent-cli

## Install

```sh
agentstack add skill-jgorostegui-notion-agent-cli-notion-agent-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## CLI

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/actions.mjs  [args...]
```

Run actions directly. If the decision tree does not cover your case, run `schema ` for live metadata. Prefer `schema` over reading source.

### Quick Patterns

- Read + summarize/report -> `getPage` -> `createPage` (2 calls)
- Copy with modifications -> `copyPageWith` (1 call)
- Merge pages -> `createPage` -> `mergePages` (2 calls)
- Batch property update -> `batchSetProperties` (1 call)

## Decision Tree

- **Find something** -> `search "query"` or `workspaceMap`
- **Read a page** -> `getPage `
- **Query a database** -> `queryDatabase ` (markdown table; `--format raw` for JSON)
- **Create a page** -> `createPage  "Title" "markdown content"`
- **Replace all content** -> `updatePage  "content"`
- **Add to end** -> `appendBlocks  "content"`
- **Update properties** -> `setProperties  '{"Status":"Done"}'`
- **Markdown table to database** -> `importTable  "| md | table |" --title "Name"` (infers column types)
- **Full copy with subpages** -> `deepCopy  `
- **Copy + modify** -> `copyPageWith   "Title" --appendMd "## Extra"`
- **Merge pages** -> `mergePages '["id1","id2"]' `
- **Read one section** -> `extractSection  "Heading"`
- **Edit one section** -> `replaceSection  "Heading" "new content"`
- **Batch update** -> `batchSetProperties '["id1","id2"]' '{"Status":"Done"}'`

## Key Behaviors

- **Page reads and database queries return markdown** by default.
  `getPage` and `extractSection` return markdown. `queryDatabase` returns a
  compact markdown table with row IDs for follow-up actions.
- **`setProperties` auto-types values** from the database schema.
  Pass `{"Status": "Done"}` — no raw Notion API format needed.
- **`createPage` accepts markdown** as the content argument.
- **Compound actions save turns** — each CLI call is one agentic turn:
  - `copyPageWith` = read + modify + create in 1 call
  - `mergePages` = N reads + merge in 1 call (target must exist; use `createPage` first)
  - `batchSetProperties` = N updates in 1 call
- **Stdin mode** for large content:
  `echo '{"action":"createPage",...}' | node ${CLAUDE_PLUGIN_ROOT}/scripts/actions.mjs -`
- **Auto-snapshot** before destructive operations.

## Common Pitfalls

1. Do NOT fetch database entries individually — `queryDatabase` returns all in one call
2. Do NOT use `getPage` + `createPage` when `copyPageWith` does both in one call
3. Do NOT use multiple `setProperties` when `batchSetProperties` handles N pages
4. Do NOT read the script source — use `schema ` or the references below
5. `mergePages` target must already exist — use `createPage` first to create it
6. Large content (>4KB) should use stdin mode, not inline CLI args
7. Properties are auto-typed from the database schema — pass simple values like `{"Status": "Done"}`, not raw Notion API format
8. File/image URLs expire after ~1 hour — re-fetch if reusing later

## References

- **`references/action-reference.md`** — Read when you need exact parameter names or options for an unfamiliar action.
- **`references/workflows.md`** — Read when combining operations or piping large content via stdin.
- **`references/api-limits.md`** — Read when hitting API errors, size limits, or unexpected behavior.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jgorostegui](https://github.com/jgorostegui)
- **Source:** [jgorostegui/notion-agent-cli](https://github.com/jgorostegui/notion-agent-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jgorostegui-notion-agent-cli-notion-agent-cli
- Seller: https://agentstack.voostack.com/s/jgorostegui
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.