---
title: CLI Reference
description: >-
  Comprehensive reference for the Panache CLI, including all commands, options, and usage examples.
---

# Command-Line Help for `panache`

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

## `panache`

Panache is a command-line formatter, linter, and language server (implementing the Language Server Protocol, 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>`

For help with a specific command, see: `panache help <command>`.

Homepage and downloads (including .deb and .rpm packages): <https://panache.bz>

###### **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
* `clean` — Delete cache data
* `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.
* `--stdin-filename <PATH>` — Synthetic filename to associate with stdin input. This is useful for editor integrations that pipe content via stdin but still need Panache to infer flavor/extensions from file extension (for example: --stdin-filename doc.qmd).
* `--flavor <FLAVOR>` — Override the markdown flavor for this invocation. Takes the highest precedence: it overrides any value in panache.toml, the [flavor-overrides] glob table, and the flavor inferred from the file extension. Extension overrides from [extensions] in panache.toml still merge on top of the flavor's defaults. Useful when the file extension is unknown (e.g. a .txt file containing markdown) or when you want to force a one-off interpretation.

  Possible values:
  - `pandoc`:
    Pandoc's Markdown (the extended dialect described in `man pandoc`)
  - `quarto`:
    Quarto's Markdown (Pandoc-based, with Quarto-specific extensions and shortcodes)
  - `rmarkdown`:
    R Markdown (Pandoc-based, with knitr/Rmd code chunks)
  - `gfm`:
    GitHub Flavored Markdown
  - `commonmark`:
    CommonMark (the strict, standardized base dialect)
  - `multimarkdown`:
    MultiMarkdown (Fletcher Penney's extended Markdown dialect)

* `--color <WHEN>` — Control when colored output is used

  Default value: `auto`

  Possible values: `auto`, `always`, `never`

* `--no-color` — Disable colored output (equivalent to --color never)
* `-q`, `--quiet` — Suppress informational status messages on stdout (e.g. "Formatted X", "N file left unchanged", "All files are correctly formatted", "No issues found") as well as per-violation lint diagnostics. Errors are still written to stderr, and primary command output (such as formatted content when reading from stdin, JSON/Markdown reports, or the parsed CST) continues to print so that pipelines keep working. The process exit code still reflects whether issues were found in --check mode.
* `-v`, `--verbose` — Print additional informational output where supported. Currently used by `panache clean` to include a summary of cache size and file count alongside the "Removed cache directory" message. Conflicts with --quiet.
* `--isolated` — Ignore all discovered configuration files
* `--no-cache` — Disable all lint/format cache reads and writes for this run. Can also be enabled with PANACHE_NO_CACHE.
* `--cache-dir <CACHE_DIR>` — Path to the cache directory for this invocation. Overrides config `cache-dir`. Can also be set with PANACHE_CACHE_DIR.
* `-j`, `--jobs <N>` — Number of worker threads to use when formatting or linting multiple files. 0 (the default) selects an automatic level based on available CPU cores. 1 forces serial processing. Single-file invocations always run on one thread; the inner external-formatter pool (see external-max-parallel) is only used when this value is 1 or when only one file is being processed. Can also be set with PANACHE_JOBS.

  Default value: `0`



## `panache format`

Format a Quarto, Pandoc, or R 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]...`

###### **Arguments:**

* `<FILES>` — Path(s) to the input file(s) or directories to format. If not provided, or if the single argument `-` is given, reads from stdin. Supports .qmd, .md, .Rmd/.Rmarkdown, 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. `-` cannot be combined with other paths.

###### **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`.
* `--force-exclude` — Apply exclude patterns from your configuration even to files passed explicitly on the command line.

   By default, explicitly-named files bypass exclude patterns: the assumption is that if you asked for a specific file, you want it processed. With --force-exclude, those patterns are honored regardless.

   This is primarily intended for pre-commit hooks (and similar tooling), which pass changed files explicitly but should still respect the project's exclude configuration.
* `-o`, `--option <KEY=VALUE>` — Override an individual config option for this invocation, using the kebab-case key names from panache.toml. May be repeated. Takes precedence over both panache.toml and the built-in defaults. 

   Supported keys: `line-width` (positive integer) and `wrap` (one of: reflow, sentence, preserve). 

   Example: --option line-width=100 -o wrap=sentence. 

   Note: this is an escape hatch for ad-hoc invocations. Prefer panache.toml so that everyone formatting the repository gets the same result.



## `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]`

###### **Arguments:**

* `<FILE>` — Path to the input file to parse. If not provided, or if `-` is given, reads from stdin. The parser respects extension flags from the configuration file.

###### **Options:**

* `--to <FORMAT>` — Choose what to print to stdout:
   - cst (default): debug-format CST tree, useful for parser debugging.
   - pandoc-ast: pandoc-native AST text, the same shape produced by `pandoc -f markdown -t native`. Unsupported constructs emit visible `Unsupported "<KIND>"` sentinels rather than being silently dropped.
   - pandoc-json: the same AST encoded as JSON, matching `pandoc -f markdown -t json`. UTF-8 round-trips cleanly through `jq`/`ascii2uni` since strings use standard JSON escaping rather than Haskell-show numeric escapes.

  Default value: `cst`

  Possible values: `cst`, `pandoc-ast`, `pandoc-json`

* `--json <PATH>` — Write the parsed CST to the given JSON file in addition to printing the selected --to format to stdout. The JSON output is always CST-shaped regardless of --to; it includes node kinds, text ranges, and token text.
* `--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]...`

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

###### **Arguments:**

* `<FILES>` — Path(s) to the input file(s) or directories to check. If not provided, or if the single argument `-` is given, reads from stdin. Supports .qmd, .md, .Rmd/.Rmarkdown, and other Markdown-based formats. Supports glob patterns (e.g., *.md) and directories (e.g., . or docs/). Directories are traversed recursively, respecting .gitignore files. `-` cannot be combined with other paths.

###### **Options:**

* `--check` — Exit with code 1 if violations found (CI mode)
* `--fix` — Automatically fix violations where possible
* `--message-format <MESSAGE_FORMAT>` — Diagnostic rendering format

  Default value: `human`

  Possible values: `human`, `short`

* `--force-exclude` — Apply exclude patterns from your configuration even to files passed explicitly on the command line. 

   By default, explicitly-named files bypass exclude patterns: the assumption is that if you asked for a specific file, you want it processed. With --force-exclude, those patterns are honored regardless. 

   This is primarily intended for pre-commit hooks (and similar tooling), which pass changed files explicitly but should still respect the project's exclude configuration.



## `panache clean`

Delete Panache's on-disk cache data.

**Usage:** `panache clean [OPTIONS]`

###### **Options:**

* `--all` — Remove all Panache cache buckets
* `--dry-run` — Print the cache path(s) that would be deleted, along with a summary of file count and size, but do not modify anything on disk. The size summary is always shown in --dry-run mode (the global --verbose flag is not required). Combine with --all to preview removal of every cache bucket.



## `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 (use `-` for stdin)

###### **Options:**

* `--checks <CHECKS>` — Which checks to run

  Default value: `all`

  Possible values: `idempotency`, `losslessness`, `all`

* `--json` — Emit JSON output for machine-readable tooling
* `--report` — Emit Markdown report output suitable for issue descriptions
* `--dump-dir <DIR>` — Directory where failing artifacts are written
* `--dump-passes` — Write input/parse/format pass artifacts to --dump-dir for every file
* `--force-exclude` — Apply exclude patterns from your configuration even to files passed explicitly on the command line. 

   By default, explicitly-named files bypass exclude patterns: the assumption is that if you asked for a specific file, you want it processed. With --force-exclude, those patterns are honored regardless. 

   This is primarily intended for pre-commit hooks (and similar tooling), which pass changed files explicitly but should still respect the project's exclude configuration.



