# Installation

> Install via npm/bun global package or Cargo build script; platform support matrix and prebuilt binary layout.

- Repository: anomalyco/rift
- GitHub: https://github.com/anomalyco/rift
- Human docs: https://www.grok-wiki.com/public/docs/anomalyco-rift-ea3fd5dbf662
- Complete Markdown: https://www.grok-wiki.com/public/docs/anomalyco-rift-ea3fd5dbf662/llms-full.txt

## Source Files

- `README.md`
- `npm/rift-snapshot/package.json`
- `npm/rift-snapshot/bin/rift.js`
- `scripts/install.sh`
- `.github/workflows/release.yml`

---

---
title: "Installation"
description: "Install via npm/bun global package or Cargo build script; platform support matrix and prebuilt binary layout."
---

The `rift-snapshot` npm package ships a Node CLI shim (`bin/rift.js`) that resolves and executes a platform-specific prebuilt `rift` binary from `prebuilds/<platform>-<arch>/`. The same package bundles FFI shared libraries for Bun and Node conditional exports. No install lifecycle scripts run during `npm install`; artifacts are selected at runtime from the published tarball.

<Warning>
This repository is experimental. Behavior, interfaces, and implementation details may change without notice.
</Warning>

## Installation methods

<Tabs>
<Tab title="npm">

```bash
npm install -g rift-snapshot
```

The global `rift` command points at `bin/rift.js`, which spawns the bundled native executable with inherited stdio.

</Tab>
<Tab title="bun">

```bash
bun add -g rift-snapshot
```

Bun uses the same launcher shim and prebuilt CLI binary layout as npm.

</Tab>
<Tab title="Cargo">

From a repository checkout:

```bash
./scripts/install.sh
```

`scripts/install.sh` runs:

```bash
cargo install --path crates/cli --root "${CARGO_HOME:-$HOME/.cargo}" --force --locked
```

The optimized CLI lands at `${CARGO_HOME:-$HOME/.cargo}/bin/rift`. This path builds only `rift-cli`; it does not bundle FFI libraries for JavaScript.

</Tab>
<Tab title="GitHub Releases">

Release archives are published on version tags (`v*`) to [GitHub Releases](https://github.com/anomalyco/rift/releases/latest).

| Archive name pattern | Target triple | Contents |
| --- | --- | --- |
| `rift-<tag>-x86_64-unknown-linux-gnu.tar.gz` | `x86_64-unknown-linux-gnu` | `rift` |
| `rift-<tag>-x86_64-apple-darwin.tar.gz` | `x86_64-apple-darwin` | `rift` |
| `rift-<tag>-aarch64-apple-darwin.tar.gz` | `aarch64-apple-darwin` | `rift` |
| `rift-<tag>-x86_64-pc-windows-msvc.zip` | `x86_64-pc-windows-msvc` | `rift.exe` |

Each release includes `SHA256SUMS` checksums for all archives. Extract the archive and place the executable on your `PATH`.

</Tab>
</Tabs>

<Note>
The npm package name is temporarily `rift-snapshot`. When the `rift` npm name is available, only the launcher package name changes; the prebuild layout and shim behavior stay the same.
</Note>

## Platform support matrix

Rift publishes installable artifacts for four host targets. Workspace copy-on-write behavior depends on the host OS and filesystem, not only on whether installation succeeded.

| Host | Published artifacts | Copy-on-write backend | Workspace behavior after install |
| --- | --- | --- | --- |
| Linux x64 | npm prebuild `linux-x64`, GitHub `x86_64-unknown-linux-gnu` | Writable btrfs subvolumes or native per-file reflinks | `rift init` converts an ordinary btrfs directory into a subvolume, or verifies reflink support and registers in place on other Linux filesystems (including XFS when `FICLONE` succeeds). |
| macOS x64 | npm prebuild `darwin-x64`, GitHub `x86_64-apple-darwin` | APFS `clonefile` | `rift init` registers the source directory. |
| macOS arm64 | npm prebuild `darwin-arm64`, GitHub `aarch64-apple-darwin` | APFS `clonefile` | Same as macOS x64. |
| Windows x64 | npm prebuild `windows-x64`, GitHub `x86_64-pc-windows-msvc` | None implemented | The package installs and the CLI runs, but `create` fails with `cow_unavailable` because no copy-on-write strategy is implemented for Windows. |

<Warning>
Linux arm64 is not in the release or npm prebuild matrix. Although `package.json` lists `arm64` under `cpu`, there is no `prebuilds/linux-arm64/` directory in published packages. Installation on Linux arm64 fails at runtime when the shim cannot locate a binary.
</Warning>

On Linux, the production strategy selects btrfs or reflink backends at runtime based on the workspace filesystem. On macOS, `ApfsStrategy` handles cloning. On other host OS values (including Windows), `UnsupportedStrategy` rejects copy operations.

## npm package layout

The published `rift-snapshot` tarball contains the launcher, conditional FFI entry points, type definitions, and all prebuild directories.

```text
rift-snapshot/
├── bin/rift.js              # CLI shim: spawnSync prebuilt rift
├── bun/index.js             # Bun FFI binding
├── node/index.js            # Node experimental FFI binding
├── index.d.ts
└── prebuilds/
    ├── linux-x64/
    │   ├── rift
    │   └── librift_ffi.so
    ├── darwin-x64/
    │   ├── rift
    │   └── librift_ffi.dylib
    ├── darwin-arm64/
    │   ├── rift
    │   └── librift_ffi.dylib
    └── windows-x64/
        ├── rift.exe
        └── rift_ffi.dll
```

### Platform and architecture resolution

All launchers map `os.platform()` and `os.arch()` to prebuild directory names:

| `os.platform()` | Prebuild prefix | CLI binary | FFI library |
| --- | --- | --- | --- |
| `darwin` | `darwin-<arch>` | `rift` | `librift_ffi.dylib` |
| `linux` | `linux-<arch>` | `rift` | `librift_ffi.so` |
| `win32` | `windows-<arch>` | `rift.exe` | `rift_ffi.dll` |

Only `arm64` and `x64` architectures are accepted. Any other `platform-arch` pair exits the CLI shim with code `1` or throws in FFI bindings.

### Conditional exports

`package.json` routes JavaScript imports by runtime:

| Export condition | Entry | Native artifact |
| --- | --- | --- |
| `bun` | `./bun/index.js` | FFI library via `import` with `{ with: { type: "file" } }` |
| `node` | `./node/index.js` | FFI library via `node:ffi` `dlopen` |
| `default` | `./node/index.js` | Same as `node` |

The npm release workflow builds `rift-cli` and `rift-ffi` for every matrix target, copies both artifacts into the matching `prebuilds/<platform>/` directory with `scripts/prepare-npm-prebuild.mjs`, restores executable bits on Unix targets, and publishes with provenance. Crate and npm versions must match the release tag (currently `0.0.10` for tag `v0.0.10`).

### Constraints

- No `postinstall`, `preinstall`, or other lifecycle scripts. Native code is not compiled on the installing machine.
- `files` in `package.json` limits the published tarball to `bin`, `bun`, `node`, `index.d.ts`, and `prebuilds`.
- `os` and `cpu` fields declare `darwin` / `linux` / `win32` and `arm64` / `x64`, but only the four prebuild directories above are actually shipped.

## Verify installation

<Steps>
<Step title="Confirm the CLI is on PATH">

```bash
which rift
```

For npm/bun global installs, this should resolve to the package `bin/rift.js` symlink. For Cargo installs, expect `${CARGO_HOME:-$HOME/.cargo}/bin/rift`.

</Step>
<Step title="Run the CLI help">

```bash
rift --help
```

A successful install prints Clap help for subcommands (`init`, `create`, `remove`, `list`, `ancestors`, `gc`, `shell-init`). A missing prebuild prints:

```text
Unable to locate the Rift binary for <platform>-<arch>. Reinstall rift-snapshot.
```

and exits with code `1`.

</Step>
<Step title="Optional: verify JavaScript FFI (Node)">

Node requires the experimental FFI API (Node.js 26.1+):

```bash
node --experimental-ffi -e "import('rift-snapshot').then(m => console.log(Object.keys(m)))"
```

With Node's permission model, also pass `--allow-ffi`.

</Step>
</Steps>

## Install failure modes

| Symptom | Cause | Remedy |
| --- | --- | --- |
| `Unsupported Rift platform: <os>-<arch>` | Host outside `darwin`/`linux`/`win32` × `arm64`/`x64` | Use a supported host triple or build from source with Cargo on an unsupported arch (FFI/npm prebuilds still unavailable). |
| `Unable to locate the Rift binary for <platform>-<arch>` | Missing or corrupt prebuild directory (common on Linux arm64) | Reinstall `rift-snapshot`, or install via GitHub Release / Cargo for CLI-only use. |
| `Unable to locate the Rift Node library for <platform>-<arch>` | FFI shared library missing from prebuilds | Reinstall the npm package; verify `prebuilds/<platform>-<arch>/` contains the platform library file. |
| `cow_unavailable` on first `rift create` (Windows) | Windows has no implemented copy-on-write strategy | Expected on Windows x64 today; use Linux or macOS for workspace creation. |
| Version mismatch during release | Tag does not match crate/npm version | Release CI rejects mismatched tags; install only from published `v*` releases. |

## Related pages

<CardGroup>
<Card title="Overview" href="/overview">
What Rift exposes (CLI, npm package, FFI), supported platforms and backends, and the shortest path from init to create.
</Card>
<Card title="Quickstart" href="/quickstart">
Initialize a workspace, create a filtered child, list it, and remove it with expected stdout signals.
</Card>
<Card title="Copy strategies and platforms" href="/copy-strategies">
Platform-specific copy-on-write backends, filtered vs exact copy modes, and unsupported platforms.
</Card>
<Card title="Development" href="/development">
Build and test the Rust workspace, install the CLI locally, and CI test matrix details.
</Card>
<Card title="JavaScript API" href="/javascript-api">
`rift-snapshot` exports, Bun vs Node bindings, and Node.js 26.1+ FFI requirements.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Common failure modes after installation: uninitialized workspaces, CoW unavailable, and platform limitations.
</Card>
</CardGroup>