CLI Reference

Synopsis

snapper [OPTIONS] [FILE...]
snapper init [--dry-run]
snapper sdiff [--no-color] [-f FORMAT] <OLD> <NEW>
snapper git-diff [--no-color] [-f FORMAT] [REF] [FILE...]
snapper watch [-f FORMAT] <PATTERNS...>
snapper lsp

If no files are given, snapper reads from stdin and writes to stdout.

Options

-f, --format <FORMAT>

Input format. One of: org, latex, markdown, plaintext.

Auto-detected from file extension when omitted. Defaults to plaintext for stdin.

--stdin-filepath <PATH>

Assume this filename when reading stdin, for format auto-detection. Useful for editor integrations that pipe buffer contents.

Example: cat paper.org | snapper --stdin-filepath paper.org

-o, --output <FILE>

Write output to a file instead of stdout.

-i, --in-place

Modify input files in place. Requires file arguments (not stdin).

-w, --max-width <N>

Maximum line width. Sentences exceeding this width are wrapped at word boundaries using textwrap. Default: 0 (unlimited). Also respects max_line_length from .editorconfig if present.

--check

Check mode for CI. Exits with code 1 if any file would change, without modifying anything. Prints the paths of files that would be reformatted to stderr.

--diff

Show a unified diff of what would change, without modifying anything. Useful for reviewing before committing. Exits with code 1 if any file would change.

--range <START:END>

Only format lines in the given range (1-indexed, inclusive). Lines outside the range pass through unchanged. Useful for editor format-selection integrations.

Example: snapper --range 10:20 paper.org

--output-format <text|json|sarif>

Output format for --check mode. Default: text (prints filenames to stderr).

  • json : outputs a JSON array with file paths and line counts

  • sarif : outputs SARIF v2.1.0 for GitHub Code Scanning integration

--neural

Use neural sentence detection via nnsplit (byte-level LSTM, tract backend). Downloads and caches the model (~4MB) to ~/.cache/nnsplit/ on first use. Rule-based detection remains the default (faster, better abbreviation handling). Neural excels for non-English text.

--lang <CODE>

Language for neural sentence detection. Default: en. Available: en, de, fr, no, sv, zh, tr, ru, uk.

--model-path <PATH>

Path to a custom ONNX model file for neural detection. Overrides --lang.

--config <PATH>

Path to a .snapperrc.toml config file. When omitted, snapper searches from the current directory upward.

-h, --help

Print help message.

-V, --version

Print version.

Subcommands

snapper init

Initialize snapper for a project. Detects which prose formats exist in the directory tree and generates:

  • .snapperrc.toml with sensible defaults

  • .gitattributes entries for the git smudge/clean filter

  • pre-commit hook snippet

  • Apheleia (Emacs) configuration snippet

Use --dry-run to preview without writing files.

snapper sdiff <OLD> <NEW>

Sentence-level diff between two files. Parses both files, extracts sentences, diffs at sentence granularity. Whitespace reflow produces zero diff. Colored output by default; use --no-color to disable. Exits with code 1 if differences found.

snapper git-diff [REF] [FILE...]

Sentence-level diff against a git ref. Default ref: HEAD. If no files specified, diffs all changed prose files (.org, .tex, .md). Uses git show REF:path to retrieve the old version.

snapper watch <PATTERNS...>

Watch files and auto-reformat on save. Accepts file paths or glob patterns. 200ms debounce to avoid reformatting during rapid saves. Press Ctrl+C to stop.

snapper lsp

Start the Language Server Protocol server on stdin/stdout. Provides document formatting, range formatting, and diagnostics (flags lines with multiple sentences). Works with any LSP-compatible editor (Neovim, Emacs eglot, VS Code, Helix).

Exit codes

  • 0 : Success (or --check / --diff with no changes needed)

  • 1 : --check or --diff found files that would change, or any error