@prmworks/mdbook

CLI companion for MDBook — sync markdown files between your local filesystem and MDBook projects.

Write in your editor, push to MDBook. Edit in MDBook, pull to local. Keep everything in sync.

Install

npm install -g @prmworks/mdbook

Requires Node.js >= 18.17.

Quick start

# 1. Log in with your MDBook account
mdbook-cli login

# 2. Link the current directory to a project
mdbook-cli link

# 3. Push local markdown files to MDBook
mdbook-cli push

# 4. Or pull remote files down
mdbook-cli pull

Commands

mdbook-cli login

Authenticate with your MDBook account. You'll enter your email, receive a 6-digit verification code, and the CLI stores your session locally.

mdbook-cli login

mdbook-cli logout

Clear stored credentials.

mdbook-cli logout

mdbook-cli whoami

Show the currently logged-in user and verify the session is still valid.

mdbook-cli whoami

mdbook-cli link

Link the current directory to an MDBook project. This creates a .mdbook.json file in your directory that tracks which remote project it maps to.

# Interactive — pick from your projects or create a new one
mdbook-cli link

# Direct — link by project ID
mdbook-cli link --project-id <id>

Re-running link replaces the existing link.

mdbook-cli push

Upload local markdown files to the linked remote project. New files are created, modified files are updated.

mdbook-cli push

# Also delete remote files that don't exist locally
mdbook-cli push --delete

# Skip confirmation prompt
mdbook-cli push -y

mdbook-cli pull

Download remote project files to the current directory. New and modified files are downloaded.

mdbook-cli pull

# Also delete local files that don't exist on remote
mdbook-cli pull --delete

# Skip confirmation prompt
mdbook-cli pull -y

mdbook-cli diff

Show what's different between your local files and the remote project.

mdbook-cli diff

# Include inline content diffs for modified files
mdbook-cli diff --content

How it works

The CLI compares your local .md files against the remote project using content hashes. On each push or pull, it shows a summary of what will change and asks for confirmation before proceeding.

Local config files:

| File | Location | Purpose | |------|----------|---------| | ~/.mdbook/config.json | Home directory | User info | | .mdbook.json | Project directory | Project link and sync state |

Add .mdbook.json to your .gitignore — it contains project-specific sync state and IDs.

License

MIT