CLI Reference

The differens command is a single binary. It runs in five modes and prints five output formats.

differens [options] [args]

Modes

Invocation	What it diffs
`differens`	Working tree vs HEAD (git mode)
`differens diff`	Explicit alias for the above
`differens <old> <new>`	Two files, or two commits when both args resolve as git refs
`differens <old>/ <new>/`	Two directories, walked file by file
`differens main..feature`	Commit range
`differens <sha1> <sha2>`	Two commits (refs are resolved first, files are the fallback)

Options

Flag	Description
`--format=terminal\|json\|markdown\|llm\|ndjson`	Output format (default `terminal`, or the config file’s `format`)
`--json`, `-j`	Shorthand for `--format=json`
`--markdown`, `--md`	Shorthand for `--format=markdown`
`--llm`, `-l`	Shorthand for `--format=llm`
`--help`, `-h`	Print usage
`--version`, `-v`	Print version (read from package.json)

Subcommands

Command	Description
`diff`	Explicit diff mode; takes the same inputs as bare invocation
`languages`	List supported languages with their level (L6 semantic / L5 generic) and extensions
`install-git-driver`	Register Differens as the git diff driver and write the `.gitattributes` rules itself

Config file

differens.toml (or .differensrc.json) in the working directory, or the nearest ancestor that has one, changes the defaults:

# differens.toml
format = "json"                      # default output format
driverExtensions = ["ts", "tsx"]     # extensions install-git-driver registers

Flags override the config. Unknown keys and malformed values are ignored, and an unparseable config file is skipped rather than fatal.

Examples

differens

differens src/app.ts src/app.new.ts

differens release/1.0/ release/1.1/

differens main..feature

differens 8f3a1c2 5b0e9d7

differens main..feature --format=json
differens main..feature --json

differens main..feature --format=ndjson

--format=ndjson prints one JSON object per changed file as its diff finishes, always in input order, so a long changeset streams instead of buffering. Cross-file moves trail as one final object with a crossFileMoves key when any exist.

differens languages

differens install-git-driver

Exit behavior

When the diff is empty, any mode prints “nothing changed” (or “nothing changed in range: …”) instead of failing.
Errors exit 1 with a message on stderr: not in a git repo, file cannot be read, a directory against a file, or malformed args.

Internal flags

The CLI also accepts two flags for internal use: --git-diff-driver (git invokes the registered driver with it) and a worker flag used by the parallel diff pool. Ignore them in scripts.

​CLI Reference

​Modes

​Options

​Subcommands

​Config file

​Examples

​Exit behavior

​Internal flags