CLI Commands

MK Notes provides two main commands to help you manage your markdown to Notion synchronization:

sync

The sync command synchronizes markdown files to a Notion page or database. You can sync either a single markdown file or an entire directory of markdown files, creating a matching page hierarchy for directories.

Usage

mk-notes sync -i <path> -d <notionUrl> -k <notionApiKey>

Required Options

• -i, --input <path>: Path to a markdown file or directory containing your markdown files
• -d, --destination <notionUrl>: URL of the parent Notion page or database where content will be synchronized
• -k, --notion-api-key <notionApiKey>: Your Notion API key for authentication

Optional Options

• -c, --clean: Clean sync mode - behavior depends on the destination type:

  For Notion Pages

  Removes ALL existing content from the destination page before syncing, including any manually added content or blocks not created by mk-notes.

  For Notion Databases

  Finds and deletes existing pages with the same id (using the mk-notes-id notion database property) before creating new ones. This requires the id property to be set in your markdown frontmatter.

  For more information about synchronization into a database, you can read the Database Synchronization guide.

• -l, --lock: Lock the Notion page after syncing to prevent further editing. This is useful when you want to preserve the synchronized content and prevent accidental modifications.

Destination Types

Mk Notes supports two types of destinations:

Notion Page

When the destination is a Notion page, content is appended directly to the page (or replaces existing content with --clean). Child pages are created as sub-pages.

Notion Database

When the destination is a Notion database, pages are created as database items. This is useful for managing collections of documents where you want to leverage Notion's database features like filtering, sorting, and views.

Examples

Syncing a Directory

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123...

This command will:

1. Read all markdown files in the ./my-docs directory
2. Create a matching page hierarchy in Notion
3. Convert and sync the content to your specified Notion page
4. Display a success message with the Notion page URL when complete

Syncing a Directory with Clean Sync (Caution)

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123... \
  --clean

This command will:

1. Remove ALL existing content from the destination Notion page (including any custom blocks and content not created by mk-notes)
2. Read all markdown files in the ./my-docs directory
3. Create a matching page hierarchy in Notion
4. Convert and sync the content to your specified Notion page
5. Display a success message with the Notion page URL when complete

Syncing a Single File

mk-notes sync \
  --input ./my-docs/README.md \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123...

This command will:

1. Read the single markdown file ./my-docs/README.md
2. Create a single Notion page with the file content
3. Convert and sync the content to your specified Notion page
4. Display a success message with the Notion page URL when complete

Syncing with Page Locking

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123... \
  --lock

This command will:

1. Read all markdown files in the ./my-docs directory
2. Create a matching page hierarchy in Notion
3. Convert and sync the content to your specified Notion page
4. Lock the Notion page to prevent further editing
5. Display a success message with the Notion page URL when complete

Syncing with Both Clean and Lock Options

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123... \
  --clean \
  --lock

This command will:

1. Remove ALL existing content from the destination Notion page (including pages that are locked)
2. Read all markdown files in the ./my-docs directory
3. Create a matching page hierarchy in Notion
4. Convert and sync the content to your specified Notion page
5. Lock the Notion page to prevent further editing
6. Display a success message with the Notion page URL when complete

Syncing to a Notion Database

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/database-123456 \
  --notion-api-key secret_abc123...

This command will:

1. Read all markdown files in the ./my-docs directory
2. Create pages as items in the specified Notion database
3. Display a success message when complete

Syncing to a Database with Clean Sync

mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/database-123456 \
  --notion-api-key secret_abc123... \
  --clean

For database destinations with clean sync, make sure your markdown files include an id in the frontmatter:

---
id: my-unique-page-id
title: My Document
---

Content here...

This command will:

1. Find existing pages in the database with matching mk-notes-id property
2. Delete those existing pages
3. Create new pages as database items with the content from your markdown files

preview-sync

The preview-sync command lets you preview how your markdown files will be organized in Notion before actually performing the synchronization. This is useful for verifying the structure before making any changes.

Usage

mk-notes preview-sync -i <path> [options]

Required Option

• -i, --input <path>: Path to a markdown file or directory containing your markdown files

Optional Options

• -f, --format <format>: Output format for the preview
  • plainText (default): Shows a tree-like structure
  • json: Outputs the structure in JSON format
• -o, --output <output>: Save the preview to a file instead of displaying it in the terminal

Examples

1. Basic preview with default format:

mk-notes preview-sync --input ./my-docs

Output example for directory:

├─  (Your parent Notion Page)
│   ├─ getting-started.md
│   ├─ guides/
│   │   ├─ installation.md
│   │   ├─ configuration.md
│   ├─ api/
│   │   ├─ endpoints.md
│   │   ├─ authentication.md

Output example for single file:

├─  (Your parent Notion Page)
│   ├─ README.md

2. Preview in JSON format:

mk-notes preview-sync --input ./my-docs --format json

3. Save preview to a file:

mk-notes preview-sync --input ./my-docs --output preview.txt

4. Preview a single file:

mk-notes preview-sync --input ./my-docs/README.md

Single File vs Directory Synchronization

Mk Notes automatically detects whether your input path is a single markdown file or a directory and handles each case appropriately:

Single File Synchronization

• Input: A path to a single .md file
• Behavior: Creates a single Notion page with the file content
• Use case: When you want to sync just one specific document
• Example: mk-notes sync -i ./docs/README.md -d <notion-url> -k <api-key>

Directory Synchronization

• Input: A path to a directory containing markdown files
• Behavior: Creates a hierarchical structure in Notion matching your directory structure
• Use case: When you want to sync an entire documentation project
• Example: mk-notes sync -i ./docs -d <notion-url> -k <api-key>

Error Handling

• If you provide a non-markdown file, Mk Notes will show an error message
• If you provide a path that doesn't exist, you'll get a clear error message
• Only .md files are supported for synchronization

Tips for Using CLI Commands

1. Directory Structure

   • Organize your markdown files in a logical hierarchy
   • Use directories to create sections and subsections
   • Consider using index.md files for section introductions

2. Preview First

   • Always use preview-sync before running the actual sync
   • Verify the structure matches your expectations
   • Make adjustments to your file organization if needed

3. Notion API Key

   • Keep your API key secure
   • Consider using environment variables for the API key
   • Make sure your API key has the necessary permissions

4. Regular Backups

   • Consider backing up your Notion pages before large syncs
   • Use preview-sync to verify changes before updating existing content
   • Be extremely cautious when using the --clean flag as it will delete ALL content on the destination page
   • Avoid using --clean on Notion pages that contain important manual content not created by mk-notes

For more details about how MK Notes organizes your content, see the Architecture documentation.