> ## Documentation Index
> Fetch the complete documentation index at: https://differens.ossl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> The differens command: all flags, formats, and modes

# CLI Reference

The `differens` command is a single binary. It runs in five modes and prints four 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` | Output format (default `terminal`)     |
| `--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 print the `.gitattributes` lines to add |

## Examples

<CodeGroup>
  ```bash Diff the working tree theme={null}
  differens
  ```

  ```bash Diff two files theme={null}
  differens src/app.ts src/app.new.ts
  ```

  ```bash Diff two directories theme={null}
  differens release/1.0/ release/1.1/
  ```

  ```bash Diff a commit range theme={null}
  differens main..feature
  ```

  ```bash Diff two commits theme={null}
  differens 8f3a1c2 5b0e9d7
  ```

  ```bash JSON output theme={null}
  differens main..feature --format=json
  differens main..feature --json
  ```

  ```bash List languages theme={null}
  differens languages
  ```

  ```bash Install the git driver theme={null}
  differens install-git-driver
  ```
</CodeGroup>

## 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.
* Files over 2 MiB are treated as whole-file changes. Differens writes `note: fell back to … diff` to stderr.

## 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.