CLI Reference

Command-Line Help for `panache`

This document contains the help content for the panache command-line program.

`panache`

Panache is a CLI formatter and LSP for Quarto (.qmd), Pandoc, and Markdown files written in Rust. It understands Quarto/Pandoc-specific syntax that other formatters like Prettier and mdformat struggle with, including fenced divs, tables, and math formatting.

Usage: panache [OPTIONS] <COMMAND>

EXAMPLES:

# Format a file in place
panache format document.qmd

# Format from stdin to stdout
cat document.qmd | panache format

# Check if a file is formatted
panache format --check document.qmd

# Use custom config
panache format --config custom.toml document.qmd

# Parse and inspect CST
panache parse document.qmd

# Parse and verify losslessness (input == CST text)
panache parse --verify document.qmd

CONFIGURATION:

Panache looks for configuration files in this order: 1. Explicit –config path 2. panache.toml or .panache.toml in current/parent directories 3. ~/.config/panache/config.toml (XDG) 4. Built-in defaults

Example .panache.toml:

flavor = "quarto"
line-width = 80

[extensions]
hard-line-breaks = false
citations = true

For more information, visit: https://github.com/jolars/panache

Subcommands:

format — Format a Quarto, Pandoc, or Markdown document
parse — Parse and display the CST tree for debugging
lsp — Start the Language Server Protocol server
lint — Lint a Quarto, Pandoc, or Markdown document
debug — Debug utilities for parser/formatter diagnostics

Options:

--config <CONFIG> — Path to a custom configuration file. If not specified, panache will search for .panache.toml or panache.toml in the current directory and its parents, then fall back to ~/.config/panache/config.toml.

`panache format`

Format a Quarto, Pandoc, or Markdown document according to panache’s formatting rules. By default, formats files in place. Use –check to verify formatting without making changes. With –verify, panache runs parser/formatter invariants without writing changes to disk. Stdin input always outputs to stdout.

Usage: panache format [OPTIONS] [FILES]...

EXAMPLES:

# Format file in place (default)
panache format document.qmd

# Format multiple files
panache format file1.md file2.md file3.qmd

# Use glob patterns (expanded by shell)
panache format **/*.{md,qmd}

# Format entire directory recursively, all supported files
panache format .
panache format docs/

# Format from stdin to stdout
echo '# Heading' | panache format

# Check formatting (exit code 1 if not formatted)
panache format --check document.qmd

# Verify parser/formatter invariants (does not write changes)
panache format --verify document.qmd

Arguments:

<FILES> — Path(s) to the input file(s) or directories to format. If not provided, reads from stdin. Supports .qmd, .md, .Rmd, and other Markdown-based formats. When file paths are provided, the files are formatted in place by default. Stdin input always outputs to stdout. Supports glob patterns (e.g., *.md) and directories (e.g., . or docs/). Directories are traversed recursively, respecting .gitignore files.

Options:

--check — Check if the file is already formatted according to panache’s rules without making any changes. If the file is not formatted, displays a diff and exits with code 1. If formatted, exits with code 0. Useful for CI/CD pipelines.
--range <START:END> — Format only the specified line range. Lines are 1-indexed and inclusive. The range will be expanded to complete block boundaries to ensure well-formed output. For example, if you select part of a list, the entire list will be formatted. Format: –range START:END (e.g., –range 5:10 formats lines 5 through 10).

Note: This feature is experimental. Range filtering may not work correctly in all cases.
--verify — Run smoke-check invariants: (1) parser losslessness (input == parsed CST text) and (2) formatter idempotency (format(format(x)) == format(x)). When formatting files by path (including directories), –verify does not write any changes to disk. Exits with code 1 when verification fails.

Deprecated: prefer panache debug format --checks all.

`panache parse`

Parse a document and display its Concrete Syntax Tree (CST) for debugging and understanding how panache interprets the document structure. The CST shows all block and inline elements detected by the parser.

Usage: panache parse [OPTIONS] [FILE]

EXAMPLES:

# Parse a file and show CST
panache parse document.qmd

# Parse a file and write CST JSON to disk
panache parse --json cst.json document.qmd

# Parse from stdin
echo '# Heading' | panache parse

# Parse without printing CST output
panache parse --quiet document.qmd

# Parse with custom config (affects extension parsing)
panache parse --config .panache.toml document.qmd

# Verify parser losslessness while parsing
panache parse --verify document.qmd

Arguments:

<FILE> — Path to the input file to parse. If not provided, reads from stdin. The parser respects extension flags from the configuration file.

Options:

--json <PATH> — Write the parsed CST to the given JSON file instead of printing the debug tree. The output includes node kinds, text ranges, and token text.
--quiet — Suppress CST output to stdout. Useful with –verify for smoke-testing large files without terminal spam. Verification failures still print diagnostics and exit non-zero.
--verify — Run parser losslessness verification (input == parsed CST text). Exits with code 1 when verification fails.

Deprecated: prefer panache debug format --checks losslessness.

`panache lsp`

Start the panache Language Server Protocol (LSP) server for editor integration. The LSP server provides formatting capabilities to editors like VS Code, Neovim, and others that support LSP.

Usage: panache lsp [OPTIONS]

The LSP server communicates via stdin/stdout and is typically launched automatically by your editor’s LSP client. You generally don’t need to run this command manually.

For editor configuration examples, see: https://github.com/jolars/panache#editor-integration

Options:

--debug — Enable verbose LSP debug logging to ~/.local/state/panache/lsp-debug.log (or $XDG_STATE_HOME/panache/lsp-debug.log when XDG_STATE_HOME is set). Logs are written to file to avoid interfering with the LSP protocol over stdout.

`panache lint`

Lint a document to check for correctness issues and best practice violations. Unlike the formatter which handles style, the linter catches semantic problems like syntax errors, heading hierarchy issues, and broken references.

Usage: panache lint [OPTIONS] [FILES]...

EXAMPLES:

# Lint a file and show diagnostics
panache lint document.qmd

# Lint multiple files
panache lint file1.md file2.qmd

# Lint entire directory
panache lint .

# Lint from stdin
echo '# H1\n### H3' | panache lint

# Check mode for CI (exit code 1 if violations found)
panache lint --check document.qmd

# Apply auto-fixes
panache lint --fix document.qmd

LINT RULES:

Parser errors: Syntax errors detected during parsing
Heading hierarchy: Warns on skipped heading levels (e.g., h1 → h3)

Configure rules in .panache.toml with [lint] section.

Arguments:

<FILES> — Path(s) to the input file(s) or directories to check. If not provided, reads from stdin. Supports .qmd, .md, .Rmd, and other Markdown-based formats. Supports glob patterns (e.g., *.md) and directories (e.g., . or docs/). Directories are traversed recursively, respecting .gitignore files.

Options:

--check — Exit with code 1 if violations found (CI mode)
--fix — Automatically fix violations where possible

`panache debug`

Debugging utilities for parse/format workflows. These commands are intended for diagnosing parser losslessness and formatter idempotency failures in repositories.

Usage: panache debug <COMMAND>

Subcommands:

format — Run parser+formatter checks and emit diagnostics

`panache debug format`

Run parser+formatter checks and emit diagnostics

Usage: panache debug format [OPTIONS] [FILES]...

Arguments:

<FILES> — Input file path(s) or directories

Options:

--checks <CHECKS> — Which checks to run

Default value: all

Possible values: idempotency, losslessness, all
--json — Emit JSON output for machine-readable tooling
--dump-dir <DIR> — Directory where failing artifacts are written

Command-Line Help for panache

panache

Subcommands:

Options:

panache format

Arguments:

Options:

panache parse

Arguments:

Options:

panache lsp

Options:

panache lint

Arguments:

Options:

panache debug

Subcommands:

panache debug format

Arguments:

Options:

Command-Line Help for `panache`

`panache`

`panache format`

`panache parse`

`panache lsp`

`panache lint`

`panache debug`

`panache debug format`