CLI Reference

Install

No global install required — run directly with npx:

$ npx mding-cli

Or install globally for a shorter command:

$ npm install -g mding-cli $ mding-cli

Commands

mding-cli [path]

Connect a folder and start syncing. Scans for .md files, opens a WebSocket to markdown.ing, and starts watching for file changes. If not authenticated, runs the login flow automatically.

Argument	Description	Default
`path`	Directory to watch	`.` (current dir)

screenshot: cli-connect.png — CLI connected to a workspace

mding-cli auth login

Start the device code authentication flow. Opens your browser to a verification page and displays a code in the terminal. Confirm the code in your browser to authenticate.

Your session token is saved to ~/.config/mding/config.json. You only need to do this once per machine.

screenshot: cli-login.png — device code auth flow

mding-cli auth logout

Revoke your session token on the server and remove it locally. If the server is unreachable, the local token is still removed.

mding-cli auth status

Show your authentication status, server URL, config file location, and workspace info.

screenshot: cli-auth-status.png — auth status display

mding-cli status

Alias for mding-cli auth status.

mding-cli ping

Test connectivity to the markdown.ing server. Reports latency in milliseconds. Exits with code 1 on failure — useful for scripting.

$ mding-cli ping ✓ ok Server reachable (42ms)

mding-cli disconnect

Terminate an active workspace session from another terminal. Useful if a session got stuck or you closed a terminal without disconnecting cleanly.

Global flags

Flag	Description
`--server <url>`	Override the server URL (default: `https://app.markdown.ing`)
`--no-browser`	Don't auto-open the browser on connect or login
`--verbose`	Show detailed output (connection events, WebSocket frames)
`--quiet`	Suppress non-essential output
`--version, -v`	Show version number
`--help, -h`	Show help text

How sync works

The CLI connects to markdown.ing over WebSocket using Phoenix channels. Once connected:

Your file tree is sent to the server (names and paths, not content)
When you open a file in the browser, the server asks the CLI for its content
When you save in the browser, the server sends the content to the CLI, which writes to disk
When you edit a file on disk, the CLI detects the change and notifies the server

Your content is not stored on our servers. Files are transmitted over the WebSocket only while the CLI is running. When you disconnect, nothing remains server-side.

Activity log

While connected, the CLI displays a real-time activity log showing file sync events:

screenshot: cli-activity.png — activity log with colored sync events

Icon	Event	Description
`+`	create	New file detected on disk
`~`	update	File changed on disk
`-`	delete	File removed from disk
`→`	open	Browser requested file content
`←`	save	Browser saved changes to disk
`↑`	sync	Content sent to browser
`!`	error	Sync error occurred

Reconnection

If the connection drops, the CLI reconnects automatically with exponential backoff (up to 60 seconds between attempts). Events that occur while disconnected are queued and replayed when the connection resumes.

Limits

Maximum file size: 10 MB
Watches .md files recursively in the target directory
Symlinks are resolved — paths outside the target directory are rejected for security

Configuration

Config is stored at ~/.config/mding/config.json (mode 0600). The CLI supports multiple server configurations:

{
  "default_server": "https://app.markdown.ing",
  "servers": {
    "https://app.markdown.ing": {
      "access_token": "...",
      "authenticated_at": "2026-04-16T..."
    }
  }
}

Use --server to connect to a different instance. The CLI upgrades older flat config formats automatically.

SSH usage

mding-cli works on any machine with Node.js — including remote servers you access via SSH. No port forwarding, no X11, no special configuration:

remote server

  $ ssh prod-server admin@prod $ npx mding-cli ~/docs ✓ Connected to markdown.ing # open browser on your local machine — editing remote files  

screenshot: cli-ssh.png — mding-cli running over SSH

The browser on your local machine connects to the same markdown.ing session. Edits in the browser write to files on the remote server. File changes on the server update the browser instantly.