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

  Removes ALL existing content from the database before syncing.

  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.

• -s, --save-id: Save the Notion page ID back to your markdown file's frontmatter after synchronization. This enables incremental updates on subsequent syncs by allowing MK Notes to identify and update existing pages rather than creating duplicates.

  How it works

  After a successful sync, MK Notes writes the Notion page ID to the id field in your markdown frontmatter. On subsequent syncs, MK Notes uses this ID to update the existing page instead of creating a new one.

• -f, --force-new: Force creation of new pages even if your markdown files contain existing page IDs. This is useful when you want to recreate all pages from scratch, ignoring any previously saved IDs.

  Use with caution

  Using --force-new will create duplicate pages if you have existing pages with the same content. Consider using --clean together with --force-new if you want to replace existing content.

• --flat: Flatten the result page tree, making all pages direct children of the destination instead of maintaining nested folder structures. When enabled, the root node is skipped and all files are created as direct children of the parent page.

  When to use flat mode

  Use --flat when you want a flat list of pages in Notion rather than a hierarchical structure. This is useful for:

  • Creating a simple list of documents without nested folders
  • Syncing to databases where you want all items at the same level
  • Simplifying navigation when folder structure isn't important

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. Delete existing content from the database
2. Create new pages as database items with the content from your markdown files

Syncing with Save ID (Incremental Updates)

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

This command will:

1. Read all markdown files in the ./my-docs directory
2. Create or update pages in Notion
3. Save the Notion page IDs back to each markdown file's frontmatter
4. Display a success message with the Notion page URL when complete

After running this command, your markdown files will have an id field in their frontmatter:

---
id: 12345678-1234-1234-1234-123456789abc
title: My Document
---

Content here...

On subsequent syncs with --save-id, MK Notes will update the existing pages instead of creating new ones.

Syncing with Force New (Recreate Pages)

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

This command will:

1. Read all markdown files in the ./my-docs directory
2. Ignore any existing page IDs in the markdown frontmatter
3. Create new pages in Notion for all files
4. Display a success message with the Notion page URL when complete

Combining Force New with Clean and Save ID

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

This command will:

1. Remove ALL existing content from the destination Notion page
2. Read all markdown files in the ./my-docs directory
3. Create new pages (ignoring any existing IDs)
4. Save the new page IDs back to the markdown files
5. Display a success message with the Notion page URL when complete

This is useful when you want to completely reset your synchronization and start fresh with new page IDs.

Syncing with Flat Structure

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

This command will:

1. Read all markdown files in the ./my-docs directory
2. Flatten the structure - all pages will be created as direct children of the destination page
3. Skip synchronizing the root node (if your directory has an index.md, it will be created as a child page instead of updating the parent)
4. Display a success message with the Notion page URL when complete

Example structure:

Without --flat:

Parent Page
  └── docs/
      ├── getting-started.md
      └── guides/
          └── installation.md

With --flat:

Parent Page
  ├── docs/ (root copy)
  ├── getting-started.md
  └── installation.md

All files are now direct children, making navigation simpler.

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
• --flat: Flatten the preview structure, showing how pages will appear when using the --flat option in sync. All pages will be displayed as direct children of the root.

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

5. Preview with flat structure:

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

This shows how the structure will look when using --flat during sync, with all pages as direct children of the root.

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.