notionfs 0.4.0

Local-first sync for Notion. Work with pages as markdown files.

Features

Installation

pip install notionfs

Quick Start

# Set your Notion API token
export NOTION_TOKEN="secret_..."

# Initialize a workspace (interactive page selection)
notionfs clone

# Or from a URL directly
notionfs clone https://www.notion.so/My-Page-abc123...

# Sync your changes
notionfs pull    # Download from Notion
notionfs push    # Upload to Notion
notionfs sync    # Bidirectional sync

Commands

Workspace Structure

my-workspace/
├── .notionfs/
│   ├── config.toml       # Workspace config
│   └── state.db          # Sync state
├── Page Title.md         # Leaf page
├── Parent Page/          # Page with children -> directory
│   ├── _index.md         # Parent page content
│   └── Child Page.md
└── Database Name/        # Database -> directory
    ├── Entry 1.md
    └── Entry 2.md

Markdown Format

Pages are markdown with YAML frontmatter for database properties:

---
Status: In Progress
Tags:
  - work
  - important
Due Date: 2024-03-15
---

# Meeting Notes

Your content here.

- Bullet points
- [ ] Todo items
- [x] Completed items

> Quotes work too

Conflict Resolution

# Check for conflicts
notionfs status

# Resolve conflicts
notionfs resolve "Page.md" --keep-local   # Your version wins
notionfs resolve "Page.md" --keep-remote  # Notion version wins
notionfs resolve "Page.md" --keep-both    # Keep both versions

Watch Mode

# Continuous sync (2s local debounce, 30s remote poll)
notionfs watch

# Custom intervals
notionfs watch -d 1 -i 60    # 1s debounce, 60s poll

Configuration

Token lookup order:

1. NOTION_TOKEN environment variable
2. ~/.notionfs/config.toml file

# Save token permanently
notionfs auth secret_...

Tips & Tricks

# Search across all notes
grep -r "TODO" .

# Batch edit
find . -name "*.md" -exec sed -i 's/old/new/g' {} \;
notionfs push

# Git integration (version history for your notes)
git init && echo ".notionfs/" >> .gitignore

Troubleshooting

# Debug mode
notionfs --debug pull
notionfs --debug push

# Page not accessible?
# -> Add your integration via page menu -> Connections

License

MIT