# Oak CLI

`oak` is the command-line client for [Oak](https://oakvcs.com) — version
control for you and your agents. It is a purpose-built VCS designed for
agent workflows: branch-per-session, content-addressed storage,
large-file support, and lazy mounts.

This repository contains the **client** side of Oak: the `oak` binary and
the local crates it builds on. The hosted server and web UI are not part
of this repository.

## Structure

This repository **is** the `oak-cli` package — the repo root is the crate
that defines the `oak` binary. It has a single dependency of note:

| Crate                        | Description                                                                 |
| ---------------------------- | --------------------------------------------------------------------------- |
| `oak-cli` (this repo's root) | The `oak` command-line application (clap-based). Defines the `oak` binary.  |
| [`oak-core`](https://crates.io/crates/oak-core) (external) | Core VCS logic **and** the client-side local repository: BLAKE3 hashing, content-defined chunking, diff/merge, the `Blob`/`Manifest`/`Commit`/`Tree` data model, and the `Repository` trait with its local SQLite + read-only git backends. Published on crates.io and shared with the Oak server. |

`oak-core` is consumed from crates.io. The storage it provides is
**client-only** — it depends on neither `sqlx` nor any server data model.
Oak's server-side async/PostgreSQL storage lives in a separate, private tree.

> **Building before `oak-core` is published:** the root `Cargo.toml` carries
> a `[patch.crates-io]` entry pointing `oak-core` at a sibling `../oak-core`
> checkout so the CLI builds locally today. Once `oak-core` is live on
> crates.io, delete that patch section.

## Installing

Requires a Rust toolchain (see [`rust-toolchain.toml`](rust-toolchain.toml)).

```bash
cargo install --path .             # build and install the `oak` binary to ~/.cargo/bin
make install                       # same, but with the `mount` feature on macOS/Linux
```

Or just build it without installing:

```bash
cargo build --release              # release binary at target/release/oak
cargo test                         # run the test suite
```

### Lazy mounts (`--features mount`)

`oak mount` exposes a remote repository as a virtual filesystem, hydrating
files on demand. It is **off by default** and enabled with the `mount`
feature, which selects a platform-native backend at compile time:

```bash
cargo install --path . --features mount
```

- **macOS** — FUSE via [macFUSE](https://macfuse.github.io)
  (`brew install pkgconf macfuse`) or fuse-t. Links `libfuse`, which is why
  `mount` is never baked into the default distributed mac binary.
- **Linux** — FUSE via the `fusermount3` helper from the `fuse3` package
  (no `libfuse` link). Needs `/dev/fuse`.
- **Windows** — [ProjFS](https://learn.microsoft.com/windows/win32/projfs/projected-file-system).
  Enable the optional feature once per machine:
  ```powershell
  Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS -NoRestart
  ```

## Default server

`oak` talks to [oakvcs.com](https://oakvcs.com) by default. Point it at a
different server with `oak login -r <url>` or the `-r/--remote` flag on the
sync commands.

## Getting started

```bash
oak init                 # initialize a repository in the current directory
oak commit               # record a snapshot
oak push --repo <org>/<name>   # publish your branch to the server
```

Run `oak --help` for the full command list, or `oak <command> --help` for
details on any command. Docs live at <https://oakvcs.com/docs>.

## License

Licensed under the [Apache License, Version 2.0](LICENSE).
