#+OPTIONS: num:nil toc:nil

* CLI Reference

** Synopsis

#+begin_src text
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
#+end_src

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
