Workflow

Learn how to use the CLI day-to-day — pulling changes, editing documents, and pushing updates.

The two sync operations

Everything below is built from two commands that move documents between your .meldoc.md files and the server:

Operation	Command	What it does
Push	meldoc push	Upload local changes to the server
Pull	meldoc pull	Download server changes to your files

First-time setup

In a fresh clone, or in a repository that has never been synced:

meldoc init         # creates meldoc.config.yml, adds .meldoc/ to .gitignore
meldoc auth login   # or: export MELDOC_TOKEN=your-token
meldoc pull         # download the documents that already exist on the server

See Quick Start for the full walkthrough, including your first document.

Daily workflow

Start each session by pulling the latest changes from the server:

meldoc pull

Edit your .meldoc.md files, then scan and push when you’re ready to publish:

meldoc scan
meldoc push

Commit the changes to Git so your team stays in sync:

git add docs/
git commit -m "Update DundlerOS API docs"
git push

Add a new document

meldoc new --alias order-endpoints   # create the file with correct frontmatter
# edit the file
meldoc validate                      # check the structure before publishing
meldoc push --alias order-endpoints  # upload just this one

Make a structural change

When you move a document in the hierarchy — a new parentAlias, a different order — edit the frontmatter first, then let the CLI move the files to match:

meldoc organize --dry-run   # preview the file moves
meldoc organize             # execute them
meldoc validate             # verify the result
meldoc push

Add aliases to existing files

If you have .meldoc.md files without an alias, fetch the aliases from the server and write them into the frontmatter:

meldoc migrate
meldoc validate
meldoc push

Push a single document

You don’t have to push everything. Target specific files by path or alias:

# By path
meldoc push docs/order-endpoints.meldoc.md

# By alias
meldoc push --alias order-endpoints

# Preview what would change
meldoc push --dry-run

Work with tracked documents

Tracked documents let you work with a subset of server documents locally — useful for large projects where you don’t need every file.

Pull a single document

# First time — specify where to save
meldoc pull --alias inventory-sync --to docs/warehouse/inventory-sync.meldoc.md

# After that, just use the alias
meldoc pull --alias inventory-sync

Manage the tracked set

# Add a document to tracking
meldoc track add --alias order-endpoints

# Add it at an explicit path
meldoc track add --alias order-endpoints --path docs/order-endpoints.meldoc.md

# List tracked documents
meldoc track list

# Stop tracking a document
meldoc track remove --alias order-endpoints

# Pull only tracked documents
meldoc pull --tracked

# Pull only documents that exist locally
meldoc pull --local

meldoc pull --local is the one to use when you have a partial checkout of the repository — it updates the files you have and leaves the rest alone.

Keep the repository as source of truth

For projects synced from a repository, make all edits in your local files and publish via meldoc push. Avoid editing the same documents in the Meldoc web UI — while the merge system handles this, keeping one source of truth prevents unnecessary conflicts.

Fix duplicate aliases

Two files claiming the same alias is the most common structural error. Find them, edit one of them, and verify:

meldoc docs --duplicates
# edit the offending files
meldoc validate
meldoc push

Reset local state

If something goes wrong, back up your docs and re-sync from the server:

cp -r docs docs-backup
rm -rf .meldoc
meldoc init --force
meldoc pull --force

Restore any local changes you need from the backup, then push:

meldoc scan
meldoc push

Habits worth keeping

• Pull before you start work, so you edit the current version.
• Push in small batches rather than accumulating a week of local changes — conflicts get harder the longer you wait.
• Keep documentation in version control alongside the code it describes, and use clear commit messages.
• In CI, store tokens as secrets, never in the repository. See CI/CD Integration.

What’s next?

Conflict Resolution — Handle sync conflicts when local and server edits collide.

Team Workflow — Collaborate on documentation with your team.

Working with Assets — Work with images and files alongside your documents.

CI/CD Integration — Automate publishing from CI/CD pipelines.

Troubleshooting — Solve problems when a command doesn’t do what you expect.