---
name: rift
description: Rift is an encrypted filesystem for agents, run from the `rift` command. Use when the user asks you to install or join Rift, to keep your work in a Rift folder, to share a folder with a machine or another agent, to request access to a folder, or to get a file from another agent, or when they mention `rift` commands or the `~/rift` folder.
compatibility: "macOS and Linux. Needs a shell and a home directory you can write to."
allowed-tools: Bash
metadata:
  homepage: https://rift.sh
  docs: https://rift.sh/llms.txt
---

# Rift

Rift is a filesystem for agents. Files you write in a Rift folder appear on every machine that was given access to that folder, encrypted end to end. `rift <command> --help` is the source of truth for flags.

## Quick setup

1. Check whether Rift is already here: `rift status`, and read its first line.
   - `joined as <name>`: this machine already joined with an invite. Do not run `rift init` and do not use a token. If you were given a token, tell the person it was not used and which name this machine joined as. Skip to step 4.
   - A key that starts `ed25519:` and no `joined as`: the machine's owner set it up, and you are working with their key.
     - No token: skip to step 4.
     - A token and a directory from the person: run `rift init --invite <token> --home <dir>`, add `--home <dir>` to every `rift` command, and skip to step 4.
     - A token and no directory: stop. Tell the person that this machine already uses their key, that you can see every folder in `~/rift`, and that the token is unused. If they give you a directory, do as in the line above. If they tell you to keep working with their key, do not use the token, and skip to step 4.
   - Command not found: run `~/.local/bin/rift status`. If it prints a first line, read it by this list and call the binary by its full path from here on. If that is not found either, go on to step 2.
   - Found, and no folder printed: go to step 3.
2. Install: `curl -fsSL https://rift.sh/install | sh`. It installs to `~/.local/bin`. If that directory is not on your `PATH`, call the binary by its full path.
3. Join. You need an invite token from the person you work for. If the environment variable `RIFT_INVITE` is set, use it. If you have no token, stop and show them this text:

   ```
   To add me to your Rift filesystem, run this on your own machine and send me the token it prints:
   rift invite <a name for me>
   ```

   Then run `rift init --invite <token>`. It creates a key for this machine and prints Rift's folder, usually `~/rift`.
4. Verify: `rift status`. It passes when it prints Rift's folder:

   ```
   ✓ joined as <your name> · in sync
     folder at ~/rift
   ```

   On a machine its owner set up, the first line shows the key in place of `joined as`. That also passes.

   If it does not, report the message as it is and stop.

## Working with Rift

- Keep your work inside a folder that `rift ls` lists. Those are the folders shared with you, and files you write in them reach the person's machines without any further command.
- Everything in them is an ordinary file. Read and write it with the tools you already use. Writing a file is enough, so you never need `rift add`.
- A folder that `rift ls` lists as `work/` is at `~/rift/work`. If you joined with `--home <dir>`, use the folder that `rift status --home <dir>` prints in place of `~/rift`.
- A folder you make yourself under `~/rift` stays private to this machine. If `rift ls` lists no folder, ask the person which folder to use.
- You see only the folders that were shared with you. That is expected.

## Choosing the right command

| You want to | Run |
| --- | --- |
| See whether this machine is joined and in sync | `rift status` |
| See which folders and files you can reach | `rift ls [path]` |
| Ask for a folder you cannot see | `rift request <path> --reason "<why>"` |
| Get a file from another agent | `rift ask <agent> "<what you need>"` |
| Share a folder you can administer | `rift share <path> <name>` gives write. Add `--read` for read only. |
| Remove access | `rift unshare <path> <name>` |
| Read output in a script | add `--json` to any command |

A file from `rift ask` arrives in a folder shared with you. Run `rift ls` to find it.

## Keys and access

- `rift init` creates this machine's private key. Never print it, copy it, commit it or send it anywhere. The public key, which starts with `ed25519:`, is safe to show.
- Do not delete Rift's key or its folder to start again. That removes this machine's identity, and every folder shared with it stops arriving.
- An invite token lets a machine join under one name. Treat it as a secret. Do not store it in a file that syncs or in a repository.
- If you need a folder you cannot see, use `rift request`. It asks for read access. When the person approves, the folder appears in `rift ls`.
- After you ask, tell the person you asked, carry on with work that does not need the folder, and check `rift ls` again before you use it. If nothing is left that you can do without it, stop and tell the person what you asked for. Do not look for another way to reach it.
- Share a folder or remove access only when the person asks you to.

## Common mistakes

- Writing output outside a shared folder and expecting it to reach the person. Only files in a folder shared with you reach them.
- Running `rift init` again with a different invite to "fix" something. Run `rift status` and report what it says.
- Treating a missing folder as an error. You were not given it. Request it.
- Putting a `.git` directory inside a Rift folder. Keep the repository itself outside `~/rift`.

## Docs

- Index of every page: https://rift.sh/llms.txt
- Setup, step by step: https://rift.sh/setup.md
- For agents: https://rift.sh/docs/agents.md
- Commands: https://rift.sh/docs/commands.md
- Sharing: https://rift.sh/docs/sharing.md