---
description: "Every rumdl command and flag, including which stream findings are written to, what each exit code means, and the machine readable formats."
icon: lucide/terminal
---
# CLI Commands
Complete reference for rumdl command-line interface.
## Commands
### `check [PATHS...]`
Lint Markdown files and report issues.
```bash
rumdl check . # Lint current directory
rumdl check README.md docs/ # Lint specific files/directories
rumdl check --fix . # Lint and auto-fix issues
```
**Options:**
| `--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 |
| `--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.
### `fmt [PATHS...]`
Format Markdown files (applies fixes like `rumdl check --fix`, but keeps formatter-style exit codes).
```bash
rumdl fmt . # Format all files
rumdl fmt README.md # Format specific file
rumdl fmt --silent - # Format stdin to stdout without diagnostics
```
**Options:**
| `--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.
```bash
rumdl init # Create .rumdl.toml
rumdl init --preset google # Use Google style preset
rumdl init --output custom.toml # Custom output path
```
**Options:**
| `--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.
```bash
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:**
| `--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.
```bash
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:**
| `--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.
```bash
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.
```bash
rumdl server # Start Language Server Protocol server
```
See [LSP Integration](../lsp.md) for details.
### `vscode`
Install VS Code extension.
```bash
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.
```bash
rumdl --version # Short version
rumdl version # Detailed version info
```
## Global Options
These options are commonly used with `check` and `fmt`:
| `--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](#output-formats)) |
## Exit Codes
| `0` | Success |
| `1` | Lint violations found |
| `2` | Configuration or runtime error |
!!! note "fmt vs check --fix"
- `rumdl fmt` always exits 0 (formatter mode)
- `rumdl check --fix` exits 1 if unfixable issues remain
!!! note "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.
!!! note "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:
```text
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
```bash
# Lint all Markdown files
rumdl check .
# Lint specific directory
rumdl check docs/
# Lint with custom config
rumdl check --config my-config.toml .
```
### Selective Rules
```bash
# Disable specific rules
rumdl check --disable MD013,MD033 .
# Enable only specific rules
rumdl check --enable MD001,MD003 .
```
### File Filtering
```bash
# 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
```bash
# Watch for changes
rumdl check --watch docs/
```
### Stdin/Stdout
```bash
# Format from stdin
# With filename context
# Format clipboard (macOS)
### Output Formats
Control how warnings are displayed with `--output-format`:
```bash
rumdl check --output-format full .
rumdl check --output-format json .
RUMDL_OUTPUT_FORMAT=github rumdl check .
```
**Human-readable formats:**
| `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:**
| `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](../output-formats.md) for the field-level reference for each
machine-readable format.
**CI/CD formats:**
| `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:**
```text
MD013 Line length 95 exceeds 80 characters
--> README.md:42:81
|
|
```
**Example: `text` format output (default):**
```text
README.md:42:81: [MD013] Line length 95 exceeds 80 characters
```