{
  "schema_version": "cmdhub.website.command_catalog.v1",
  "tool": "notion",
  "title": "Notion CLI",
  "description": "Databases, pages, blocks, and search with command-level schema.",
  "auth_mode": "Private session",
  "auth_scopes": {
    "label": "Notion private session",
    "scopes": [
      "Notion private session token"
    ],
    "note": "Stored locally by the CLI for the selected Notion workspace."
  },
  "markdown_url": "/cli/notion/index.md",
  "commands": [
    {
      "id": "cmd-notion-auth",
      "path": "notion auth",
      "name": "auth",
      "short": "Manage Notion PAT authentication",
      "long": "Manage Notion Personal Access Token authentication for the active profile.\n\nUse auth status when commands fail with AUTH_REQUIRED.\nUse auth login to store a Notion PAT.\nUse auth whoami to confirm which user or bot the profile points at.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-auth-login",
      "path": "notion auth login",
      "name": "login",
      "short": "Store a Notion Personal Access Token",
      "long": "Store a Notion Personal Access Token (PAT) for the active profile.\n\nThis validates the PAT against the Notion REST API and caches the returned identity metadata.",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion auth login\nnotion auth login --pat-env NOTION_API_TOKEN\nprintf '%s' \"$NOTION_API_TOKEN\" | notion auth login --pat -",
      "flags": [
        {
          "name": "pat",
          "type": "string",
          "usage": "read the Notion PAT from stdin when set to -"
        },
        {
          "name": "pat-env",
          "type": "string",
          "usage": "read the Notion PAT from this environment variable"
        }
      ]
    },
    {
      "id": "cmd-notion-auth-logout",
      "path": "notion auth logout",
      "name": "logout",
      "short": "Remove stored Notion credentials",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion auth logout",
      "flags": []
    },
    {
      "id": "cmd-notion-auth-refresh",
      "path": "notion auth refresh",
      "name": "refresh",
      "short": "Validate the stored Notion PAT",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion auth refresh",
      "flags": []
    },
    {
      "id": "cmd-notion-auth-status",
      "path": "notion auth status",
      "name": "status",
      "short": "Show Notion auth status",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion auth status",
      "flags": []
    },
    {
      "id": "cmd-notion-auth-whoami",
      "path": "notion auth whoami",
      "name": "whoami",
      "short": "Show the current Notion user and workspace",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion auth whoami",
      "flags": []
    },
    {
      "id": "cmd-notion-block",
      "path": "notion block",
      "name": "block",
      "short": "Work with Notion blocks",
      "long": "Get, list, append, and delete Notion blocks within a page.\n\nBlocks are referred to by --page <ref> where ref is a local marker (p1), URL, or UUID.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-block-append",
      "path": "notion block append",
      "name": "append",
      "short": "Append a block to a Notion page",
      "long": "Append a new block to the end of a Notion page.\n\nUse --body to supply text directly, @file to read from a file, or - to read from stdin.\nWhen --body - is used, --page must be provided explicitly (stdin is consumed for body text).\nWhen --page is omitted, a piped item from a previous command is used as the page reference.\n\nSupported block types: paragraph, heading_1, heading_2, heading_3,\nbulleted_list, numbered_list, to_do, code, quote",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion block append --page p1 --body \"New block\"",
      "flags": [
        {
          "name": "body",
          "type": "string",
          "usage": "Block text content; use @file to read from a file, - to read from stdin"
        },
        {
          "name": "checked",
          "type": "bool",
          "usage": "Mark to_do block as checked (only meaningful with --type to_do)"
        },
        {
          "name": "page",
          "type": "string",
          "usage": "Page reference (marker, URL, or UUID)"
        },
        {
          "name": "type",
          "type": "string",
          "default": "paragraph",
          "usage": "Block type: paragraph, heading_1, heading_2, heading_3, bulleted_list, numbered_list, to_do, code, quote"
        }
      ]
    },
    {
      "id": "cmd-notion-block-delete",
      "path": "notion block delete",
      "name": "delete",
      "short": "Delete (trash) one or more Notion blocks",
      "long": "Delete a block by local block ref or a piped item from block list.\n\nThis moves the block to trash (alive=false). It does not permanently delete.\nUse notion block list --page p1 --jsonl to pipe block items into this command.",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion block list --page p1 --limit 1 --jsonl | notion block delete",
      "flags": [
        {
          "name": "all",
          "type": "bool",
          "usage": "Confirm batch block deletion"
        },
        {
          "name": "yes",
          "type": "bool",
          "usage": "Confirm destructive batch block deletion"
        }
      ]
    },
    {
      "id": "cmd-notion-block-get",
      "path": "notion block get",
      "name": "get",
      "short": "Get one or more Notion blocks by ref",
      "long": "Get a Notion block by local marker, URL, or UUID.\n\nRun block list first to populate local block markers from a page.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion block get b1",
      "flags": []
    },
    {
      "id": "cmd-notion-block-list",
      "path": "notion block list",
      "name": "list",
      "short": "List blocks in a Notion page",
      "long": "List the blocks contained in a Notion page.\n\nReturns a structured list of block types and their text content.\nUse --depth to control how many levels of nesting are returned (default: all).",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion block list --page p1",
      "flags": [
        {
          "name": "depth",
          "type": "int",
          "usage": "Max nesting depth (0 = unlimited)"
        },
        {
          "name": "page",
          "type": "string",
          "usage": "Page reference (marker, URL, or UUID)"
        }
      ]
    },
    {
      "id": "cmd-notion-capabilities",
      "path": "notion capabilities",
      "name": "capabilities",
      "short": "Describe capabilities",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion capabilities",
      "flags": []
    },
    {
      "id": "cmd-notion-config",
      "path": "notion config",
      "name": "config",
      "short": "Inspect local configuration",
      "long": "",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-config-explain",
      "path": "notion config explain",
      "name": "explain",
      "short": "Explain resolved configuration",
      "long": "",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion config explain --help",
      "flags": []
    },
    {
      "id": "cmd-notion-data-source",
      "path": "notion data-source",
      "name": "data-source",
      "short": "Work with Notion data sources",
      "long": "List, inspect, and query Notion data sources.\n\nData sources are the queryable tables that live under Notion databases.\nRun data-source list first to populate local markers for follow-up commands.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-data-source-get",
      "path": "notion data-source get",
      "name": "get",
      "short": "Get one or more Notion data sources by ref",
      "long": "Get a Notion data source by local marker, URL, or UUID.\n\nReturns metadata including title, collection ID, and property schema.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion data-source get ds1",
      "flags": []
    },
    {
      "id": "cmd-notion-data-source-list",
      "path": "notion data-source list",
      "name": "list",
      "short": "List accessible Notion data sources",
      "long": "List Notion data sources accessible to the current PAT.\n\nThis searches the workspace for queryable database-like content and assigns\nlocal markers (ds1, ...) for follow-up commands.\nUse --query to narrow results by title.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion data-source list --limit 10",
      "flags": [
        {
          "name": "limit",
          "type": "int",
          "default": "20",
          "usage": "Maximum number of results to return"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Text query to match database titles"
        }
      ]
    },
    {
      "id": "cmd-notion-data-source-query",
      "path": "notion data-source query",
      "name": "query",
      "short": "Query rows in a Notion data source",
      "long": "Query rows in a Notion database or data source.\n\nReturns page rows with their titles and properties.\nUse --query for simple text matching across titles/properties.\nUse --filter and --sort for advanced queries (raw Notion query JSON).",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion data-source query ds1 --limit 10",
      "flags": [
        {
          "name": "filter",
          "type": "string",
          "usage": "Filter as raw Notion query JSON"
        },
        {
          "name": "limit",
          "type": "int",
          "default": "50",
          "usage": "Maximum number of rows to return"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Text query to match returned page titles and properties"
        },
        {
          "name": "sort",
          "type": "string",
          "usage": "Sort as raw Notion query JSON"
        }
      ]
    },
    {
      "id": "cmd-notion-database",
      "path": "notion database",
      "name": "database",
      "short": "Work with Notion databases",
      "long": "List, inspect, and query Notion databases.\n\nDatabases are referred to by local marker (d1), Notion URL, or UUID.\nRun database list first to populate local markers.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-database-get",
      "path": "notion database get",
      "name": "get",
      "short": "Get one or more Notion databases by ref",
      "long": "Get a Notion database by local marker, URL, or UUID.\n\nReturns metadata including title, collection ID, and property schema.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion database get d1",
      "flags": []
    },
    {
      "id": "cmd-notion-database-list",
      "path": "notion database list",
      "name": "list",
      "short": "List accessible Notion databases",
      "long": "List Notion databases accessible to the current PAT.\n\nThis searches the workspace for queryable database-like content and assigns\nlocal markers (d1, ...) for follow-up commands.\nUse --query to narrow results by title.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion database list --limit 10",
      "flags": [
        {
          "name": "limit",
          "type": "int",
          "default": "20",
          "usage": "Maximum number of results to return"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Text query to match database titles"
        }
      ]
    },
    {
      "id": "cmd-notion-database-query",
      "path": "notion database query",
      "name": "query",
      "short": "Query rows in a Notion database",
      "long": "Query rows in a Notion database or data source.\n\nReturns page rows with their titles and properties.\nUse --query for simple text matching across titles/properties.\nUse --filter and --sort for advanced queries (raw Notion query JSON).",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion database query d1 --limit 10",
      "flags": [
        {
          "name": "filter",
          "type": "string",
          "usage": "Filter as raw Notion query JSON"
        },
        {
          "name": "limit",
          "type": "int",
          "default": "50",
          "usage": "Maximum number of rows to return"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Text query to match returned page titles and properties"
        },
        {
          "name": "sort",
          "type": "string",
          "usage": "Sort as raw Notion query JSON"
        }
      ]
    },
    {
      "id": "cmd-notion-doctor",
      "path": "notion doctor",
      "name": "doctor",
      "short": "Run Notion adapter diagnostics",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion doctor",
      "flags": []
    },
    {
      "id": "cmd-notion-login",
      "path": "notion login",
      "name": "login",
      "short": "Store a Notion Personal Access Token",
      "long": "Store a Notion Personal Access Token (PAT) for the active profile.\n\nThis validates the PAT against the Notion REST API and caches the returned identity metadata.",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion auth login\nnotion auth login --pat-env NOTION_API_TOKEN\nprintf '%s' \"$NOTION_API_TOKEN\" | notion auth login --pat -",
      "flags": [
        {
          "name": "pat",
          "type": "string",
          "usage": "read the Notion PAT from stdin when set to -"
        },
        {
          "name": "pat-env",
          "type": "string",
          "usage": "read the Notion PAT from this environment variable"
        }
      ]
    },
    {
      "id": "cmd-notion-logout",
      "path": "notion logout",
      "name": "logout",
      "short": "Remove stored Notion credentials",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion auth logout",
      "flags": []
    },
    {
      "id": "cmd-notion-page",
      "path": "notion page",
      "name": "page",
      "short": "Work with Notion pages",
      "long": "Get and modify Notion pages.\n\nPages are referred to by local marker (p1), Notion URL, or UUID.\n\tRun database query or workspace search first to populate local page markers.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-page-create",
      "path": "notion page create",
      "name": "create",
      "short": "Create a new Notion page",
      "long": "Create a new Notion page within a database.\n\nUse --body to append a paragraph block to the new page. Supports inline text,\n@file to read from a file, or - to read body from stdin (parent is always explicit).\nCreating child pages directly under top-level pages is not supported by the\ncurrent Notion REST write path; create the page in a database contained by that page.",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion page create --parent d1 --title \"New page\"",
      "flags": [
        {
          "name": "body",
          "type": "string",
          "usage": "Body paragraph text; use @file to read from file, - to read from stdin"
        },
        {
          "name": "parent",
          "type": "string",
          "usage": "Parent page or database reference"
        },
        {
          "name": "properties",
          "type": "string",
          "usage": "Raw Notion properties JSON object"
        },
        {
          "name": "title",
          "type": "string",
          "usage": "Page title"
        }
      ]
    },
    {
      "id": "cmd-notion-page-get",
      "path": "notion page get",
      "name": "get",
      "short": "Get one or more Notion pages by ref",
      "long": "Get a Notion page by local marker, URL, or UUID.\n\nReturns page metadata, parent information, and a block summary.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion page get p1",
      "flags": []
    },
    {
      "id": "cmd-notion-page-list",
      "path": "notion page list",
      "name": "list",
      "short": "List Notion pages",
      "long": "List Notion pages from the workspace, a database, or a parent page.\n\nWith no selector, this lists recent pages from workspace search.\nUse --database to list rows from a database.\nUse --parent-page to list direct child pages under a parent page.\nUse --query to narrow returned pages by title or property text.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion page list --limit 10",
      "flags": [
        {
          "name": "database",
          "type": "string",
          "usage": "Database reference (marker, URL, or UUID)"
        },
        {
          "name": "limit",
          "type": "int",
          "default": "20",
          "usage": "Maximum number of results to return"
        },
        {
          "name": "parent-page",
          "type": "string",
          "usage": "Parent page reference (marker, URL, or UUID)"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Text query to match returned page titles and properties"
        }
      ]
    },
    {
      "id": "cmd-notion-page-restore",
      "path": "notion page restore",
      "name": "restore",
      "short": "Restore one or more Notion pages from trash",
      "long": "Restore a Notion page from trash by local marker, URL, or UUID.\n\nUse this only after selecting the exact trashed page ref.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion page restore p1 --yes",
      "flags": [
        {
          "name": "all",
          "type": "bool",
          "usage": "Confirm batch page restore"
        },
        {
          "name": "yes",
          "type": "bool",
          "usage": "Confirm batch page restore"
        }
      ]
    },
    {
      "id": "cmd-notion-page-trash",
      "path": "notion page trash",
      "name": "trash",
      "short": "Move one or more Notion pages to trash",
      "long": "Move a Notion page to trash by local marker, URL, or UUID.\n\nThis is an idempotent operation. Trashed pages can be restored with notion page restore.",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion page trash p1",
      "flags": [
        {
          "name": "all",
          "type": "bool",
          "usage": "Confirm batch page trash"
        },
        {
          "name": "yes",
          "type": "bool",
          "usage": "Confirm destructive batch page trash"
        }
      ]
    },
    {
      "id": "cmd-notion-page-update",
      "path": "notion page update",
      "name": "update",
      "short": "Update a Notion page",
      "long": "Update a Notion page title and optionally append body text.\n\nUse --body to append a paragraph block to the page. Supports inline text,\n@file to read from a file, or - to read body from stdin (page ref must then\nbe a positional argument \u2014 stdin cannot carry both the ref and body text).",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion page update p1 --title \"Updated title\"",
      "flags": [
        {
          "name": "body",
          "type": "string",
          "usage": "Body paragraph to append; use @file to read from file, - to read from stdin"
        },
        {
          "name": "properties",
          "type": "string",
          "usage": "Raw Notion properties JSON object"
        },
        {
          "name": "title",
          "type": "string",
          "usage": "New page title"
        }
      ]
    },
    {
      "id": "cmd-notion-profile",
      "path": "notion profile",
      "name": "profile",
      "short": "Manage provider profiles",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-profile-create",
      "path": "notion profile create",
      "name": "create",
      "short": "Create an unauthenticated provider profile",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion profile create --help",
      "flags": []
    },
    {
      "id": "cmd-notion-profile-delete",
      "path": "notion profile delete",
      "name": "delete",
      "short": "Delete a local provider profile",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion profile delete --help",
      "flags": []
    },
    {
      "id": "cmd-notion-profile-list",
      "path": "notion profile list",
      "name": "list",
      "short": "List provider profiles",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion profile list --help",
      "flags": []
    },
    {
      "id": "cmd-notion-profile-rename",
      "path": "notion profile rename",
      "name": "rename",
      "short": "Rename a local provider profile",
      "long": "",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion profile rename --help",
      "flags": []
    },
    {
      "id": "cmd-notion-profile-use",
      "path": "notion profile use",
      "name": "use",
      "short": "Set the default provider profile",
      "long": "",
      "mutates": true,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "notion profile use --help",
      "flags": []
    },
    {
      "id": "cmd-notion-resolve",
      "path": "notion resolve",
      "name": "resolve",
      "short": "Resolve a Notion local marker or shortened canonical reference",
      "long": "Resolve a Notion short reference into its canonical payload.\n\nUse this when you have a marker such as d1, p1, or b1, or a shortened canonical id, and want to inspect what it refers to.\n\nResolution is profile-scoped. If a marker does not resolve, verify --profile and rerun the relevant list command.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion resolve p1",
      "flags": []
    },
    {
      "id": "cmd-notion-schema",
      "path": "notion schema",
      "name": "schema",
      "short": "Emit Notion adapter schema hints",
      "long": "Show schema hints for the Notion resource payloads emitted by this CLI.\n\nUse this when you need to understand structured output fields for automation or downstream parsing.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion schema",
      "flags": [
        {
          "name": "in",
          "type": "bool",
          "usage": "Show input schema"
        },
        {
          "name": "input",
          "type": "bool",
          "usage": "Show input schema"
        },
        {
          "name": "out",
          "type": "bool",
          "usage": "Show output schema"
        }
      ]
    },
    {
      "id": "cmd-notion-version",
      "path": "notion version",
      "name": "version",
      "short": "Show notion version information",
      "long": "",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion version",
      "flags": []
    },
    {
      "id": "cmd-notion-workspace",
      "path": "notion workspace",
      "name": "workspace",
      "short": "Search and inspect the Notion workspace",
      "long": "Search workspace content visible to the current Notion PAT.\n\nUse workspace search when you need mixed page and database discovery before selecting a local ref.",
      "mutates": false,
      "safe_discovery": false,
      "supports_dry_run": false,
      "example": "",
      "flags": []
    },
    {
      "id": "cmd-notion-workspace-search",
      "path": "notion workspace search",
      "name": "search",
      "short": "Search Notion for pages, databases, and data sources",
      "long": "Search the Notion workspace for pages, databases, and data sources matching a query.\n\nAssigns local markers (p1, d1, ds1, ...) for follow-up commands.",
      "mutates": false,
      "safe_discovery": true,
      "supports_dry_run": false,
      "example": "notion workspace search --query \"roadmap\" --limit 10",
      "flags": [
        {
          "name": "in-trash",
          "type": "string",
          "usage": "Filter by trash state: true or false"
        },
        {
          "name": "limit",
          "type": "int",
          "default": "20",
          "usage": "Maximum number of results to return"
        },
        {
          "name": "query",
          "type": "string",
          "usage": "Search query text"
        },
        {
          "name": "type",
          "type": "string",
          "usage": "Filter by type: page, database, or data-source"
        }
      ]
    }
  ]
}