---
title: The rsva command
summary: How rsva signs in, how its output works in scripts and agents, and every command it has.
---

`rsva` is recursiva from a terminal, for people and for agents. Each command is a thin call of the [agent API](/docs/agents/api): names, keys and refusals come from the server. At a terminal the output is for a person: colour, the window's width, issues grouped by state. In a pipe, a file or an agent it is plain text, or JSON with `--json`. `rsva help` lists every command, and `rsva help <command>` shows one.

## Getting rsva

`rsva` is not published as a package yet: it runs from a clone of the [repository](https://github.com/r3cursiva/recursiva). It needs Node.js 24.11 or newer, and corepack, which installs the pnpm version the repository pins.

```sh
git clone https://github.com/r3cursiva/recursiva.git
cd recursiva
corepack enable
pnpm install
alias rsva="node $PWD/apps/cli/bin/rsva.js"   # put this line in your shell's profile to keep it
rsva help
```

The same clone holds the terminal app: [`rsva tui`](/docs/terminal/tui) works as soon as `rsva` does.

### Your first commands

Make a token in **Settings › API tokens**, then:

```sh
export RSVA_TOKEN=rsva_…          # the token, shown once
rsva workspace show               # the workspace and whose token this is
rsva issues
rsva create "Try rsva" -p ABC     # ABC: one of your projects' keys
rsva tui
```

`RSVA_TOKEN` in the environment is the quickest way to start; [Signing in](#signing-in) below keeps the token in the Keychain instead.

### Your own server

`rsva` talks to https://app.rsva.dev. For a recursiva you run yourself ([self-hosting](https://github.com/r3cursiva/recursiva/blob/main/SELF_HOSTING.md)), set its address first:

```sh
export RSVA_URL=http://localhost:3800
```

## Signing in

The commands run with an API token. Make one in **Settings › API tokens** (see [Agents](/docs/agents/agents)). A token belongs to one workspace, and `rsva` uses that workspace unless `RSVA_WS` names another.

`rsva` looks for the token in this order:

1. `RSVA_TOKEN` in the environment.
2. On macOS, the Keychain, under the service `RSVA_KEYCHAIN` names. The default service is `rsva-bot`, the one meant for the agents' token.

To keep your own token in the Keychain, store it under a service of your own and point `RSVA_KEYCHAIN` at it. With `-w` last, `security` asks for the token, so it never appears on the command line:

```sh
security add-generic-password -s rsva-own -a me -w
export RSVA_KEYCHAIN=rsva-own
rsva workspace show
```

`rsva workspace show` names the workspace and whose token this is: its person, role and what it may change. On other systems there is no Keychain: set `RSVA_TOKEN`.

The server address must be `https`, except on `localhost`.

### rsva login

`rsva login` signs this Mac's terminal in as you, for [`rsva tui`](/docs/terminal/tui) only. The other commands keep using the token.

```sh
rsva login
```

It opens **Settings › Security** in the browser. Choose **Sign in a terminal** and paste the code it shows. The code works once, for 5 minutes. Without a terminal, `rsva login` reads the code from stdin. The session is kept in the Keychain under the service `rsva-session`, so `rsva login` works on macOS only. Signing in again ends the previous terminal session.

`rsva logout` ends the session on the server and here, and deletes the copies of your workspaces that `rsva tui` kept with it.

## Environment variables

| Variable | What it sets |
| --- | --- |
| `RSVA_URL` | The server. Default `https://app.rsva.dev`. |
| `RSVA_WS` | The workspace's slug. Default: the token's own workspace, asked of the server once a run. Setting it saves that request. |
| `RSVA_PROJECT` | The project when `-p` is left out. `rsva my` and `rsva update` do not read it. |
| `RSVA_TOKEN` | The token. Without it, the macOS Keychain. |
| `RSVA_KEYCHAIN` | The Keychain service the token is read from. Default `rsva-bot`. |
| `RSVA_PAGER` | The pager for a person's long output. Default `$PAGER`, else `less`. `cat` or empty: no pager. |
| `RSVA_SESSION` | For `rsva tui`: your session, instead of the one `rsva login` keeps. |
| `RSVA_OWN_KEYCHAIN` | For `rsva tui` without `rsva login`: the Keychain service of your own token. Default `rsva-own`. |
| `RSVA_TUI_IMAGES` | For `rsva tui`: `1` draws images, `0` shows their captions. |
| `RSVA_AGENT` | For dispatch: the email of the agent issues are delegated to. |
| `NO_COLOR` | Plain text at a terminal too. |
| `FORCE_COLOR` | Colour into a pipe. |

`rsva my` lists the open issues of the token's person, in every project. With the agents' token, that person is the agent.

## Output for scripts and agents

Who reads the output decides its form:

- At a terminal, the output is for a person: colour, lines cut to the window, lists grouped by state, keys that open the issue. Output taller than the window goes through the pager.
- In a pipe or a file, it is plain text: one line per thing, the fewest bytes that say it.
- When `CLAUDECODE` is set, the output is plain even in a terminal: an agent pays for every byte.
- `--plain` and `--color` choose for one command. `NO_COLOR` and `TERM=dumb` turn colour off; `FORCE_COLOR` turns it on in a pipe.

`--json` prints the server's answer. It is one line in plain output and indented for a person. Every command that asks the server takes `--json`; `cycle show` gives both of its answers as `{cycle, issues}`. Commands with no answer of the server (`open`, `edit`, `tui`, `login`, `logout`, `completion`, `help`) refuse it. `rsva api` always prints JSON.

`rsva create` prints the new issue's key alone on stdout, so a script can read it. Open issues that look like the new one go to stderr.

A few rules hold for every command:

- `none` clears a field: `--cycle none`, `--due none`. `--label none` and `--assignee none` empty the list.
- `-` reads text from stdin: `-d -` for a description, `rsva comment KEY -` for a comment.
- After `--` every word is an argument: `rsva comment KEY -- -x`.
- An unknown flag is refused, not sent as text.
- A GET the server is too busy for is asked once more after its wait, if the wait is 5 seconds or less.

Exit codes: `0` done, `1` a refusal by the server or a failure on the way, `2` a mistake in the call.

```sh
key=$(rsva create "Fix the login redirect" -p ABC --priority high)
rsva issues label:bug --json | jq '.issues[].key'
git log -1 --format=%B | rsva comment "$key" -
```

## Issues

| Command | What it does |
| --- | --- |
| `rsva issues [query...]` | List issues. The query is the language of the app's `/` field ([Query language](/docs/finding/query)). Flags: `-p KEY`, `--view NAME`, `--order FIELD`, `--limit N`. 500 at most. |
| `rsva my [query...]` | Open issues assigned to the token's person, every project. A query narrows it. Flags: `-p KEY`, `--order FIELD`, `--limit N`. |
| `rsva show KEY` | One issue with its description and the newest page of its comments. Says when the issue is deleted or archived. |
| `rsva open KEY` | The issue in the browser. Where nothing can open it, prints its address. |
| `rsva edit KEY` | The description in `$VISUAL` or `$EDITOR`. Saved when it changed; refused if it changed on the server meanwhile, and your text stays in the file. |
| `rsva create TITLE` | A new issue. Takes `-p KEY` and the issue flags below. A strong match with an open issue refuses it unless `--force`. |
| `rsva update KEY...` | Change the fields given, on one issue or many. `--label` and `--assignee` replace the list; `--add-label`, `--remove-label`, `--add-assignee` and `--remove-assignee` change each issue's own. `--title` renames. `-p KEY` moves one issue to that project. |
| `rsva move KEY... --to KEY` | Move issues to another project, keeping history, comments, links and pull requests. Each gets the next number there; its old key still finds it. State and labels go by name; the cycle is cleared. `--sub-issues` takes their sub-issues too. |
| `rsva archive KEY` | To the archive. Only finished or cancelled issues. |
| `rsva delete KEY` | To the project's trash. |
| `rsva restore KEY` | Out of the trash. |

The issue flags of `create` and `update`:

- `-s STATE`, `--priority P` (`urgent`, `high`, `medium`, `low`, `none`)
- `--label L` and `--assignee A`, each as many times as needed; people by email
- `--delegate A`, `--parent KEY`, `--cycle C`
- `--start DATE`, `--due DATE`
- `-d TEXT`, or `-d -` for stdin

`--order` takes `updatedAt`, `createdAt`, `priority`, `dueDate`, `startDate` or `manual`.

```sh
rsva issues 'state:"In Review" -label:security' -p ABC
rsva update ABC-12 ABC-14 --add-label bug --priority high
rsva move ABC-12 --to XYZ --sub-issues
```

## Comments

| Command | What it does |
| --- | --- |
| `rsva comments KEY` | The newest page of comments, a reply under its comment. The last line says how to read the page before (`--until`). |
| `rsva comment KEY TEXT` | Add a comment in Markdown. `-` reads it from stdin. `--reply-to ID` answers a comment; `--edit ID` replaces your own. |
| `rsva uncomment KEY ID` | Delete your own comment. Its replies stay. |

`ID` is the short handle `rsva comments` shows, or the comment's full id.

## Links, files and relations

| Command | What it does |
| --- | --- |
| `rsva link KEY URL` | Attach a link. A GitHub pull request or commit is recognised. `--title T` names it. |
| `rsva unlink KEY URL` | Remove a link, by its address as `show` prints it, or by its id. |
| `rsva attach KEY FILE` | Upload a file, 25 MiB at most, and attach it. `--name N` is the name it shows. |
| `rsva detach KEY NAME` | Remove a file, by its name as `show` prints it, or by its id. |
| `rsva relate KEY TYPE OTHER` | Link two issues. `TYPE` is `blockedBy`, `blocks`, `related`, `duplicateOf` or `duplicates`. |
| `rsva unrelate KEY OTHER` | Remove the link between two issues. |

## Cycles

A cycle is named by its short name, such as `C12`, or by its name. Each takes `-p KEY`.

| Command | What it does |
| --- | --- |
| `rsva cycles` | A project's cycles in time order. |
| `rsva cycle show CYCLE` | A cycle and its issues, 500 at most. |
| `rsva cycle create NAME` | A new cycle. `--start` and `--end` set its dates; without dates it is a draft. `--lead A`, `-d TEXT`. |
| `rsva cycle update CYCLE` | Change the fields given: `--name`, `--start`, `--end`, `--lead`, `-d`. `none` clears one. |
| `rsva cycle complete CYCLE --move-to TARGET` | Complete it and move its open issues to another cycle, to `next` or to `none`. `--keep KEY` leaves an issue in the completed cycle. |
| `rsva cycle delete CYCLE` | Take its issues out and delete it. A completed cycle is kept. |

## Projects, states and labels

Any token can read these. Changing them needs an admin's token, or a member's or an agent's where an admin opened that kind to members in Settings › Members (labels are open by default); see [Agents](/docs/agents/agents).

| Command | What it does |
| --- | --- |
| `rsva projects` | The workspace's projects, archived ones too. |
| `rsva project show KEY` | A project with its states and labels. |
| `rsva project create KEY NAME` | A new project with the default workflow: Backlog, Todo, In Progress, Done, Cancelled. `--hue C` is its color. |
| `rsva project update KEY` | Change `--key`, `--name`, `--hue` or `--rollover on` / `off`. The old key stays an alias. With rollover on, a cycle that is over completes itself and its open issues move to the next. |
| `rsva project archive KEY` | To the archive. `project unarchive` brings it back. |
| `rsva states` | A project's workflow states in the app's order. |
| `rsva state create NAME --group G` | A new state in a group: `backlog`, `unstarted`, `started`, `completed` or `cancelled`. Last in its group unless placed with `--before S` or `--after S`. |
| `rsva state update STATE` | Change `--name`, `--group`, its place, or make it the project's default with `--default`. |
| `rsva state delete STATE` | Delete it. `--move-to S` moves its issues first, archived ones too. |
| `rsva labels` | The labels a project's issues can use, as a tree. |
| `rsva label create NAME` | A new label. `--hue` is `#rrggbb` or one of the app's colors by name. `--parent L` puts it inside another. |
| `rsva label update LABEL` | Change `--name`, `--hue` or `--parent`. `--parent none` takes it to the top level. |
| `rsva label delete LABEL` | Take it off every issue and delete it. The labels inside it move up a level. |

## Members, views and the workspace

| Command | What it does |
| --- | --- |
| `rsva members` | The workspace's people and agents, by role: the emails `--assignee` and mentions take. |
| `rsva views` | The saved views you see, shared and your own: the names `--view` takes. |
| `rsva workspace show` | The workspace, and whose token this is: its person, role, scope and what it may change. |
| `rsva workspace update` | Change `--name` or `--hue`. Needs an admin's token. |

## Inbox

`rsva inbox` lists the token's person's notifications, newest first. `--all` lists the snoozed ones too.

```sh
rsva inbox
rsva inbox read ABC-12 ABC-14
rsva inbox archive --all
```

`read`, `unread` and `archive` take issue keys, or `--all`.

## Any API call

`rsva api METHOD PATH` makes any call of the agent API and prints the answer as JSON. The path is under `/api/v1/workspaces/<workspace>`. A `name=value` argument goes into the query; a JSON argument is the request body, and `-` reads it from stdin.

```sh
rsva api GET /issues/ABC-12
rsva api GET /issues q=label:bug limit=5
rsva api PATCH /issues/ABC-12 '{"priority": "high"}'
```

See [The agent API](/docs/agents/api) for the paths.

## Other commands

| Command | What it does |
| --- | --- |
| `rsva tui` | The app in the terminal. See [The terminal app](/docs/terminal/tui) and [Dispatch an agent](/docs/terminal/dispatch). |
| `rsva login`, `rsva logout` | Sign this terminal in as you for `rsva tui`, or out. |
| `rsva completion zsh` | A zsh completion script: `source <(rsva completion zsh)`, or save it as `_rsva` in `$fpath`. Only zsh so far. |
| `rsva help [command]` | Every command, or one. |
