docs~/terminal/cli.md
/esc
~/terminal/cli.md
terminal/cli.md · 12 min · updated 2026-11-15 · as markdown

# The rsva command

rsva is recursiva from a terminal, for people and for agents. Each command is a thin call of the agent 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. 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 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 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), 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). 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 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). 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.

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.

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 for the paths.

Other commands

Command What it does
rsva tui The app in the terminal. See The terminal app and Dispatch an agent.
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.