Skip to content

CLI Commands

Complete reference for rumdl command-line interface.

Commands

check [PATHS...]

Lint Markdown files and report issues.

rumdl check .                    # Lint current directory
rumdl check README.md docs/      # Lint specific files/directories
rumdl check --fix .              # Lint and auto-fix issues

Options:

Option Description
--fix Auto-fix issues (exits 1 if unfixable issues remain)
--config <PATH> Path to configuration file
--disable <RULES> Disable specific rules (e.g., MD013,MD033)
--enable <RULES> Enable only specific rules
--exclude <PATTERNS> Exclude files matching patterns
--include <PATTERNS> Include only files matching patterns
--stdin-batch Read NUL-delimited path/content pairs from stdin
--stdin-batch-closed-world Resolve batch links only within the supplied document set
--watch Watch for changes and re-lint
--verbose Show detailed output
--quiet Print diagnostics, but suppress summaries
--silent Suppress diagnostics and summaries
--no-exclude Disable exclude patterns defined in config
--stderr Write diagnostics to stderr instead of stdout
--deny-config-warnings Treat configuration warnings as errors (exit code 2)

Findings go to stdout, whether the document came from a path or from --stdin, so --output-format json redirects the same way in both. --stderr moves them; config warnings and errors are always on stderr. The exception is a document rewritten on stdout - check --fix --stdin and fmt --stdin - where stdout belongs to the document and diagnostics go to stderr.

The closing summary is written for a person, so a machine-readable format never carries one and needs no --quiet to keep its output parseable.

Batch stdin

--stdin-batch checks many caller-supplied snapshots in one process. The byte stream is a repeated path NUL content NUL sequence and must end in NUL:

path\0content\0path\0content\0

Paths and contents must be UTF-8, paths must be non-empty and unique after path normalization, and content may be empty. Each path is both the diagnostic name and the filesystem context used for configuration and relative links.

By default, supplied documents take precedence and links to documents omitted from the batch fall back to the on-disk workspace. Add --stdin-batch-closed-world to prohibit that fallback. Batch input never reads or writes the persistent workspace-index cache, because supplied content may differ from the file saved at the same path.

Batch mode is check-only and cannot be combined with paths, --stdin, --stdin-filename, --fix, --diff, --check, or --watch.

fmt [PATHS...]

Format Markdown files (applies fixes like rumdl check --fix, but keeps formatter-style exit codes).

rumdl fmt .                      # Format all files
rumdl fmt README.md              # Format specific file
rumdl fmt --silent -             # Format stdin to stdout without diagnostics

Options:

Option Description
--config <PATH> Path to configuration file
--diff Show a diff of what would change instead of rewriting files
--check Exit 1 if formatting changes would be needed
--stdin Read from stdin
--stdin-filename <NAME> Filename for stdin (for error messages)
--output-format <FMT> Output format for any remaining diagnostics
--watch Re-run formatting when files change
--quiet Print diagnostics, but suppress summaries
--silent Suppress diagnostics and summaries
--deny-config-warnings Treat configuration warnings as errors (exit code 2)

Use --silent whenever stdout should contain only formatted Markdown. Plain rumdl fmt - may also emit remaining diagnostics.

init [OPTIONS]

Create a configuration file.

rumdl init                       # Create .rumdl.toml
rumdl init --preset google       # Use Google style preset
rumdl init --output custom.toml  # Custom output path

Options:

Option Description
--pyproject Generate configuration for pyproject.toml
--preset <NAME> Use a style preset (default, google, relaxed)
--output <PATH> Output file path (default: .rumdl.toml)

import <FILE>

Import configuration from markdownlint.

rumdl import .markdownlint.json      # Import from markdownlint config
rumdl import .markdownlint.jsonc     # JSONC comments are supported
rumdl import .markdownlint.yaml      # YAML also works
rumdl import --dry-run .markdownlint.json
rumdl import --format json .markdownlint.yaml --output rumdl-config.json

Options:

Option Description
--dry-run Show the converted config without writing
--format <FMT> Output format: toml or json
--output <PATH> Output file path (default: .rumdl.toml)

rule [<RULE>]

Show rule documentation.

rumdl rule                       # List all rules
rumdl rule MD013                 # Show details for specific rule
rumdl rule line-length           # Use rule alias
rumdl rule --list-categories     # Discover rule categories
rumdl rule MD013 --output-format json
rumdl rule MD013 --output-format json --explain

Options:

Option Description
--list-categories List rule categories and exit
--category <NAME> Filter listed rules by category
--fixable Show only fixable rules
--output-format <FMT> Structured output such as json or json-lines
--explain Include full documentation in JSON-based output

config [OPTIONS]

Show effective configuration.

rumdl config                     # Show merged configuration
rumdl config --defaults          # Show default values only
rumdl config --no-defaults       # Show non-default values only

server

Start the LSP server.

rumdl server                     # Start Language Server Protocol server

See LSP Integration for details.

vscode

Install VS Code extension.

rumdl vscode                     # Install extension
rumdl vscode --status            # Check installation
rumdl vscode --update            # Update the installed extension
rumdl vscode --force             # Force reinstall

version

Show version information.

rumdl --version                  # Short version
rumdl version                    # Detailed version info

Global Options

These options are commonly used with check and fmt:

Option Description
--help, -h Show help
--version, -V Show version
--verbose, -v Verbose output
--quiet, -q Print diagnostics, but suppress summaries
--color <WHEN> Color output (auto, always, never)
--no-config Ignore discovered configuration and use built-in defaults
--output-format <FMT> Output format (see Output Formats)

Exit Codes

Code Meaning
0 Success
1 Lint violations found
2 Configuration or runtime error

fmt vs check --fix

  • rumdl fmt always exits 0 (formatter mode)
  • rumdl check --fix exits 1 if unfixable issues remain

Failing on configuration problems

Configuration problems (an unknown rule or option in a config file or a CLI flag, an unknown rule in an inline rumdl-disable-line comment, a shadowed config file, a subdirectory config that could not be loaded, an .editorconfig property rumdl cannot apply, or a run in which every Markdown file found was filtered out) are non-fatal warnings by default and do not affect the exit code. Pass --deny-config-warnings to make any of them exit with code 2, so CI catches a typo'd rule name. This is distinct from --fail-on, which governs the severity of Markdown violations (exit 1); a config problem exits 2 and takes precedence over Markdown violations.

When nothing gets checked

Checking zero files and checking every file cleanly both exit 0 with no findings, so rumdl reports which one happened on stderr. A directory holding no Markdown says so plainly; a run whose files were all filtered out instead reports how many were found and which setting removed them:

No markdown files left to check: 12 files found were filtered out.
  12 by ignore files (.gitignore, .ignore, .markdownlintignore); pass --respect-gitignore=false to keep them

The notice never shares a stream with the selected output, so it stays out of --output-format json and the other machine-readable formats: it goes to stderr, or to stdout when --stderr routes diagnostics the other way. It survives --quiet; use --silent to suppress it, or --deny-config-warnings to fail the run instead.

Usage Examples

Basic Linting

# Lint all Markdown files
rumdl check .

# Lint specific directory
rumdl check docs/

# Lint with custom config
rumdl check --config my-config.toml .

Selective Rules

# Disable specific rules
rumdl check --disable MD013,MD033 .

# Enable only specific rules
rumdl check --enable MD001,MD003 .

File Filtering

# Exclude directories
rumdl check --exclude "node_modules,dist" .

# Include only specific patterns
rumdl check --include "docs/**/*.md" .

# Combine patterns
rumdl check --include "docs/**/*.md" --exclude "docs/drafts" .

Watch Mode

# Watch for changes
rumdl check --watch docs/

Stdin/Stdout

# Format from stdin
cat README.md | rumdl fmt --silent -

# With filename context
cat README.md | rumdl check - --stdin-filename README.md

# Format clipboard (macOS)
pbpaste | rumdl fmt --silent - | pbcopy

Output Formats

Control how warnings are displayed with --output-format:

rumdl check --output-format full .
rumdl check --output-format json .
RUMDL_OUTPUT_FORMAT=github rumdl check .

Human-readable formats:

Format Description
text One line per warning: file:line:col: [RULE] message (default)
full Source lines with caret underlines highlighting the violation
concise Minimal: file:line:col rule message
grouped Warnings grouped by file with a header per file

Machine-readable formats:

Format Description
json JSON array of all warnings (collected)
json-lines One JSON object per warning (streaming)
sarif SARIF 2.1.0 for static analysis tools
junit JUnit XML for CI test reporters

See Output Formats for the field-level reference for each machine-readable format.

CI/CD formats:

Format Description
github GitHub Actions annotations (::warning/::error)
gitlab GitLab Code Quality report (JSON)
azure Azure Pipelines logging commands
pylint Pylint-compatible format

Example: full format output:

MD013 Line length 95 exceeds 80 characters
 --> README.md:42:81
   |
42 | This is a long line that exceeds the configured maximum line length ...
   |                                                                     ^^^
   |

Example: text format output (default):

README.md:42:81: [MD013] Line length 95 exceeds 80 characters