# Overview
> What Rift exposes (CLI, npm package, FFI), supported platforms and backends, and the shortest path from init to create.
- 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`
- `specs.md`
- `Cargo.toml`
- `crates/core/src/lib.rs`
- `npm/rift-snapshot/package.json`
---
---
title: "Overview"
description: "What Rift exposes (CLI, npm package, FFI), supported platforms and backends, and the shortest path from init to create."
---
Rift is a Rust workspace (`rift` core, `rift-cli`, `rift-ffi`) that registers source directories as managed workspaces, clones them with platform copy-on-write backends, and tracks parent-child provenance in a central SQLite registry. Consumers reach the same semantics through the `rift` CLI binary, the `rift-snapshot` npm package (CLI shim plus Bun/Node FFI bindings), or direct use of the `rift` Rust crate.
This repository is experimental. Behavior, interfaces, and implementation details may change without notice.
## What Rift provides
Rift replaces heavyweight full-directory copies (and complements Git worktrees) with instant, space-efficient workspace clones. A registered source workspace gets a `.rift` marker and a ULID identity in SQLite; each `create` operation produces a filtered or exact copy-on-write child, records the immediate parent, and optionally runs `.rift.toml` postcreate hooks.
Four interfaces share one implementation and metadata model:
| Interface | Artifact | Role |
| --------- | -------- | ---- |
| Native library | `rift` crate (`crates/core`) | Core API: `Manager`, `init`, `create`, `remove`, `list`, `ancestors`, `gc` |
| CLI | `rift` executable (`crates/cli`) | Shell commands, Git-root/`--here` selection, progress output, shell integration |
| Bun FFI | `rift-snapshot` → `bun/index.js` | `dlopen` of `librift_ffi` / `rift_ffi.dll`; JSON request protocol |
| Node FFI | `rift-snapshot` → `node/index.js` | Node 26.1+ experimental `node:ffi`; same JSON protocol |
The npm launcher publishes as **`rift-snapshot`** (version `0.0.10` at time of writing). It installs a `rift` bin shim that spawns a bundled prebuilt executable from `prebuilds/-/`. Conditional exports route `import "rift-snapshot"` to the Bun or Node binding. No install lifecycle scripts are required.
```text
Application / shell npm rift-snapshot
| |
v v
rift CLI (clap) bin/rift.js → prebuilds/.../rift
| |
+----------+ JSON FFI +------+------+
| rift_ffi_call | |
v v v
rift-ffi (cdylib) bun/index.js node/index.js
|
v
rift core (Manager)
|
+---------+---------+
| | |
Strategy SQLite .rift markers
(CoW copy) registry (ULID per workspace)
```
## Platform and backend support
Prebuilt npm artifacts target four platform-arch pairs: `linux-x64`, `darwin-x64`, `darwin-arm64`, and `windows-x64`. Workspace **creation** requires a production copy-on-write strategy on the host OS and filesystem.
| Platform | Backend | `init` behavior | `create` behavior |
| -------- | ------- | ----------------- | ----------------- |
| Linux x64 on btrfs | `BtrfsStrategy` | Converts ordinary directories into btrfs subvolumes via reflink import; registers existing subvolumes in place | Exact: writable subvolume snapshots; filtered: reflink import of included paths |
| Linux x64 on reflink-capable FS (e.g. XFS) | `LinuxReflinkStrategy` | Verifies native reflink (`FICLONE`) support; registers in place | Per-file reflink tree clone |
| macOS arm64 / x64 (APFS) | `ApfsStrategy` | Registers source directory | Exact: `clonefile` directory clone; filtered: per-entry clone |
| Windows x64 | `UnsupportedStrategy` | Package publishes; CoW cloning not implemented | Fails with `cow_unavailable` |
Linux selects btrfs vs reflink at runtime via `statfs` magic detection. macOS always uses `ApfsStrategy`. Other platforms compile `UnsupportedStrategy`, which rejects `create` with no byte-copy fallback.
On btrfs, `create` requires the source to already be a subvolume. If `from` is an ordinary btrfs directory, run `rift init` first.
## Shortest path: init to create
The minimal CLI workflow registers a source workspace, then clones it. Defaults use the current working directory, filtered copy (excluding regenerable artifacts like `node_modules` and `target`), and adjacent `.rifts//` storage.
```bash title="npm"
npm install -g rift-snapshot
```
```bash title="bun"
bun add -g rift-snapshot
```
```bash title="Cargo (from source)"
./scripts/install.sh
```
The Cargo script installs an optimized `rift` binary to `${CARGO_HOME:-$HOME/.cargo}/bin/rift`. Release archives are also published on [GitHub Releases](https://github.com/anomalyco/rift/releases/latest).
```bash
cd ~/code/app
rift init
```
`rift init` walks upward from the current directory. Unless `--here` is passed, it selects the nearest existing managed ancestor, or the nearest Git root when no Rift root exists. Core `init` then registers the directory, writes a `.rift` marker (ULID), and on Linux btrfs may convert an ordinary directory into a subvolume.
**Success signals (stderr unless noted):**
- First-time btrfs conversion: progress lines (`Creating BTRFS subvolume...`, `Importing workspace...`), then `Ready `
- Already registered: `Already initialized `
- Restored deleted marker: `Restored marker `
```bash
rift create
# or
rift create --name parser-fix
```
`rift create` resolves upward to the nearest `.rift` marker, copy-on-write clones the managed workspace, inserts a registry child record, prepares Git state (detached `HEAD` when applicable), and prints the **new workspace path to stdout**.
```text
/home/you/code/.rifts/app/parser-fix
```
Filtered copy omits heavyweight dependency and build artifacts while preserving manifests, lockfiles, and dirty working-tree state. Use `--copy-all` for exact copies including `node_modules`, `target`, and similar paths.
```bash
rift list # direct children of current workspace
rift ancestors # parent chain, nearest first
rift remove # move current created rift to .trash
rift gc # physically delete trashed workspaces
```
## JavaScript API surface
The `rift-snapshot` package exposes the same operations as the CLI core, with path defaults to `process.cwd()`:
```ts
import { init, create, list, remove, gc } from "rift-snapshot";
init({ at: "/path/to/app" });
const child = create({ from: "/path/to/app", name: "schema-work" });
console.log(list({ of: "/path/to/app" }));
remove({ at: child });
gc();
```
Initializes exactly `at`. Git-root selection and `--here` are CLI-only behavior.
Returns the new workspace path. `copyAll` and `hooks` default to filtered copy and running postcreate hooks.
Failures throw `RiftError` with a `code` (e.g. `cow_unavailable`, `workspace_not_initialized`, `hook_failed`) and optional `path`.
Conditional export `bun` loads `librift_ffi` via `bun:ffi` `dlopen`. No extra runtime flags.
Requires Node.js **26.1+** with the experimental FFI API:
```bash
node --experimental-ffi app.mjs
```
With Node's permission model, also pass `--allow-ffi`.
## Registry and storage at a glance
Every managed workspace has a `.rift` file at its root containing its ULID. A central SQLite database at the platform user data directory (`/rift/rift.sqlite`) stores `id`, `parent_id`, `path`, and trash records. Workspace operations locate their root by searching upward for `.rift`.
Default child storage sits beside the registered source root:
```text
~/code/app/ source workspace
~/code/.rifts/app/parser-fix/ created workspace
~/code/.rifts/app/.trash/ removed workspace storage
```
Custom destinations use `rift create --into` or the `into` API field.
## CLI command inventory
| Command | Purpose |
| ------- | ------- |
| `rift init` | Register (and possibly convert) a source workspace |
| `rift create` | Copy-on-write clone with optional `--name`, `--into`, `--copy-all`, `--no-hooks` |
| `rift list` | List direct child workspaces |
| `rift ancestors` | List parent workspaces, nearest first |
| `rift remove` | Trash a created rift, or unregister a source root with `-f` |
| `rift remove --children` | Trash descendants while preserving the selected workspace |
| `rift gc` | Physically delete trashed workspaces and prune missing registry entries |
| `rift shell-init ` | Emit shell wrapper for auto-`cd` after init/create/remove |
Hidden global flags `--database` and `--shell-cwd` support testing and shell integration.
## Related pages
Install via npm, bun, Cargo, or GitHub release archives; prebuilt binary layout.
End-to-end init, create, list, and remove with expected stdout signals.
Btrfs subvolumes, Linux reflinks, APFS clonefile, filtered vs exact modes.
FFI request protocol, exports, and Node.js 26.1+ requirements.
All subcommands, flags, defaults, and exit behavior.