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

# Installation

> Install the Differens CLI and libraries

# Installation

Differens ships as an npm CLI plus five published libraries. It is built with Bun, TypeScript, and Turborepo, and runs on any platform that supports Bun or Node.

## Prerequisites

* **Bun >= 1.3** or **Node >= 18.17** to run the CLI and install the libraries
* A package manager (`npm`, `bun`, or your tool of choice) to install from npm

## Install the CLI

Install globally, or add it to your project as a dev dependency:

<CodeGroup>
  ```bash npm (global) theme={null}
  npm install -g differens
  ```

  ```bash bun (global) theme={null}
  bun install -g differens
  ```

  ```bash npm (project-local) theme={null}
  npm install -D differens
  ```

  ```bash Source build theme={null}
  git clone https://github.com/ossl-dev/differens
  cd differens
  bun install
  bun run build
  bun link
  ```
</CodeGroup>

## Install the libraries

Each stage of the pipeline is published as a separate package under the `@ossl-dev` scope. Install only the pieces you use:

<CodeGroup>
  ```bash npm theme={null}
  npm install @ossl-dev/differens-core
  ```

  ```bash bun theme={null}
  bun add @ossl-dev/differens-core
  ```

  ```bash All libraries theme={null}
  npm install \
    @ossl-dev/differens-core \
    @ossl-dev/differens-tiers \
    @ossl-dev/differens-narrate \
    @ossl-dev/differens-correlate \
    @ossl-dev/differens-git
  ```
</CodeGroup>

## The six packages

| Package                         | Description                                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `differens`                     | The CLI: working tree, file, directory, and commit-range diffs with terminal, JSON, markdown, and LLM output |
| `@ossl-dev/differens-core`      | The semantic diff core: GumTree-lineage tree matching over postorder arrays, emitting typed edit scripts     |
| `@ossl-dev/differens-tiers`     | Content-tier adapters that parse code, config, and markup into trees the core can match                      |
| `@ossl-dev/differens-narrate`   | Turns a differens edit script into sentences, markdown, JSON, or a token-frugal format for models            |
| `@ossl-dev/differens-correlate` | Cross-file correlation: finds the code that moved between two files                                          |
| `@ossl-dev/differens-git`       | Git integration: working tree, commit range, and directory diffs, plus the git diff driver                   |

## Standalone executable

To ship Differens as a single binary that needs no runtime install:

<CodeGroup>
  ```bash bun build --compile theme={null}
  bun build --compile packages/cli/src/index.ts --outfile differens
  ./differens --help
  ```
</CodeGroup>

<Info>
  The compiled binary bundles Bun's runtime, so it runs on machines without Bun or Node installed. The tradeoff is a larger file.
</Info>

## Verify the installation

```bash theme={null}
differens --help
```

You should see usage for the core commands:

```text theme={null}
Usage: differens [options] [a] [b]

Diff a working tree, two files, two directories, or a commit range.

Options:
  --format <format>  terminal | json | markdown | llm (default: terminal)
  --help             Show this help message
  --version          Show the version number
```

Next: the [Quickstart](/getting-started/quickstart).