> Documentation index: https://rift.sh/llms.txt

# For agents

This page is written for an agent that has been asked to use Rift. It is the procedure in order.

## Reading these docs

Every page is available as Markdown at the same address with `.md` added. [/llms.txt](https://rift.sh/llms.txt) lists every page, and [/llms-full.txt](https://rift.sh/llms-full.txt) holds the docs in one file.

[/setup.md](https://rift.sh/setup.md) is this procedure written as steps for an agent to follow, with the point at which to stop and ask. It covers the setup steps of the [prompt](https://rift.sh/index.md#agent) on the home page, and adds the verify step, the skill and a report.

[/skill.md](https://rift.sh/skill.md) is the Rift skill, with the commands and the mistakes to avoid.

## Install and join

Run `rift status` first and read its first line.

If it says `joined as`, this machine already joined with an invite. Do not run `rift init` and do not use a token. If you were given one, tell the person it was not used and which name this machine joined as. Then go on to Work in a shared folder.

If it shows a key that starts `ed25519:` and no `joined as`, the machine's owner set it up and you are working with their key. With no token, go on to Work in a shared folder.

If it shows a key and you have a token and a directory from the person, run `rift init --invite <token> --home <dir>`, add `--home <dir>` to every `rift` command, and go on to Work in a shared folder. The folder to use is the one `rift status --home <dir>` prints, in place of `~/rift`.

If it shows a key and you have a token and no directory, stop and 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 above. If they tell you to keep working with their key, do not use the token, and go on to Work in a shared folder.

If the command is not found, run `~/.local/bin/rift status`. If it answers, read its first line by the rules above and call the binary by that path from here on. If it is not found there either, install Rift and then join.

If Rift is found and prints no folder, skip the install and join with an invite token. Use `RIFT_INVITE` if it is set. If you have no token, stop and ask the person you work for to run `rift invite <name>` and send you the token it prints. Run `rift init --invite <token>` once.

```
$ curl -fsSL https://rift.sh/install | sh
✓ installed rift 0.1.0 to ~/.local/bin
$ rift init --invite <token>
✓ created a key for this machine
  ed25519:a1b2c3d4…f0a1b2
✓ joined as coder
✓ folder at ~/rift
```

## Work in a shared folder

Keep your work inside a folder that `rift ls` lists. Those are the folders shared with you. Everything in them is an ordinary file, so read and write it with the tools you already use. Files you write there reach the person's machines without any further command.

A folder it lists as `work/` is at `~/rift/work`. 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.

## Ask for a folder you cannot see

Say which folder and why. A request asks for read access. The person approves or declines from any of their machines.

```
$ rift request work --reason "To re-run the tests with your fix"
✓ asked for work · waiting for approval
```

When the person approves, the folder appears in `rift ls`. 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 the folder.

## Get a file from another agent

```
$ rift ask hermes "the latest report"
✓ received report.pdf from hermes
```

The file arrives in a folder that is shared with you. Run `rift ls` to find it.

## Check that you are in sync

```
# is this machine joined and in sync
$ rift status
✓ joined as coder · in sync
  folder at ~/rift
# what you can see
$ rift ls
work/
```

If a command fails, read its message and report it as it is. Do not delete Rift's folder or its key to start again, because that removes this machine's identity.

## Install the skill

An agent that supports Agent Skills installs the Rift skill with one command. Ask the person before you install it.

```
$ npx -y skills add https://rift.sh -g -y
```

This step needs Node. On a machine that has none, read the skill once in its place.