Command Reference
Full reference for every Meldoc CLI command.
Global options
| Option | Description |
|---|---|
--debug |
Enable debug logging |
--token <token> |
Authentication token (overrides MELDOC_TOKEN) |
--project <alias> |
With several projects configured, limit the run to one of them. See Several Projects in One Repository |
Keep in mind:
--projectonmeldoc initis a different flag — there it writes the project alias into a new config file. Everywhere else it selects which of the configured projects to act on.
Exit codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Error |
4 |
Success with unresolved conflicts (push and pull only) |
meldoc init
Set up Meldoc for your project. Run this once in a Git repository to create meldoc.config.yml and configure .gitignore.
meldoc init
| Flag | Description |
|---|---|
--workspace <alias> |
Workspace alias (skips interactive prompt) |
--project <alias> |
Project alias (skips interactive prompt) |
--config |
Create or update meldoc.config.yml |
--force |
Reinitialize even if already set up |
--with-skills |
Install Meldoc AI agent skills to .claude/skills/ |
The command prompts for workspace and project aliases if not provided via flags or already in config. It adds .meldoc/ to .gitignore. Pass --with-skills to also install the Meldoc AI agent skills into .claude/skills/.
# Non-interactive setup
meldoc init --workspace my-workspace --project my-project
# Reinitialize and recreate config file
meldoc init --config --force
meldoc new
Create a new .meldoc.md file with correct YAML frontmatter. Does not push to the server — use meldoc push after creating.
meldoc new --alias my-document --title "My Document"
| Flag | Description |
|---|---|
[path] |
Output file path (optional, derived from alias if omitted) |
--alias <alias> |
Unique document identifier (required in non-interactive mode) |
--title <title> |
Document title (defaults to alias if omitted) |
--parent <alias> |
Parent document alias for hierarchy |
--template <alias> |
Write template: and seed the body from that Document Templates’s skeleton |
--project <alias> |
Project to create the document in (required with several configured) |
-i, --interactive |
Force interactive mode |
When --alias is omitted and stdout is a terminal, the command enters interactive mode automatically — prompting for alias, title, parent, and file path.
# Create with parent
meldoc new --alias child-page --parent parent-section
# Create at specific path
meldoc new docs/guide --alias guide --title "Guide"
# Interactive mode
meldoc new -i
meldoc scan
Find all documentation files and check for changes. Reports new, changed, and unchanged files.
meldoc scan
| Flag | Description |
|---|---|
--force |
Force cache update even if files haven’t changed |
meldoc push
Upload documentation changes to the server.
meldoc push
| Flag | Description |
|---|---|
[paths...] |
Push specific files by path |
--alias <alias> |
Push by alias (comma-separated or repeated) |
--force |
Push all files, ignore cache |
--dry-run |
Preview what would be pushed |
--no-assets |
Skip asset upload |
--track |
Add pushed files to the tracked set |
--resolve <mode> |
Conflict resolution: ours, theirs, ask, or merge (default: merge) |
--skip-validate |
Skip pre-publish validation |
Before uploading, meldoc push runs structural validation (same checks as meldoc validate). If errors are found, the push stops before anything reaches the server. Use --skip-validate to bypass this.
The CLI compares file checksums with the local cache and only uploads changed files. Use --force to re-upload everything.
When prune: true is set in Configuration, a full-repo push also deletes server documents that no longer exist locally. Use --dry-run to preview.
# Push specific files
meldoc push docs/api-guide.meldoc.md docs/getting-started.meldoc.md
# Push by alias
meldoc push --alias api-guide,getting-started
# Preview changes
meldoc push --dry-run
meldoc pull
Download the latest documentation from the server.
meldoc pull
| Flag | Description |
|---|---|
--alias <alias> |
Pull a single document by alias |
--to <path> |
Target path for a new document (used with --alias) |
--local |
Update only documents that exist locally |
--tracked |
Update only tracked documents |
--force |
Ignore cache, match by alias, no prompts |
--yes |
Answer yes to all prompts |
--resolve <mode> |
Conflict resolution: ours, theirs, ask, or merge (default: merge) |
--no-assets |
Skip asset download |
--force-assets |
Re-download all assets even if unchanged |
--updated-since <timestamp> |
Only fetch documents updated after this RFC3339 timestamp |
--archived |
Also pull archived documents (add --force to fetch the older archive, since pull is incremental) |
Pull modes
Full pull (default) downloads all documents from the server.
By alias (--alias) pulls a single document. If the file doesn’t exist locally, use --to to specify where to save it.
Local only (--local) updates only files that already exist in your repo — safe for partial checkouts.
Tracked only (--tracked) updates only documents in your tracked set (see meldoc track).
Incremental (--updated-since) fetches only documents modified after the given timestamp. Useful for cron jobs that already synced once and only need the delta.
--tracked and --local fetch through the batch endpoint, and the CLI splits the request into chunks the server advertises (100 documents when it says nothing). A repository with hundreds of tracked documents needs no manual paging — the chunks are looped over and merged for you.
# Pull a single document to a specific path
meldoc pull --alias new-feature --to docs/new-feature.meldoc.md
# Update only local files
meldoc pull --local
# Always use server version
meldoc pull --resolve theirs
# Incremental pull (only changes since last run)
meldoc pull --updated-since "2026-04-29T00:00:00Z"
meldoc ci
Push and delete documentation changes in CI/CD pipelines. Automatically detects which files changed between commits using git diff — no manual scripting needed.
meldoc ci
| Flag | Description |
|---|---|
--base <commit> |
Base commit for diff (auto-detected from CI environment) |
--head <commit> |
Head commit for diff (default: HEAD) |
--all |
Push all documents instead of only changed ones |
--dry-run |
Preview what would be pushed or deleted |
--force |
Force push, ignore cache |
--no-assets |
Skip asset upload |
--skip-validate |
Skip pre-publish validation |
In diff mode (default), meldoc ci compares two commits to find added, modified, and deleted .meldoc.md files. It pushes the changes and deletes removed documents from the server automatically.
The base commit is auto-detected from CI environment variables:
| Variable | CI provider |
|---|---|
GITHUB_EVENT_BEFORE |
GitHub Actions |
CI_COMMIT_BEFORE_SHA |
GitLab CI |
BITBUCKET_COMMIT~1 |
Bitbucket Pipelines |
If none are set, falls back to HEAD~1. Override with --base.
In --all mode, the command pushes every .meldoc.md file in the repo (like meldoc push). Pruning applies if prune: true is set in config.
Conflict resolution is always ours (local wins, non-interactive).
# Preview what would change
meldoc ci --dry-run
# Push all docs (not just changed)
meldoc ci --all
# Override base commit
meldoc ci --base abc1234
meldoc delete
Delete documents from the server by alias. Local files are not removed.
meldoc delete --alias my-document
| Flag | Description |
|---|---|
--alias <alias> |
Aliases to delete (required, comma-separated or repeated) |
--yes |
Skip confirmation prompt |
# Delete multiple documents
meldoc delete --alias old-feature,deprecated-guide
# Skip confirmation
meldoc delete --alias old-feature --yes
Keep in mind: a Renaming & Redirects is refused — the name now points at a different document, so the item is reported as
skippedrather than deleted. Use the current alias.
meldoc archive
Archive a document on the server by alias or short id. The whole subtree is archived with it; content and links keep working. See Archiving Documents.
meldoc archive my-old-runbook
| Flag | Description |
|---|---|
--replaced-by <alias> |
Record a successor document (pass an empty value to clear one) |
--dry-run |
Report how many documents would be archived, without writing |
meldoc unarchive
Restore a document from the archive by alias or short id. Children archived with it stay archived — restore each deliberately.
meldoc unarchive my-old-runbook
meldoc validate
Check your documentation structure for errors before pushing.
meldoc validate
| Flag | Description |
|---|---|
--fix |
Auto-fix fixable issues (e.g., assign parentAlias to orphaned documents) |
--strict |
Exit non-zero on content findings too — broken links, broken assets, unresolvable replacedBy. Does not apply to Document Templates warnings |
--token <token> |
Enable server-aware checks (scope validation, cross-project links) |
What it checks
File and cache checks — duplicate aliases, alias mismatches between cache and frontmatter, missing files, legacy id fields.
Field checks — empty alias or title, invalid workflow/visibility/exposure values, self-referencing parentAlias, negative order values, invalid alias characters.
Structure checks — missing or ambiguous parent references, circular parentAlias chains, duplicate order values among siblings, and siblings not numbered from 0 without gaps (the server renumbers every parent’s children to 0 … n-1, so any other numbering stops matching the files; a parent whose numbers are still the ones the last sync wrote is left alone, because archived pages that pull leaves out keep their positions).
Content checks — broken Magic Links (Wiki Links), broken cross-project links, broken relative doc links, broken asset references.
Formatting checks (warnings, never blocking; --fix inserts what is missing) — a blank line around headings, before lists and tables, and after the closing --- of the front matter. That last line belongs to the file, not the document: push leaves it out of what Meldoc stores, and pull writes it back.
Scope checks (with --token) — duplicate aliases with out-of-scope server docs, missing scope roots, documents outside the scope tree, circular chains through server documents.
# Validate with server-aware checks
meldoc validate --token $MELDOC_TOKEN
# Auto-fix orphaned documents
meldoc validate --fix
meldoc import
Convert documentation you already have into local .meldoc.md files: a folder of Markdown (an Obsidian vault counts) or an official Notion export, zipped or unpacked.
meldoc import --from markdown ./old-docs
meldoc import --from notion ./notion-export.zip --out documentation
| Flag | Description |
|---|---|
--from |
Source format: markdown or notion. Required |
--out |
Directory to write the tree into (default docs) |
--dry-run |
Print the plan, write nothing |
--force |
Overwrite files that are already there |
It never writes to the server. You get files in your working tree, review the diff, and run meldoc push when you are ready. Without --force it refuses rather than overwrite, and names every clashing path at once instead of stopping at the first.
A MIGRATION_REPORT.md lands beside the tree listing what the source syntax could not be expressed in. See Importing existing documentation for the full walkthrough.
meldoc migrate
Fix what’s wrong with your files’ aliases, in two phases:
Phase 1 — missing aliases. Adds an alias field to files that have none, using data from the local cache or server. Also removes the legacy id field if present.
Phase 2 — retired aliases. Moves files off names the server has Renaming & Redirects: updates the alias: in frontmatter and rewrites every [[old-name]] link across the repository in one pass, so nothing is left half-renamed. Only text inside [[...]] is touched — prose and code fences are safe.
meldoc migrate
| Flag | Description |
|---|---|
--dry-run |
Show what would change without writing |
Run meldoc validate after migration to verify the results. validate reports a link that still uses a former alias as a warning — the link works through a redirect, and meldoc migrate is how you clean it up.
meldoc organize
Reorganize local documentation files to match the hierarchy defined in frontmatter. This is a local-only operation — no server access needed.
meldoc organize
| Flag | Description |
|---|---|
--dry-run |
Preview moves without executing |
--force |
Reorganize even if files are already in the correct location |
--base-dir <dir> |
Override base directory from config |
Documents with children become {alias}/index.meldoc.md. Documents with a parent but no children move into their parent’s directory. Root documents with no children stay in the base directory.
# Preview first
meldoc organize --dry-run
# Then reorganize
meldoc organize
meldoc docs
List all local documentation files in a hierarchical tree view. Shows alias, title, workflow status, and file path.
meldoc docs
| Flag | Description |
|---|---|
--duplicates |
Show only documents with duplicate aliases |
--subtree <alias> |
Show a specific document and all its descendants |
Duplicate aliases are highlighted with a ⚠ marker. Documents with unresolvable parentAlias values appear in an Orphans section.
meldoc templates
Browse the project’s Document Templates. Read-only — both subcommands prefer the server and fall back to the local cache, marking the output (cached … — server unreachable) when they do.
templates list
meldoc templates list [--project <alias>]
Lists every template in the project, marking the project default with *.
templates show
meldoc templates show <alias> [--project <alias>]
Prints one template: title, description, the custom field keys it carries, and its skeleton.
| Flag | Description |
|---|---|
--project <alias> |
Which project’s registry (required with several configured) |
--token <token> |
Authentication token |
meldoc track
Manage tracked documents — a subset of server documents you work with locally.
track add
meldoc track add --alias <alias> [--path <path>]
Add a document to the tracked set. The path is auto-detected from local files if omitted.
track remove
meldoc track remove --alias <alias>
track list
meldoc track list
track clear
meldoc track clear [--yes]
Remove all tracked documents. Use --yes to skip confirmation.
meldoc skills
Manage AI agent skills installed in your project.
skills init
meldoc skills init [--force]
Install embedded Meldoc skills to .claude/skills/. Use --force to overwrite existing skills.
skills update
meldoc skills update [--yes]
Check for outdated or removed skills and update them. Use --yes to skip confirmation.
skills list
meldoc skills list
Show name, version, and description for each installed skill.
skills add
meldoc skills add <url> [--force]
Download and install a skill from a URL — the shipped ones are at https://meldoc.io/skills/<name>/SKILL.md, see IDE Setup. Use --force to overwrite an existing skill with the same name.
meldoc auth
Manage authentication credentials.
auth login
meldoc auth login
Opens your browser for authentication. Tokens are stored in ~/.meldoc/credentials.json and refreshed automatically.
auth status
meldoc auth status
Show current authentication status, email, and workspace.
auth logout
meldoc auth logout
Remove stored credentials.
meldoc mcp
MCP (Model Context Protocol) integration for AI assistants.
mcp init
meldoc mcp init
Create or update MCP configuration for your IDE.
| Flag | Description |
|---|---|
--global |
Install to user home directory (works across all projects) |
--cursor |
Create Cursor IDE configuration |
--vscode |
Create VS Code configuration |
--windsurf |
Create Windsurf configuration |
--claude-desktop |
Create Claude Desktop configuration |
--force |
Overwrite existing configuration |
--http |
Configure HTTP mode (direct connection, no subprocess) |
Only one IDE flag per invocation. Local install (default) writes config and agent skills to the project directory. Global install (--global) writes them to your home directory so they work across all projects.
# Global install for Cursor
meldoc mcp init --global --cursor
# Local install for VS Code
meldoc mcp init --vscode
mcp serve
meldoc mcp serve
Start the MCP server over stdio.
| Flag | Description |
|---|---|
--cli-only |
Local tools only — don’t connect to the remote MCP server |
--env-file <path> |
Load environment variables from file |
--config-file <path> |
Custom config file path |
By default the server exposes local tools plus the documentation tools proxied from the Meldoc server. Repository operations — scanning, validating, pushing, pulling — are meldoc commands, not MCP tools.
mcp doctor
meldoc mcp doctor
Check MCP setup health — verifies the binary, authentication, token configuration, and MCP config file.
meldoc cache clear
Delete the local cache. Useful when the cache is corrupted or out of sync.
meldoc cache clear
This removes .meldoc/cache/ but preserves your tracked documents and config file. After clearing, run meldoc scan or meldoc push --force to rebuild.
meldoc updateVersion
Update the CLI to the latest version.
meldoc updateVersion
| Flag | Description |
|---|---|
--force |
Update without confirmation |
Downloads the latest binary from GitHub Releases, verifies the checksum, and replaces the current executable. Cannot update dev builds.
meldoc setup
Interactive setup wizard that configures PATH, MCP for your IDE, and optional login.
meldoc setup
| Flag | Description |
|---|---|
--force |
Re-run even if already configured |
--skip-auth |
Skip the login step |
--skip-path |
Skip PATH setup |
The installer runs this automatically in interactive terminals. After a pipe install (curl ... | bash), open a new terminal and run ~/.local/bin/meldoc setup.
meldoc setup-path
Add the Meldoc binary directory to PATH on Windows. Modifies the user PATH in the Windows registry and broadcasts the change to running processes. No-op on macOS and Linux.
meldoc setup-path
meldoc version
Print the installed CLI version.
meldoc version
meldoc help
Show command usage and help information.
meldoc help