Rift

A git-style versioned file store for humans and AI agents. Spaces hold branches of files. You commit, pull, merge and revert them, and every person and agent holds its own key.

Agents: the instructions written for you are at /llm.md. API health: /v1/health.

Install the CLI

You need Node.js 20 or newer. The installer checks the download's SHA-256 checksum before it writes anything, then puts rift in ~/.local/bin.

curl -fsSL https://api.rift.gripe/install.sh | sh
rift --version

If ~/.local/bin is not on your PATH, add it: export PATH="$HOME/.local/bin:$PATH".

Sign in

Run rift login. It opens your browser, which mails you a sign-in link. Click the link and the CLI receives a one-time code. The browser then remembers you for 30 days, so later logins need no email. Your address must hold an access grant (to create spaces) or a membership (to join one). Your administrator sets that up.

rift login --email you@example.com

Create a space

A space is a workspace of files. You become its admin when you create it. Creating a space needs a creator grant, which an administrator gives you with rift access grant.

rift space create acme-lab
rift space list

Add people

rift members add rae@example.com --role read
rift members list
rift members set-role rae@example.com --role write
rift members remove rae@example.com

Only a space admin changes members. The last admin cannot be demoted.

Give an agent a key

rift agent create --space acme-lab --name research-bot --role write --expires-in 30d
rift agent list --space acme-lab
rift key revoke <key-id> --space acme-lab

The key is shown once. On the agent's machine, store it with rift agent login --space acme-lab --key-file. Agent keys last 1 day by default and at most 30 days. An agent works only under agent/<name>/ branches. It never holds the admin role.

Work with files

Clone a branch to your disk

rift clone acme-lab/main notes
cd notes
rift checkout -b my-topic        # your own branch, made at the last commit you synced
# edit files
rift status                      # A/M/D against the last sync
rift diff
rift push -m "add findings"      # upload changes and commit
rift pull                        # merge the branch into your copy
rift log

push is refused if someone changed a file on the branch since your last pull. pull merges each file as a whole. A file changed on both sides gets conflict markers, and push waits until you run rift resolve <path>.

Or work without a clone

rift use my-topic                # bare paths mean this branch
rift ls -r docs
rift cat main:README.md          # read main without switching
rift put report.md docs/report.md --create-only
rift edit docs/report.md --old draft --new final
rift commit my-topic -m "tidy docs"

Branches and merges

rift branch create my-topic --from main
rift branch list
rift merge my-topic main -m "combine"     # into main: admins only
rift revert <commit> --branch my-topic

A merge that would delete files is refused until you add --allow-deletes. Conflicts are listed, and nothing is half-merged.

Roles

RoleCan
readlist, find, grep, cat, get, stat, log, diff, clone, pull
writeupload, edit, delete, commit, branch create and delete, merge and revert on branches other than main. Agents create and delete branches only under agent/<name>/
adminhumans only. Writes to main (commit and merge), manages members and keys, and deletes any unprotected branch

main is protected. Nobody deletes it, and only a human admin writes to it.

Command reference

Run rift help for every command, or rift <command> --help for one. Exit code 0 is success, 2 is a usage error, and 1 is any other failure.

For AI agents, the same information is in /llm.md, written so an agent can follow it directly.