Notion Hub

NH="uv run --script --cache-dir /root/.cache/uv /var/minis/skills/notion-hub/scripts/notion_hub.py"

# Search everything
$NH search "meeting notes"
$NH search "project" --filter page
$NH search --filter database
$NH search "Q1" --sort descending --limit 5

# List users / get bot info
$NH users
$NH users --me

# Get page properties (compact)
$NH page-get <page_id_or_url>
$NH page-get <page_id> --raw  # full API response

# Read page content as Markdown (best for AI consumption)
$NH page-read <page_id>
$NH page-read <page_id> --depth 5  # deeper recursion
$NH page-read <page_id> -o /var/minis/workspace/page.md  # save to file

# Accepts Notion URLs directly:
$NH page-read "https://notion.so/My-Page-abc123def456..."

# Create page under another page
$NH page-create --page-id <parent_id> --title "New Page" --icon "📝"

# Create page in a database (= add row with content)
$NH page-create --database-id <db_id> --properties '{"Name":{"title":[{"text":{"content":"Task 1"}}]}}'

# Write Markdown content to a page
$NH page-write <page_id> --text "# Hello\n\nThis is a paragraph.\n\n- Item 1\n- Item 2"

# Write from file
$NH page-write <page_id> --file /var/minis/workspace/content.md

# Replace all existing content
$NH page-write <page_id> --text "Fresh content" --replace

# Update page properties
$NH page-update <page_id> --properties '{"Status":{"status":{"name":"Done"}}}'
$NH page-update <page_id> --icon "✅"
$NH page-update <page_id> --archived true  # archive page

# Get database schema (shows all properties, types, select options)
$NH db-get <database_id>
$NH db-get <database_id> --raw

# Query database rows
$NH db-query <database_id>
$NH db-query <database_id> --limit 20

# Query with filter
$NH db-query <database_id> --filter '{"property":"Status","status":{"equals":"In Progress"}}'

# Query with sort
$NH db-query <database_id> --sorts '[{"property":"Created","direction":"descending"}]'

# Compound filter
$NH db-query <db_id> --filter '{"and":[{"property":"Status","status":{"equals":"Done"}},{"property":"Priority","select":{"equals":"High"}}]}'

# Quick add a row (auto-detects property types from schema)
$NH db-add-row -d <database_id> --props '{"Name":"My Task","Status":"In Progress","Priority":"High","Due Date":"2024-03-15"}'
$NH db-add-row -d <database_id> --title "Simple row with just a title"

# Create a new database
$NH db-create --page-id <parent_page_id> --title "Task Tracker" --properties '{
  "Name": {"title": {}},
  "Status": {"status": {}},
  "Priority": {"select": {"options": [{"name":"High"},{"name":"Medium"},{"name":"Low"}]}},
  "Due Date": {"date": {}},
  "Tags": {"multi_select": {"options": [{"name":"Bug"},{"name":"Feature"}]}},
  "Assignee": {"people": {}},
  "Done": {"checkbox": {}}
}'

# Update database schema
$NH db-update <db_id> --title "New Title"
$NH db-update <db_id> --properties '{"New Column": {"rich_text": {}}}'

# Get top-level blocks of a page
$NH blocks-get <page_id>
$NH blocks-get <page_id> --raw

# Get ALL blocks recursively (full page tree)
$NH blocks-get-all <page_id>
$NH blocks-get-all <page_id> --depth 5

# Append content
$NH block-append <page_id> --text "A new paragraph"
$NH block-append <page_id> --text "Item A\\nItem B\\nItem C" --type bulleted_list_item
$NH block-append <page_id> --blocks '[{"type":"heading_2","heading_2":{"rich_text":[{"text":{"content":"Section"}}]}},{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Content here"}}]}}]'

# Update a specific block
$NH block-update <block_id> --content '{"paragraph":{"rich_text":[{"text":{"content":"Updated text"}}]}}'

# Delete a block
$NH block-delete <block_id>

# List comments on a page
$NH comments-list <page_id>

# Add a comment to a page
$NH comment-create "This looks good!" --page-id <page_id>

# Reply in a discussion thread
$NH comment-create "Agreed" --discussion-id <discussion_id>

// Text property
{"property": "Name", "rich_text": {"contains": "keyword"}}

// Select
{"property": "Status", "select": {"equals": "Done"}}

// Multi-select
{"property": "Tags", "multi_select": {"contains": "Bug"}}

// Status
{"property": "Status", "status": {"equals": "In Progress"}}

// Checkbox
{"property": "Done", "checkbox": {"equals": true}}

// Date
{"property": "Due", "date": {"before": "2024-04-01"}}
{"property": "Due", "date": {"on_or_after": "2024-01-01"}}

// Number
{"property": "Score", "number": {"greater_than": 80}}

// Compound (AND)
{"and": [{"property": "Status", "status": {"equals": "Done"}}, {"property": "Priority", "select": {"equals": "High"}}]}

// Compound (OR)
{"or": [{"property": "Status", "status": {"equals": "Done"}}, {"property": "Status", "status": {"equals": "Archived"}}]}

[{"property": "Created", "direction": "descending"}]
[{"property": "Name", "direction": "ascending"}]
[{"timestamp": "last_edited_time", "direction": "descending"}]