CLI Reference

All commands are available as both mdtolink and mdtl (shorthand). For example, mdtl publish and mdtolink publish are identical. You can also use mdtl <file> as a shorthand for mdtl publish <file>.

Command Aliases

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

Commands

mdtolink login

Authenticate with your MDtoLink account using the device authorization flow. Opens your browser to complete authorization, then stores the session token locally.

mdtolink login

Token storage: ~/.config/mdtolink/token.json (mode 0600)

---

mdtolink logout

Clear the stored authentication token.

mdtolink logout

---

mdtolink publish <file>

Publish a markdown file to a shareable URL. If the file was previously published, updates the existing document (same URL).

mdtolink publish <file> [options]

Arguments:

Argument	Required	Description
file	Yes	Path to the markdown file to publish

Options:

Option	Description
--slug <slug>	Custom filename (Pro+ only, e.g., meeting-notes)
--title <title>	Custom document title (defaults to filename without extension)
--private	Publish as private document (Pro+ only)
--draft	Alias for --private

Examples:

# Basic publish
mdtolink publish notes.md

# With custom title
mdtolink publish notes.md --title "Sprint Retro Notes"

# With custom filename (Pro+)
mdtolink publish notes.md --slug sprint-retro

# Publish as private (Pro+)
mdtolink publish notes.md --private
mdtolink publish notes.md --draft

Behavior:

• If not logged in, prompts to authorize before publishing
• If the file was previously published from this machine, updates the existing document
• Stores the file-to-document mapping in ~/.config/mdtolink/documents.json

---

mdtolink unpublish [file-or-slug]

Remove a published document. Can be used with a file path, slug, or interactively.

mdtolink unpublish [file-or-slug]

Arguments:

Argument	Required	Description
file-or-slug	No	File path or document slug. If omitted, shows interactive picker.

Examples:

# By file path
mdtolink unpublish notes.md

# By slug
mdtolink unpublish my-notes

# Interactive mode
mdtolink unpublish

Interactive mode:

• Shows your 5 most recent documents as checkboxes (spacebar to toggle)
• Includes an option to enter a slug manually
• Confirms before deleting

---

mdtolink list

List your published documents in a formatted table.

mdtolink list [options]

Options:

Option	Default	Description
--limit <n>	20	Number of documents to show (1-100)
--offset <n>	0	Number of documents to skip

Example:

mdtolink list --limit 10

Output columns: Title, Slug, Status, Views, Created

---

mdtolink help

Show help information and available commands.

mdtolink help
mdtolink --help
mdtolink <command> --help

---

Environment Variables

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

Configuration Files

All configuration is stored in ~/.config/mdtolink/:

File	Description
token.json	Authentication token from mdtolink login
documents.json	Mapping of local file paths to published document IDs

Both files are created with 0600 permissions (owner read/write only).

documents.json format

{
  "/path/to/file.md": {
    "documentId": "abc123",
    "slug": "xk9f2m",
    "url": "https://mdtolink.com/d/xk9f2m",
    "lastPublished": "2026-03-01T12:00:00.000Z"
  }
}

Keys are absolute file paths, resolved at publish time. This enables idempotent updates — publishing the same file always updates the same document.