CLI Guide

The MDtoLink CLI lets you publish, update, and manage markdown documents directly from your terminal.

Installation

Install globally via your preferred package manager:

# npm
npm install -g mdtolink

# pnpm
pnpm add -g mdtolink

# bun
bun add -g mdtolink

This gives you two commands: mdtolink and mdtl (shorthand). Both work identically — use whichever you prefer.

Shorthands

The CLI supports short aliases for every command, and mdtl <file> works as a shorthand for mdtl publish <file>:

# These are all equivalent:
mdtolink publish notes.md
mdtl publish notes.md
mdtl p notes.md
mdtl notes.md

All available aliases:

Command	Aliases
publish	p, pub
unpublish	rm, remove, delete
list	ls, l
login	auth, signin
logout	signout

Authentication

Before publishing, authenticate with your MDtoLink account:

mdtolink login

This opens your browser where you authorize the CLI. Once approved, your session token is stored locally at ~/.config/mdtolink/token.json.

You don’t need to login before running publish — if you’re not authenticated, the CLI will prompt you to authorize inline.

Publishing a document

mdtolink publish README.md
# → Published: https://mdtolink.com/d/xk9f2m

The CLI reads the file, uploads it to your account, and returns a shareable URL.

Custom title

By default, the title is derived from the filename. Override it with --title:

mdtolink publish notes.md --title "Meeting Notes - March 2026"

Custom filename (Pro)

Pro users can set custom filenames:

mdtolink publish notes.md --slug my-notes
# → Published: https://mdtolink.com/d/my-notes

Private documents (Pro)

Pro users can publish documents that are only visible to them when signed in. Anyone else sees “Document not found.”

mdtolink publish notes.md --private
# → Published (private): https://mdtolink.com/@david/notes

# --draft is an alias for --private
mdtolink publish notes.md --draft

Updating a document

Publishing the same file again updates the existing document — same URL, fresh content:

# First publish
mdtolink publish notes.md
# → Published: https://mdtolink.com/d/xk9f2m

# Edit notes.md, then:
mdtolink publish notes.md
# → Updated: https://mdtolink.com/d/xk9f2m

This works because the CLI stores a local mapping between file paths and document IDs in ~/.config/mdtolink/documents.json.

Listing documents

View all your published documents:

mdtolink list

Paginate with --limit and --offset:

mdtolink list --limit 10 --offset 20

Unpublishing

Remove a document by file path or slug:

# By file path
mdtolink unpublish notes.md

# By slug
mdtolink unpublish my-notes

Or run without arguments for an interactive picker:

mdtolink unpublish
# Shows your recent documents with checkbox selection

Logging out

Clear your stored authentication token:

mdtolink logout

Environment variables

Variable	Default	Description
MDTOLINK_SERVER_URL	https://api.mdtolink.com	API server URL
MDTOLINK_APP_URL	https://mdtolink.com	Base URL for document links