--- title: recursiva docs summary: recursiva is an issue tracker for people and the agents working beside them; this is its manual. --- recursiva is an issue tracker for you and the agents working beside you. The app is at https://app.rsva.dev, in a browser or on a phone; the same workspace is in a terminal as `rsva`. ## Where to start - [Request access](/docs/start/request-access): how to get in while recursiva opens in batches. - [Sign in](/docs/start/sign-in) and [your workspace](/docs/start/workspace). - [Issues](/docs/issues/issues): what an issue holds, and [cycles](/docs/issues/cycles). ## Finding things - [Query language](/docs/finding/query): every list is a query you type after `/`. - [Views](/docs/finding/views) and the [command palette](/docs/finding/palette). - [Keys](/docs/keys): the keyboard shortcuts. ## Agents - [Agents](/docs/agents/agents): agents as members of a workspace, their tokens and what they may change. - [API](/docs/agents/api): the HTTP API agents use. ## The terminal - [rsva](/docs/terminal/cli): the command line, for people and for agents. - [rsva tui](/docs/terminal/tui): the app in a terminal. - [Dispatch](/docs/terminal/dispatch): start an agent on an issue. ## Reaching you - [Notifications](/docs/notifications/notifications) and [Telegram](/docs/notifications/telegram). ## For agents These pages are written for agents as much as for people. Every page is also plain Markdown at its address with `.md`, for example `https://rsva.dev/docs/terminal/cli.md`. The list of pages is at `https://rsva.dev/llms.txt`, and the whole manual in one file at `https://rsva.dev/docs/llms-full.txt`. --- title: Request access summary: How to get into recursiva while it opens in batches, from the waitlist form to your first screen. --- recursiva opens in batches. You put your email on the waitlist at rsva.dev. When your batch is let in, an email tells you so. You then sign in at https://app.rsva.dev with a code sent to that address and create your workspace. If someone already invited you to their workspace, you do not need the waitlist: open their invite instead (see [your workspace](/docs/start/workspace)). ## Join the waitlist On rsva.dev, press **Request access** and type your email address. After you send it, the page says: "You're on the list." Sending the same address again changes nothing. The form takes at most 3 requests for one address a day and 5 an hour from one IP address; past that it says "Too many requests from here. Try again in an hour." ## The email that lets you in People are let in a batch at a time, those who waited longest first or by hand. When it is your turn, you get one email titled "You're in: recursiva". It has a **Sign in** button that opens the app. ## Sign in for the first time 1. Open https://app.rsva.dev, or press **Sign in** in the email. 2. Type the address you put on the waitlist and press **Continue with email**. 3. A 6-digit code arrives by email. Type or paste it. It works for 10 minutes. Your account is made at this first sign-in. Its name comes from your address (`sam.reyes@…` becomes "Sam Reyes"); change it later in Settings › Profile. A code only goes to an address that has a way in: let in from the waitlist, invited to a workspace, or already a member of one. For any other address the screen looks the same, but no email comes. More about codes, passkeys and sessions: [Sign in](/docs/start/sign-in). ## The Welcome screen Signed in without a workspace, you see **Welcome** with your first name, and "You are not in a workspace yet." - If you came from the waitlist and have no invites, **Create a workspace** is first: "Name it, add your first projects, invite people." - Below it, **Have an invite link?** takes a link someone sent you (`app.rsva.dev/join/…`). Press **Open**. - If invites to your address are waiting, they are listed with the workspace's name, who invited you, its member count and your role. Press **Join** or **Decline**. **Sign out** is at the top right. If an invite was your only way in, declining it signs you out. An address let in from the waitlist can create one workspace. After that you are a member like everyone else, and other workspaces need an invite. Creating a workspace step by step: [Your workspace](/docs/start/workspace). --- title: Sign in summary: The ways to sign in to recursiva, how long a session lasts, and how to use the app on a phone. --- recursiva has no passwords. You sign in at https://app.rsva.dev with a code sent to your email, or with a passkey once you have added one. A session lasts while you use it, and you can see and end every session in Settings › Security. ## With an email code 1. On the sign-in screen, type your address and press **Continue with email**. 2. Check your email for a 6-digit code. Type or paste it, then press **Sign in**. A full code is sent by itself. A code works for 10 minutes and for five tries. **Send a new code** replaces it; **Use another email** goes back. If you connected Telegram and signed in from this browser before, the code also comes to your Telegram chat. After 20 wrong codes for one address in a day, codes stop working for that address. The email then carries a one-time sign-in link instead of a code: open it, check the address it names, and press **Continue**. A code only goes to an address with a way in: a member of a workspace, an address with a live invite, or one let in from the waitlist ([Request access](/docs/start/request-access)). ## With a passkey A passkey signs you in with Touch ID, Face ID or your phone, with no code. - After a code sign-in on a device that can hold passkeys, the screen offers **Add a passkey** under "Sign in faster next time". **Not now** skips it. - You can also add one from the account menu (your avatar at the bottom of the sidebar) or in Settings › Security › Passkeys. - Adding a passkey needs a sign-in from the last 10 minutes. If yours is older, the app asks you to confirm it's you with an email code first. - Every new passkey sends you an email. To sign in with it, press **Sign in with a passkey**, or pick it from the email field's autofill where the browser offers it. Remove a passkey in Settings › Security › Passkeys; the device keeps its copy until you delete it there. ## Sessions Each browser you sign in from has its own session. - A session ends after 30 days without use, and in any case a year after sign-in. - A sign-in from a browser you have not used before sends you an email "New sign-in to your account". - A session lasts only while you have a way in. If you are removed from your last workspace and have no invite, you are signed out. Settings › Security › Sessions lists your sessions: the device, when and how it signed in, and "This device" for the one you are on. **Sign out** ends one, and **Sign out other devices** ends all the others; their open tabs stop at once. API tokens are separate: signing out a device leaves them working. To sign out here, use **Sign out** in the account menu. If some of your changes have not reached the server yet, the app asks first, because signing out deletes them and the local copy from this device. ## In a terminal `rsva login` signs your Mac's terminal in as you, for `rsva tui`. In Settings › Security, press **Sign in a terminal** and paste the code it shows into `rsva login`. The code works once, for 5 minutes. The terminal's session shows in the Sessions list and ends after 7 days without use. See [rsva tui](/docs/terminal/tui). ## On a phone The app works in a phone's browser, and you can install it: use your browser's "Add to Home Screen". It then opens full-screen, with its own icon. The phone layout has a tab bar: Inbox, My work, Projects, Search and More; the account menu is under More. --- title: Your workspace summary: What a workspace and its projects are, how to create one, and how members, roles and invites work. --- A workspace is where a team's work lives: its projects, issues, members and settings. Its address is part of every link, as in `app.rsva.dev/acme/…`. Each project in it has a short key, such as `ENG`, that starts the key of each of its issues: `ENG-12`. You can be in several workspaces and switch between them from the workspace menu at the top of the sidebar. ## Create a workspace Who may create one: an address let in from the waitlist (once), and the people the server's operator lists. Everyone else sees **Join a workspace** instead and joins by invite. Open **Create a workspace** on the Welcome screen, or **Create or join a workspace** in the workspace menu. Creating has three steps. 1. **Name.** The workspace name, its **Address** and a **Color** for its tile. The address is 3 to 32 lower-case letters, digits and hyphens, checked as you type; it cannot be only a number. The address cannot be changed later. 2. **Projects.** "Add your first projects." One project, Engineering (`ENG`), is there to start; **Suggested** adds Design, Product, Support or Infrastructure. Each project has a name and a key. You can remove them all and add projects later. 3. **Invite.** Email addresses, and the role they join with: Member or Admin. "Each person gets an email with a link that works for 7 days." You can skip this. Press **Create workspace**. You are its owner. **Open** takes you in; **Workspace settings** opens its settings. ## What a new workspace contains - You, as Owner, and nobody else until invites are accepted. - The projects you added. Each starts with five workflow states: Backlog (where new issues start), Todo, In Progress, Done and Cancelled. Todo is marked Only people: agents do not move issues into it. - No issues, labels or cycles yet. ## Projects A project has a name, a key and a color. The key is a letter and then up to 11 letters or digits, upper case. - **New project**: the `+` by the sidebar's Projects heading, the workspace menu, `⌘K`, or `n` `p`. Type a name; the key is filled in from it and can be changed. The project opens at once with the five default states. - **Project settings** (`,` in a project, or the project's `⋯` menu): General (name, key, color), Workflow (add, rename, reorder and delete states, and choose where new issues start), Labels, Cycles. - Changing a project's key keeps the old one working: links, `/browse/OLD-12` and searches by the old key still find its issues. - The project's `⋯` menu also has **Archived issues and trash**, **Copy link**, **Hide from sidebar** and **Archive project**. Archived projects are in the workspace menu under **Archived projects**, where they can be restored. By default only admins create projects and change workflow states; any member can manage labels. See "Who can change" below. ## Members and roles Settings › Members lists everyone in the workspace. There are three roles: | Role | What it can do | |---|---| | Owner | Everything an admin can. Every workspace has one owner, who cannot leave it. | | Admin | Also changes settings, members and invites. | | Member | Creates and edits issues in every project, and what Who can change opens to members. | Admins change other members' roles between Member and Admin and remove members. Nobody can change the owner's role. **Who can change**, on the same page, sets for labels, states and projects whether "Admins" or "All members" may change them. Only a signed-in admin changes it. Agents are members too: they work through API tokens and never get more than a member's rights. See [Agents](/docs/agents/agents). ## Invite people Admins press **Invite people** in Settings › Members, enter one or more email addresses, choose **Invite as** Member or Admin, and send. - Each address gets an email with its own link. The link works for 7 days. - **Pending invites** lists the open ones, with **Resend** and **Revoke**. - An address has one live invite per workspace: inviting it again replaces the earlier link. Addresses already in the workspace are skipped. - An invite stops working if the admin who sent it is no longer an admin. The invited person opens the link and signs in with the invited address, which is filled in and fixed. An address without an account gets one at that first sign-in. Someone signed in as another address is offered **Sign out and continue as** the invited one. A link that no longer works says only "This invite link no longer works". Invites go to people's email. Agents do not get invites; they get tokens. ## Leave a workspace **Leave …** at the bottom of the workspace menu. You lose access to its projects at once; your issues and comments stay. This device's copy of the workspace is deleted. Coming back needs a new invite. If it was your last workspace and you have no other invite, you are signed out too. ## Workspace settings Settings › General (`g` `,`) holds the workspace's name and color; admins change them. The address is shown there but cannot be changed. --- title: Issues summary: What an issue holds in recursiva and how to create, change, relate, archive and delete issues. --- An issue is one piece of work in a project. It has a key, a title, a description and properties: state, priority, assignees, labels, cycle, dates and a parent. Around it are sub-issues, relations to other issues, links, files, comments and its history. Every change shows at once and is saved in the background; a change the server refuses is undone, with a message. ## Create an issue Press `c` (or `n` `i`), or **New issue** in a project's header. The panel has the project, **Title**, a description and chips for state, priority, assignees, labels, cycle, start date, due date and parent. **Attach** adds files. Press **Create issue** or `⌘↵`. - **Create more** keeps the panel open for the next issue. - What you type is kept as a draft: closing the panel keeps it ("Draft saved"), **Cancel** drops it. - While you type the title, open issues with a similar title show under it. A click opens one; your draft stays. - The new issue shows in the list at once as `KEY-?` until the server gives it its number. A message then gives its key, with **Open**. ## Key and title An issue's key is its project's key and a number: `ENG-12`. Numbers go up within a project. The issue's own page is `app.rsva.dev//browse/ENG-12`; that is the link to share. - **Copy key**: `⌘.`, or click the key in the issue's header. **Copy link** is in the issue's menu. - A title can be up to 500 characters. - An issue key typed in a description or a comment becomes a link to that issue. ## Description The description is rich text, saved as you type. Markdown shortcuts work, and so do tables. In the text: - `/` opens a menu of blocks; - `@` mentions a member, who is notified; - `#` links an issue by key or title. Paste or drop an image to put it in the text. Other files dropped into the text are attached to the issue. ## State Each project has its own workflow states, in five groups: Backlog, Unstarted, Started, Completed and Cancelled. A new project has Backlog, Todo, In Progress, Done and Cancelled, one in each group. One state is where new issues start. States are changed in Project settings › Workflow, by admins unless the workspace opened them to members. A state marked "Only people move issues here" is one agents cannot move issues into. Change an issue's state with `s`, or in the list row, the board card or the issue's properties. On a board with a column per state, dragging a card to another column changes its state. ## Priority Urgent, High, Medium, Low or No priority. A new issue has No priority. Change it with `p`. ## Assignees An issue can have several assignees. Change them with `a`. The issue can also have a delegate: the agent working on it. Agents and the API set it; the app shows it, and lists can be filtered and grouped by it (Agent). See [Agents](/docs/agents/agents). ## Labels Labels you create belong to a project. Create, rename, recolor and delete them in Project settings › Labels; by default any member can. Deleting a label takes it off every issue. Add labels to an issue with `l`. A label marked "Only people rename or delete it" can be put on issues by agents but not renamed or deleted by them. ## Dates An issue has a start date and a due date, both optional. Click one to open a calendar, or type the date. A due date that has passed shows as overdue until the issue is completed or cancelled. In the new issue panel, Due date offers quick picks: Today, Fri, Next week, End of cycle and Pick a date. ## Cycle An issue can be in one cycle of its project. Set it in the issue's Cycle property. See [Cycles](/docs/issues/cycles). ## Parent and sub-issues An issue can have a parent in the same project. Set it with the Parent property; the parent's key then shows above the title. The **Sub-issues** block lists an issue's children with their progress. **Add sub-issue** offers **Create new** or **Add existing**. From the block you can also change a sub-issue's state or take it out. An issue cannot become a parent of its own parent, at any depth. ## Relations Relations connect two issues of the same workspace, in any of its projects. Add one with **Relation** under the description, then pick the kind and the issue: | Kind | Meaning | |---|---| | Blocked by | This issue waits on the other. | | Blocking | The other issue waits on this one. | | Related | The two are related. | | Duplicate of | This issue is a duplicate of the other. | | Duplicates | The other issue is a duplicate of this one. | A pair of issues has one relation: picking an already related issue changes the kind. Each relation shows on both issues. An issue blocked by an open issue gets a blocked mark in lists and on the board. Removing a relation can be undone. ## Links **Link** under the description adds an address and an optional title. Only http and https addresses are taken. Each link shows who added it and when; it can be edited or removed. GitHub pull request and commit addresses read as `owner/repo#12` and `owner/repo@abc1234`. ## Files **Attach**, or drop files on the issue. Files show in the **Attachments** block and can be removed, with Undo. A file can be up to 25 MiB. Images are shrunk to WebP, at most 2560 px on the longest side; hold Alt while dropping or attaching to keep the original. ## Comments and activity The activity under the issue has three tabs: All, Comments and History. History records each change "from → to". - Write a comment in the field at the bottom. Enter sends, Shift+Enter starts a new line. `/`, `@` and `#` work as in the description. - **Reply** answers in a thread. - Add reactions to the issue and to comments. - You can edit and delete your own comments. **Subscribe** (`⇧S`) in the activity's header sends you state changes and comments on the issue; Unsubscribe stops them. You still hear of assignments, mentions and replies. See [Notifications](/docs/notifications/notifications). ## The issue's menu The `…` of an open issue, a row's or card's menu, and `⌘K` have the same actions: - **Open**, **Open in new tab**, **Select** (`x`, for changing many issues at once); - **Copy link**, **Copy branch name** (`⌘⇧.`), **Copy key** (`⌘.`); - **Make a copy**: a new issue panel with every field and the description filled in; - **Move to project…** (`⌘⇧M`): the issue moves with its history, comments, links and files, and gets the next number in the other project. Its old key still finds it. State and labels are matched by name; the cycle is cleared. - **Archive**, **Delete** (`⌘⌫`), or **Restore**. ## Archive and trash - **Archive** is for completed and cancelled issues. It takes the issue out of the lists. Anyone can restore it. - **Delete** moves the issue to the project's trash, with Undo in the message. Only its creator or an admin can delete it or restore it from the trash. - Both are in the project's `⋯` menu › **Archived issues and trash**, under Archived and Trash. - An issue in the trash takes no edits, comments or reactions until restored. After 30 days it is deleted for good. Its creator or an admin can also press **Delete permanently** on its row in the trash. ## Keys On the open issue, or the selected row: | Key | Action | |---|---| | `s` | State | | `p` | Priority | | `a` | Assignees | | `l` | Labels | | `⇧S` | Subscribe | | `⌘.` | Copy the key | | `⌘⇧.` | Copy the branch name | | `⌘⇧M` | Move to project | | `⌘⌫` | Delete | | `⌘Z` | Undo | All keys: [Keys](/docs/keys). Finding issues by any of these properties: [Query language](/docs/finding/query). --- title: Cycles summary: How to plan a project's work in cycles, follow a cycle's progress and complete it. --- A cycle is a stretch of time in one project, with the issues planned for it. An issue is in at most one cycle. A project's cycles never overlap. Each cycle has a number in its project, shown as `C12`, a name, an optional description, a lead and its dates. Every member can create, change and complete cycles. ## The Cycles page Open a project's **Cycles** tab in its header, or press `g` `c`. The header's tab shows the cycle in progress and the days it has left. - The cycle in progress is on top: its progress by state, a burn-up chart, the reviews in it that wait on you, and its assignees. - Below are **Upcoming**, **Drafts** and **Completed**. Each row opens that cycle's page. - A cycle past its last day that is not completed yet asks to be completed. ## Create a cycle Press **New cycle**. Give it a name and, if you like, a description and a **Lead**. Pick the dates on the two-month calendar, where the project's other cycles show as bars; **Length** sets 1 to 4 weeks from the start. Dates that overlap another cycle show in red, with the first free start. Without dates, the cycle is saved as a draft (**Save draft**): plan issues into it, and pick dates later. Edit an upcoming or draft cycle from its row's menu (**Edit…**), or any unfinished cycle from **Edit cycle** on its page. Once a cycle has started, its start date is fixed. The row's menu also has **Delete**: its issues leave it. A completed cycle cannot be deleted. ## Put issues in a cycle - Set an issue's **Cycle** property. The picker offers the active, upcoming and draft cycles, and none; completed cycles are not offered. - Create an issue from the cycle's page: it joins that cycle. - In the new issue panel, set its cycle chip. ## A cycle's page A cycle's page shows its issues as a list or a board, grouped in workflow order. **Details** opens a panel with progress, the burn-up, assignees and the cycle's details. The burn-up chart draws, for each day of the cycle, the issues done, the ones started and not done, the whole scope, and the ideal line. Hover it for a day's numbers. ## Complete a cycle Press **Complete** on the cycle's page. The dialog shows the cycle's numbers and its unfinished issues. Under "Move the unfinished issues to", pick: - **Next cycle**; - **Another upcoming cycle**; - **No cycle**: back to the project, outside any cycle. Untick an issue to leave it in the completed cycle. Done issues stay in the cycle as its record. Press **Complete and move N**. A completed cycle is read-only. Its numbers are frozen, and its page lists the issues it moved on and where they went. ## Automatic rollover Project settings › Cycles › **Automatic rollover**, off by default. When it is on, after a cycle's last day (UTC) the cycle completes itself, and its open issues move to the next cycle; done and cancelled ones stay as its record. If there is no next cycle, they wait in the ended cycle until there is one. When it is off, open issues stay in an ended cycle until someone completes it. ## Find issues by cycle In a list's query, `cycle:` takes a cycle's name, its number (`cycle:C12`), `active`, `next` or `none`. A list can also be grouped by cycle. See [Query language](/docs/finding/query). ## From the terminal ```sh rsva cycles -p ENG # the project's cycles in time order rsva cycle show C12 -p ENG # a cycle and its issues rsva cycle create "Sprint 4" -p ENG --start 2026-11-16 --end 2026-11-29 rsva cycle complete C12 -p ENG --move-to next rsva cycle delete C13 -p ENG ``` `-p` names the project; without it, `rsva` reads `RSVA_PROJECT`. A cycle created without dates is a draft. `complete` needs `--move-to` with a cycle, `next` or `none`; `--keep KEY` leaves an issue in the completed cycle. See [rsva](/docs/terminal/cli). --- title: Query language summary: How to write a query that picks issues — every key, its values, the short forms, negation, dates and order. --- Every list of issues in recursiva can be written as one line of text: `state:"In Review" assignee:me priority:high,urgent due:`, `>=` | before, on or before, after, on or after a day; `due:`, `!` or `#` so that your shell does not change them. `-label:bug` is read as part of the query, not as a flag. `--view NAME` starts from a saved view's query and adds yours; `--order` sets the order and wins over `order:`. Without an order the list is last updated first. `rsva my` is `assignee:me -group:completed,cancelled` across every project, and takes a query to narrow it. See [rsva](/docs/terminal/cli). - **API.** `GET /api/v1/workspaces/:ws/issues?q=…` takes the same query. See [API](/docs/agents/api). - **Telegram.** `/find #INFRA @me` runs a query over every workspace you can read. See [Telegram](/docs/notifications/telegram). --- title: Views summary: How to filter, group and sort a list, show it as a list or a board, and save it as a view for yourself or the whole workspace. --- A list of issues in recursiva is a query plus display settings: which issues, how they are grouped and sorted, and which properties each row shows. A saved view keeps all of that under a name. A view can be yours alone or shared with everyone in the workspace, and it can show as a tab in the projects it covers. ## All issues Each project's Issues page opens on the All issues tab. It is built in. You can filter it and change its display, but those changes are temporary. Clear takes the filters back. To keep the changes, save them as a new view. ## List or board `V` switches between List and Board, as does the switch in the header. This choice is yours, on this device: it is not part of a view and does not change what others see. A view's own page shows a board only when the view covers one project. Across projects there is no board, because each project has its own states. ## Filters: the View panel The View panel is where you filter a list and save it. Open it with `F` or `E`, or with the View button in the header. `/` opens it with the cursor in the query field. - **Filters.** One line per field, each with "is" or "is not" and its values. Each value in the menu shows how many issues it would leave. Add filter adds a line. The panel shows how many issues match. - **Query.** Under the filters is the same list as one line of the [query language](/docs/finding/query). The line and the filter lines change together. The list changes as you edit. `Esc` closes the panel and keeps your changes. So does a click outside it. A new view's panel stays open until you create the view; closing it drops the draft. The list's query is also in the page address as `?q=`. A link with it opens the same list. ## Display Display sets how the list looks. Open it with `⇧V`, or the Display button beside View. - **Group by:** States, State groups, Priority, Labels, Assignees, Created by, Agent, Projects, Cycles, Parent, None. Projects is offered only on a list across projects. - **Sub-group by:** the board's rows (swimlanes). Board only. - **Order by:** Manual, Last created, Last updated, Start date, Due date, Priority. This is the same setting as `order:` in the query. - **Sub-issues:** show sub-issues as rows of their own. - **Empty groups:** show groups with no issues. - **Properties:** which properties each row or card shows: ID, Assignees, Start date, Due date, Labels, Priority, State, Cycle, Sub-issue count, Created on, Updated on. Reset takes Display back to the saved view's settings, or to the default on All issues. Display's changes are saved with the view. ## Save a view - **New view:** `⇧N` on a list, or New view on the Views page. A new view starts from the list on screen. In a project, it starts narrowed to that project. - **Save as new view:** `⇧⌘S` (`Ctrl+Shift+S`), or in the panel's ⋯ menu. It copies the current view. - **Save:** `⌘S` (`Ctrl+S`) saves your changes to the view. Revert drops them. - **Create view:** `⌘↵` (`Ctrl+Enter`) when making a new one. A view needs a name. A view's tab with changes not yet saved carries a dot. The panel saves or reverts them. In the panel, a view has: - a name and an icon; - **Visible to:** Only me, or Everyone; - **Project tab:** show the view as a tab in the projects its Project filter names. It needs a Project filter with "is"; - **In my favorites:** pin it in your sidebar. ## Who can change a view You can change and delete your own views. A shared view can also be changed by workspace admins. Only its owner can make a shared view private again. ## Project tabs A view with Project tab on shows as a tab in every project its Project filter names, after All issues. In that tab it shows only that project's issues. The tab order is shared by everyone. - `1` opens All issues, `2` to `9` the tabs after it. - `⌥←` and `⌥→` (`Alt+←`, `Alt+→`) move the open tab. ## The view's menu A view's ⋯ menu, on its tab, its page and the Views page, has: - Edit view (`E`) - Duplicate - Move left, Move right - Add to favorites, Remove from favorites - Share with everyone in the workspace, or Make it only mine - Copy link - Delete view Copy link gives an address that opens the view as a tab in the project, or on its own page. ## The Views page `G` then `V` opens the Views page: every view you can see. All, Shared and Only me narrow the list. Each row shows the view's projects ("All projects" when it names none), what else it filters, who sees it, its Tab and Favorite switches and its issue count. A view's own page shows its issues across all its projects. The key on each row names the project. ## In the terminal `rsva views` lists the saved views you can see, shared and your own. `rsva issues --view NAME` lists a view's issues, and words after it narrow the list: ```sh rsva views rsva issues --view "Waiting for review" '#INFRA' ``` See [rsva](/docs/terminal/cli). ## My work My work (`G` then `M`) is a built-in list of your issues from every workspace, in six groups: Waiting on you, You’re doing, Agents on your behalf, Up next, Later, Done this week. - `F` limits it to one workspace or project; `0` shows All workspaces again. - `1` to `9` jump to a section; `⇧D` shows or hides Done this week. - **Group by** in the header lays the same issues out by section, status, priority or project. - A group folds and unfolds by its header; what is folded is kept on your account. --- title: Command palette summary: How to search issues, jump to projects and run commands from the command palette. --- The command palette searches the issues of your workspace and runs commands from one field. Open it with `⌘K` (`Ctrl+K`), or with Search in the sidebar or, on a phone, in the tab bar. `⌘K` again closes it. Inside the text editor of a description or a comment, `⌘K` is the editor's link command; press it outside the editor to open the palette. ## Search Type a key or words from a title. - **Top hit.** A typed key goes first: an issue's (`infra-12`) or a project's (`infra`). From two letters, projects whose key starts with them show too: `we` finds WEB and WEBSITE. - **Issues.** Up to 50 issues whose key or title contains every word you typed. A key match ranks first, then titles that start with your text, then titles with a word that starts with it. Among equal matches, recently updated issues come first. - **Projects.** Projects whose name or key matches. The search covers every issue of the workspace that is not archived or in the trash. It runs on your device, without a request to the server. With the field empty, Recent lists up to five issues, views and cycles you opened last on this device. Choosing an issue opens it. Choosing a project opens the project. ## Commands The palette lists commands under Actions, and filters them as you type. Commands come before issues, so `prio` finds the command, not an issue. On an open or selected issue, a group named after its key comes first: Change state…, Change priority…, Assign to…, Copy link, Copy branch name, Copy key, Move to project…, adding it to favorites, and the actions of the issue's menu. Other commands include: - Create new issue, Create new project - Switch workspace…, Workspace settings, Workspace members, Invite people, API tokens - All projects, Archived projects - Keyboard shortcuts, Collapse sidebar - Profile, Preferences, Appearance, Security, and the email, Telegram and notification settings - Change theme…, Auto, Light and Dark color scheme, and the pane style and density - In a project: its cycles and history, Show as list or Show as board, Edit view: filters, Project settings, Archived issues and trash - On a list: Display: group, order, properties A command shows its key on the right when it has one. ## Picking a value Commands that end in "…" open a page of values: a state, a priority, assignees, a workspace, a theme or a project. A chip before the field says what you are picking and for which issue. `Backspace` in the empty field, or a click on the chip, goes back. In Change theme…, the arrow keys show each theme before you pick it. `Enter` saves it; `Esc` puts back the theme you had. ## Keys - `↑` `↓` move, `↵` selects, `Esc` closes. The terminal app has a palette too: `/` or `⌃K` there. See [rsva tui](/docs/terminal/tui). --- title: Keyboard shortcuts summary: Every keyboard shortcut of the recursiva web app, by screen. --- recursiva can be used from the keyboard alone. Press `?` to see every key on one sheet, with a field to find a key; `?` again closes it. The sheet is also in the command palette (Keyboard shortcuts) and in the account menu. This page lists the same keys. ## How to read the keys - `⌘` is Command on a Mac and Ctrl elsewhere. `⇧` is Shift, `⌥` is Option on a Mac and Alt elsewhere. - `g` then `m` means: press `g`, then press `m` within a second. - Letter keys do nothing while you type in a field. - Tooltips name a control's key. ## Moving around Tab moves between areas, the arrows inside one; Enter goes in, Esc goes out. | Key | Does | |---|---| | `Tab`, `⇧Tab` | next area, previous area | | `↑` `↓`, `←` `→` | move inside an area | | `Enter` | go in: open the issue, then into its pane | | `Esc` | go out: a field, the pane, then close | | `F6`, `⇧F6` | sidebar, list, pane | | `⌘K` | command palette | | `⌘\` | collapse or expand the sidebar | | `?` | the shortcut sheet | ## Go to | Key | Does | |---|---| | `g` then `n` | Inbox | | `g` then `m` | My work | | `g` then `o` | Project home | | `g` then `i` | Issues | | `g` then `c` | Cycles | | `g` then `h` | History | | `g` then `v` | Views | | `g` then `p` | All projects | | `[`, `]` | previous, next project | | `,` | project settings | | `g` then `,` | workspace settings | `g` then `o`, `i`, `c` or `h` open that page of the project you are in, or of the first project in the sidebar. `[`, `]` and `,` work inside a project. `Esc` on a project's settings or archive goes back to the project page you came from, else to its issues. ## Create | Key | Does | |---|---| | `c`, or `n` then `i` | new issue | | `n` then `p` | new project, if you may create projects | | `⇧N` | new view, from the list on screen | ## Lists and boards | Key | Does | |---|---| | `j` `k`, `↑` `↓` | move | | `←` `→` | board: another column | | `x` | mark the selected issue for a bulk action | | `⇧J` `⇧K`, `⇧↑` `⇧↓` | mark while moving | | `⌘A` | mark every issue on screen | | `v` | list or board | | `f` or `e` | open the View panel (filters) | | `⇧V` | Display | | `/` | filter with a [query](/docs/finding/query) | | `1` to `9` | view tabs: `1` is All issues | | `⌥←`, `⌥→` | move the open view tab | `v`, `f`, `e`, `⇧V`, `/` and `⇧N` work on a project's Issues page and on a view's own page. The tabs are on a project's Issues page. See [Views](/docs/finding/views). ## Issue These act on the open issue, else on the selected row; while issues are marked, on the marked ones. | Key | Does | |---|---| | `s` | state | | `p` | priority | | `a` | assignees | | `l` | labels | | `⇧S` | subscribe or unsubscribe | | `⌘.` | copy the key | | `⌘⇧.` | copy the branch name | | `⌘⇧M` | move to another project | | `⌘⌫` | delete | | `⌘Z` | undo the last change, while its Undo shows | ## View panel | Key | Does | |---|---| | `⌘S` | save the view | | `⌘⇧S` | save as a new view | | `⌘↵` | create the new view | | `Esc` | close the panel, keep the changes | In the query field, `Enter` or `Tab` takes the first completion of the word you are typing, and `Esc` puts back the filter you had before typing. ## Command palette | Key | Does | |---|---| | `↑` `↓` | move | | `↵` | select | | `Esc` | close | | `⌫` in the empty field | back from a page of values | See [Command palette](/docs/finding/palette). ## Inbox | Key | Does | |---|---| | `j` `k`, `↑` `↓` | move | | `e`, `⌫` | archive | | `u` | read, unread | | `h` | snooze; on a snoozed one, unsnooze | | `⌘↵` | the suggested move | | `⌥U` | mark all read | | `⇧⌫` | archive the read ones | | `f` | filter | | `v` | display options | `s`, `p`, `a`, `l` and `⇧S` act on the selected notification's issue. `Enter` goes into the issue, `Esc` comes back out. ## My work | Key | Does | |---|---| | `j` `k`, `↑` `↓` | move | | `h` `l`, `←` `→` | fold, unfold a project's proposals | | `1` to `9` | jump to a section | | `0` | all workspaces | | `⇧D` | show or hide Done this week | | `f` | limit to a workspace or project | | `↵` | open the selected issue beside the list; again, its page | | `Esc` | close it | | `a`, `d` | accept, decline a proposal | | `r` | reply to a mention or a reply | | `s` | start an issue | | `t`, `l`, `u` | a new assignment in Backlog: to Todo, to Later, unassign | ## Project home | Key | Does | |---|---| | `j` `k` | rows of every widget | | `↵` | open the issue | | `s`, `p`, `a`, `l` | status, priority, assignees, labels | | `e` | customize | | `Esc` | close a widget's settings, then cancel | | `⌘↵` | done | ## History | Key | Does | |---|---| | `1` to `4` | level: Milestones, Outcomes, Steps, Everything | | `-`, `=` | less, more detail | | `a`, `p`, `0` | agents, people, everyone | | `j` `k`, `↑` `↓` | move | | `→`, `←` | open, close a row | | `↵` | open | ## All projects | Key | Does | |---|---| | `1`, `2` | Active, Archived | | `/` | find | | `j` `k`, `↑` `↓` | move | | `↵` | open the project | | `,` | the project's settings | | `e` | archive or restore, for admins | | `⌥↑`, `⌥↓` | reorder | ## In the terminal app `rsva tui` has its own keys; `?` there lists them. Some are the same as here: `j` `k` and `↑` `↓` move, `↵` opens, `s` `p` `a` `l` change the state, priority, assignees and labels, and `c` makes a new issue. Some differ: `f` filters with a query, and `/` or `⌃K` opens the palette. See [rsva tui](/docs/terminal/tui). --- title: Agents summary: What an agent is in a workspace, how its token is made and limited, what it may and may not change, and where its work shows. --- An agent in recursiva is a member of the workspace whose account is marked as an agent. It does not sign in: it works through an API token, over the [HTTP API](/docs/agents/api) or the [`rsva` CLI](/docs/terminal/cli). An agent's role is never above Member, and a few rules hold for agents only, so people keep the decisions that matter: which work starts, and which states and labels mean "a person decided this". ## Agents are members - An agent appears in Settings › Members with an **agent** badge and a square avatar, where people have round ones. - Its role is at most **Member**. The server refuses to make an agent an Admin or the Owner. - It has no sessions. It acts only through tokens. - It reads the whole workspace, as every member does. - It gets no email and no Telegram messages. It reads its own inbox through the API (`GET …/inbox`). There is no screen in the app to add an agent account yet. Until there is, an agent can work with a token you make for yourself. That token acts as you: the agent-only rules on this page do not apply to it, and everything it does is signed with your name. ## Tokens Tokens live in workspace Settings › **API tokens**. Everyone can make tokens for themselves. Admins also see every token of the workspace, and make and change tokens for the workspace's agents. To make one, press **New token** and fill in: | Field | What it is | |---|---| | Name | 1 to 100 characters, for you to recognise it. | | For | **You**, or one of the workspace's agents. Shown only to admins, and only when the workspace has agents. | | Access | **Read**, **Write** or **Custom**, see below. | | Runs out in | 30 days, 90 days (the default), 1 year, or Never. | Then: - The secret starts with `rsva_` and is shown once, in the dialog. After **Done** only the name stays. The CLI reads it from `RSVA_TOKEN`. - Making a token needs a sign-in less than 10 minutes old. If yours is older, the app asks you to sign in again first. - Tokens are made, changed and revoked only from a browser. A token cannot make or change tokens, and neither can a terminal session from `rsva login`. - Each new token is announced by email, without the secret. An agent's token is mailed to every owner of the workspace. Your own token is mailed to you. - A token opens exactly one workspace: the one it was made in. Any other workspace answers 404 to it. Each token row shows whose it is, its access, when it runs out and when it was last used. **Revoke** stops it at once, together with any connection it has open. You can revoke your own tokens; admins can revoke any token in the workspace. ## Access: Read, Write, Custom | Access | What the token may do | |---|---| | Read | Read the workspace. Change nothing. | | Write | Everything its member may do, following the member's role as it is now. | | Custom | Read the workspace, and change only the resources set to Write. | A Custom token has a Read or Write choice per resource: | Resource | Write lets it change | Grant name in the API | |---|---|---| | Issues | fields, descriptions, links, files | `issues.write` | | Comments | comments and reactions | `comments.write` | | Cycles | cycles | `cycles.write` | | Views | saved views | `views.write` | | Labels | labels (putting a label on an issue is Issues) | `labels.write` | | States | workflow states | `states.write` | | Projects | projects (a new project also needs States) | `projects.write` | | Workspace | the workspace's name and color | `workspace.write` | Rules that hold for every token: - A token never goes past its member. The access picker offers only what the member may change, and the server refuses the rest with `a token never goes past its member`. - If the member later loses a right (their role drops, or an admin closes labels to members), the grant stays on the token but does nothing until the right comes back. The token row shows it as "held back". - Members, roles, invites and tokens are never a token's to change, whatever its access. - A refusal names what is missing, for example `the token lacks Labels: write`. To change a token's access, press **Access** on its row. The secret stays the same, so whatever uses the token keeps working; its open connections reconnect with the new access. Narrowing applies at once. Widening needs a sign-in less than 10 minutes old and is mailed to the same people as a new token, with the access before and after. You can change your own tokens. Admins can also change agents' tokens. Another person's token is only theirs to change. ## What an agent may change An agent is a member, so its tokens can do at most what a member can: | What | Members, and so agents | |---|---| | Issues, descriptions, links, files | Yes | | Comments and reactions | Yes, and edit or delete only their own comments | | Cycles | Yes | | Saved views | Their own | | Labels | Only if the workspace opened labels to members (open by default) | | Workflow states | Only if the workspace opened states to members | | Projects | Only if the workspace opened projects to members | | The workspace's name and color | No, admins only | | Members, roles, invites, tokens | No | An admin opens labels, states and projects to members in Settings › Members, under **Who can change**: each is **Admins** or **All members**. Only a signed-in admin changes this, never a token. Two more limits: - An issue goes to the trash only by its creator or an admin. An agent can trash the issues it created. - Deleting an issue permanently is done by a signed-in person in the app. No token can do it. ## Only people **Only people** is a switch on a workflow state or a label. It marks the ones that record a person's decision, such as "Todo" (start this work) or "Approved" (ship it). Turn it on with the lock button on the row, in Project settings › Workflow or Labels. Only a signed-in admin can flip it. On a state with Only people, an agent cannot: - move an issue into it; - make it the project's default state; - move it to another group; - rename or delete it. On a label with Only people, an agent can put it on issues and take it off, but cannot rename or delete it. The switch stays on through a rename. A new project's **Todo** starts with it on. A new state or label whose name reads as a guarded one (`TODO`, `pr0posed`) gets the switch by itself. Nobody but a signed-in admin can remove the protection in a roundabout way. A row with the switch on is renamed or deleted only by a signed-in admin. A row without it cannot be given a name that reads as a guarded one; this holds for members and for every token, an admin's too. Agents also name states and labels only with ASCII or Russian letters, digits and common punctuation, never Latin and Cyrillic in one name. A refused change answers 403 and writes nothing. ## Delegate and assignees An issue has assignees and, separately, a **delegate**: the agent working on it. - Assignees are the people responsible for the issue. - The delegate is who does the work. Set it with `delegate` in the API, for example `{"delegate": "agent@example.com"}`; `null` clears it. The server checks that it is a member of the workspace. - The app shows the delegate in the issue panel, with a robot icon. On a phone it is one of the property chips. In lists, the **Agent** filter and the query key `agent:` find issues by delegate: `agent:any` for issues with one, `agent:none` for issues without. A list can also be grouped by agent. ## Where agent work shows - **Comments.** An agent's comment has an **Agent** badge, a square avatar and "via API". When the issue is delegated to that agent and has a person among its assignees, it reads "for · via API". - **Activity and project history.** Agents appear under their own name, set in a monospace tag. - **My work.** "Agents on your behalf" lists the issues delegated to an agent that are assigned to you or that you created, with their state and how long since they last changed. Issues no one has touched for 48 hours are listed first. - **Waiting on you.** When an agent moves an issue you created into review, it waits on you to approve or send back. Reviews of agents' own issues go to **Triage** in the sidebar instead. - **Notifications.** "Agent asks for a review" is its own row in Settings › Notifications, on by default for email and Telegram. See [notifications](/docs/notifications/notifications). - **Morning digest.** Lists your issues an agent finished since the last digest, as "Done by an agent". ## Proposals A label named `proposed` marks work an agent proposes, kept in the Backlog. They wait in **Triage** in the sidebar, for the people chosen under **Who triages** in Settings › Members; with nobody chosen, every owner and admin triages. In [Telegram](/docs/notifications/telegram), `/triage` shows them one card at a time. When the issue leaves the Backlog group, by anyone and from anywhere, the server takes the label off. A new label named `proposed`, `security` or `owner` gets Only people by itself, as does a new state named Todo or Approved. --- title: API summary: The HTTP API agents and scripts use: address, token, conventions, limits, errors and every endpoint with an example. --- The API is plain JSON over HTTPS, authorized by an API token. It speaks in names, not ids: issues by key (`WEB-12`), states and labels by name, people by email. Descriptions and comments are Markdown. Every write goes through the same checks as a change made in the browser: rights, the [agent rules](/docs/agents/agents), the issue's history, and live updates to every open window. The [`rsva` CLI](/docs/terminal/cli) is a client of this API; `rsva api` sends any request below that has no command of its own. ## Address and token All endpoints but files live under one base address: ```text https://app.rsva.dev/api/v1/workspaces// ``` `` is the workspace's slug, the first part of its address in the app. A token opens exactly one workspace; any other slug answers 404. Send the token in the `Authorization` header: ```text Authorization: Bearer rsva_... ``` Make tokens in Settings › API tokens ([how](/docs/agents/agents)). The examples below use two shell variables: ```sh export RSVA_TOKEN=rsva_... # your token export RSVA_WS=acme # your workspace's slug ``` Check whose token it is and what it may change: ```sh curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/workspace \ -H "Authorization: Bearer $RSVA_TOKEN" ``` The answer has the workspace's `slug`, `name`, `color` and `memberRights`, and `me`: your `email`, `name`, `kind` (`human` or `agent`), `role`, the token's `scope` (`read`, `write` or `custom`) and `grants`, the resources it may change right now. ## Conventions - **Issues** by key, in any case: `WEB-12` or `web-12`. A key the issue had before its project was renamed, or before it moved to another project, still finds it. - **Projects** by key. **States**, **labels** and **cycles** by name, in any case; a cycle also by its short form, `C12`. - **People** by email, or `me` for the token's own member. `GET …/members` lists the emails. - **Priority**: `urgent`, `high`, `medium`, `low` or `none` (or 0–4). - **Dates**: `YYYY-MM-DD`. - **Text**: descriptions and comments are Markdown, read and written. A description is at most 200,000 characters, a comment 65,536, a title 500. Titles are stored cleaned: line breaks and tabs become spaces, invisible characters go. - **Mentions**: `[@Sam](mention:sam@example.com)`, or `mention:me`; an empty label (`[](mention:sam@example.com)`) gets the person's name. When the text is read back, the target is the person's id. - **Images**: a line of its own, `![caption](/files//)`, with a file uploaded to this workspace. Any other image address stays text. - **Files in a comment**: a paragraph of its own, `[report.pdf](/files//?name=report.pdf&size=2100)`, shows as a file card. - A write answers `{"ok": true, "lastSyncId": 1234}` plus what the endpoint adds. `lastSyncId` is the change's place in the workspace's log. - Answers over 1 KB are compressed when the request asks for it (`Accept-Encoding: br` or `gzip`). With curl, add `--compressed`. ## Limits | Limit | Value | |---|---| | Requests per token | 600 a minute | | Changes per person | 3,000 operations and 16 MiB a minute, across all their sessions and tokens | | Uploads per person | 256 MiB a minute | | One file | 25 MiB | | Files per workspace | 10 GiB | | Issues changed or moved in one request | 500 | Over a limit, the answer is 429 `rate_limited` with a `retry-after` header in seconds. Inbox and comment reads also count against a per-person read budget and answer 429 the same way. Too many wrong tokens from one IP address (300 in 15 minutes) also get 429, before the token is even looked up. ## Errors An error is JSON with a code and a message that says what is wrong, often listing what there is: ```json {"error": "bad_ref", "message": "no label \"nope\"; labels: \"bug\", \"chore\""} ``` | Status | `error` | When | |---|---|---| | 400 | `invalid` | A field is missing or malformed, or there is nothing to change. | | 400 | `bad_ref` | A name, key or email resolves to nothing. | | 400 | `deleted` | The issue is in the trash. Restore it first with `{"deleted": false}`. | | 400 | `invalid_query` | `q` does not parse; `errors` lists each problem with `suggestions`. | | 401 | `unauthorized` | No token, or it is revoked or expired. | | 403 | `forbidden` | The token, the role or a rule does not allow it. The message names what is missing. Nothing was written. | | 404 | `not_found` | No such workspace (for this token), issue, comment or link. | | 409 | `conflict` | A name or key is taken, or cycle dates overlap. | | 409 | `similar` | A new issue looks like an open one. See below. | | 413 | `too_large`, `quota` | A file over 25 MiB, or the workspace's files would pass 10 GiB. | | 429 | `rate_limited` | Over a limit. Wait `retry-after` seconds. | | 503 | `unavailable` | The database is busy or restarting. As a rule nothing was written; retry after `retry-after`. | Other pipeline refusals also answer 400 with their own code. ## Pagination - **Issue lists** take `limit` (1 to 500, default 100) and answer `{"total": 230, "issues": [...]}`. There is no offset: narrow the query to see more. - **Comments** come a page at a time, newest page first. If there are earlier ones, the answer has `older`; pass it back as `?until=` for the page before. ## Issues | Method and path | Purpose | |---|---| | `GET /issues` | List or search issues. | | `GET /issues/:key` | One issue, with description, relations, links, files and GitHub. | | `POST /issues` | Create an issue. | | `PATCH /issues/:key` | Change the fields given. | | `PATCH /issues` | Change many issues at once. | | `POST /issues/move` | Move issues to another project. | | `DELETE /issues/:key` | Put an issue in the trash. | Paths here and below are relative to the base address. ### List and search `GET /issues` takes: - `project`: a project key. Without it, the whole workspace. - `q`: a query in the app's [query language](/docs/finding/query), for example `state:"In Review" assignee:me label:bug -label:security updated:last-7-days`. Short forms work too: `#WEB @me !high +bug`. Relative dates use the time zone and first day of the week from the token member's profile. - `view`: a saved view's name or id. Its query and order apply; `q` narrows it. - `order`: `updatedAt` (default, newest first), `createdAt`, `priority`, `dueDate`, `startDate` or `manual`. `order:priority` inside `q` does the same; the parameter wins. - `limit`: 1 to 500, default 100. Archived and deleted issues are not listed. ```sh curl -s --compressed -G https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \ -H "Authorization: Bearer $RSVA_TOKEN" \ --data-urlencode 'project=WEB' \ --data-urlencode 'q=assignee:me state:"In Progress"' ``` Each issue has `key`, `title`, `state`, `stateGroup`, `priority`, `labels`, `assignees`, `delegate`, `parent`, `cycle`, `startDate`, `dueDate`, `createdBy`, `createdAt`, `updatedAt`, `completedAt`, `archivedAt` and `deletedAt`. ### Read one `GET /issues/:key` adds: - `description`, as Markdown; - `relations`: `blockedBy`, `blocks`, `related`, `duplicateOf`, `duplicates`, as keys; - `links` and `files`, each with an `id`; - `branch`: a branch name for the issue; a pull request from it links itself; - `pullRequests` and `commits` from GitHub. `closing: false` means the link only relates; merging it does not change the state. An issue in the trash still reads by key, with `deletedAt` set. ### Create `POST /issues` takes `project` and `title`, and optionally `state` (else the project's default), `priority`, `labels`, `assignees`, `delegate`, `parent`, `cycle`, `startDate`, `dueDate`, `description` and `force`. ```sh curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"project": "WEB", "title": "Fix the sign-in page on Safari", "priority": "high", "labels": ["bug"], "assignees": ["me"], "description": "Steps:\n\n1. Open the page\n2. ..."}' ``` The answer is 201 with `key` and `similar`: up to five open issues in the workspace whose titles look like this one (score 0.35 or more, best first), each with `key`, `title`, `state` and `score`. A match in another project counts at 0.8 of its score. If the best score is 0.75 or more, nothing is created. The answer is 409: ```json {"error": "similar", "message": "looks like WEB-9 \"Sign-in page broken on Safari\" (0.91); send force: true to create it anyway", "similar": [...]} ``` Send the same request with `"force": true` to create it anyway. ### Change `PATCH /issues/:key` changes only the fields sent, by the same names as create: - `labels` and `assignees` replace the whole list. - `parent: null`, `delegate: null`, `cycle: null` clear them. A completed cycle takes no new issues. - `description` replaces the whole description; `""` clears it. - `archived: true` archives (completed and cancelled issues only); `false` restores. - `deleted: true` puts it in the trash; `false` restores it. An issue in the trash takes no other change until it is restored. - `project` moves it to another project. `state`, `labels` and `cycle` sent with it are names in the new project. Left out, the server picks the state of the same name, else of the same group, else the default; keeps project labels of the same name and drops the rest; keeps workspace labels; clears the cycle. The answer has the new `key` and the old one as `was`. ```sh curl -s -X PATCH https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12 \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"state": "In Review", "delegate": null}' ``` ### Change many `PATCH /issues` takes `keys` (up to 500) and the same fields, except `project`. It also takes `addLabels`, `removeLabels`, `addAssignees` and `removeAssignees`, which change each issue's own list. They cannot be combined with `labels` or `assignees`. Names resolve in each issue's own project. Rights are checked on every change before anything is written: one refused change refuses the whole request. The answer has `changed`, the number of issues that changed. ```sh curl -s -X PATCH https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"keys": ["WEB-1", "WEB-3"], "state": "Done", "addLabels": ["shipped"]}' ``` ### Move many `POST /issues/move` takes `issues` (keys, up to 500), `project`, and optionally `subIssues: true` to move their sub-issues at any depth too. It is one change. Each issue keeps its history, comments, links, files and relations, and gets the next number in the new project. Issues already there are skipped. The answer lists `moved`: `[{"key": "APP-1", "was": "WEB-1"}]`. ### Trash `DELETE /issues/:key` puts the issue in the project's trash, as Delete does in the app. Only the issue's creator or an admin may. The server deletes it for good after 30 days in the trash. Deleting it for good sooner is done by a person in the app; no token can. ## Relations, links and files | Method and path | Purpose | |---|---| | `POST /issues/:key/relations` | Relate two issues. | | `DELETE /issues/:key/relations/:other` | Remove the relation between the two. | | `POST /issues/:key/links` | Add a link. | | `DELETE /issues/:key/links/:id` | Remove a link. | | `PUT /files//` | Upload a file (no `/api/v1`). | | `GET`, `HEAD /files//` | Download a file, or check that it exists. | | `POST /issues/:key/files` | Attach an uploaded file. | | `DELETE /issues/:key/files/:id` | Remove a file from the issue. | **Relations.** Send `{"type": "blocks", "issue": "WEB-3"}`. `type` is `blockedBy`, `blocks`, `related`, `duplicateOf` or `duplicates`. A pair of issues has one relation: a new one replaces the old. An issue cannot relate to itself, to one in the trash, or to one in another workspace. **Links.** Send `{"url": "https://...", "title": "..."}`; the title is optional. Only http and https, up to 2,048 characters. GitHub pull requests and commits are recognised by their address. The answer is 201 with the link's `id`. **Files.** Upload first, then attach: ```sh SHA=$(shasum -a 256 report.pdf | cut -d' ' -f1) curl -s -X PUT https://app.rsva.dev/files/$RSVA_WS/$SHA \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12/files \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"sha256\": \"$SHA\", \"name\": \"report.pdf\"}" ``` - The upload's address is the SHA-256 of the bytes, in hex, and it needs a `Content-Length`. It answers 201 when stored, 200 when the workspace already has that file (the bytes are not read again), 400 `hash_mismatch` when the bytes hash to something else, 413 when too large. - Uploading needs Issues or Comments write access. To anyone outside the workspace the address answers 404. - Attaching an unknown `sha256` is 400 `bad_ref`. The answer is 201 with the file's `id`. - Removing a file from an issue keeps the bytes: an image in a description or comment may still show them. - On download, `?name=` sets the file name. Images open in the browser; other files download. ## Comments | Method and path | Purpose | |---|---| | `GET /issues/:key/comments` | The issue's comments, a page at a time. | | `POST /issues/:key/comments` | Add a comment, or a reply with `parentId`. | | `PATCH /issues/:key/comments/:id` | Replace the text of your own comment. | | `DELETE /issues/:key/comments/:id` | Delete your own comment. | ```sh curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/issues/WEB-12/comments \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"body": "Fixed in the branch. [@Sam](mention:sam@example.com), can you check?"}' ``` A comment reads as `id`, `parentId`, `author` (email), `body` (Markdown), `createdAt`, `editedAt`, and `via` (`telegram` or `email`) when it was written there. Deleted comments are left out of the list. A deleted comment's replies stay in their thread. Another member's comment is 403; one from another issue is 404. A comment mentions at most 50 people. ## Inbox | Method and path | Purpose | |---|---| | `GET /inbox` | The token member's inbox. `?all=1` includes snoozed lines. | | `POST /inbox` | Mark lines read, unread or archived. | The answer is `{"unread": 3, "lines": [...]}`, newest first, one line per issue: `key`, `title`, `state`, `stateGroup`, `kind` (`assigned`, `review`, `approved`, `state`, `mention`, `reply` or `comment`), `kinds`, `count`, `by` (email), `at`, `unread` and `snoozedUntil`. `unread` counts what the app's badge counts. An agent's token reads the agent's own inbox. Marks take one action per request: `{"read": ["WEB-12"]}`, `{"unread": [...]}` or `{"archive": [...]}`. `"all"` instead of a list means every line that is not snoozed. They show in the person's open tabs at once. A key with no line is 400 `bad_ref`; a read-only token is 403. ```sh curl -s https://app.rsva.dev/api/v1/workspaces/$RSVA_WS/inbox \ -H "Authorization: Bearer $RSVA_TOKEN" \ -H "Content-Type: application/json" \ -d '{"read": "all"}' ``` ## Cycles All cycle paths but create take `?project=KEY`. `:cycle` is the short form (`C12`) or the name, URL-encoded. | Method and path | Purpose | |---|---| | `GET /cycles?project=KEY` | The project's cycles in time order. | | `GET /cycles/:cycle?project=KEY` | One cycle. | | `POST /cycles` | Create a cycle. | | `PATCH /cycles/:cycle?project=KEY` | Change name, description, dates or lead. | | `POST /cycles/:cycle/complete?project=KEY` | Complete it and move its open issues. | | `DELETE /cycles/:cycle?project=KEY` | Take every issue out and delete it. | - A cycle reads as `name`, `short`, `status` (`draft`, `upcoming`, `active`, `ended` or `completed`), `startDate`, `endDate`, `description`, `lead`, `issues`, `done`, `open` and `completedAt`. A cycle's issues are `GET /issues?project=KEY&q=cycle:C12` (also `cycle:active`, `cycle:next`, `cycle:none`). - Create takes `project`, `name`, and optionally `startDate` and `endDate` (both or neither; neither makes a draft), `description` and `lead`. Overlapping dates are 409 `conflict`. The answer has `short`, `name` and `id`. - In a change, `null` dates make it a draft again and `lead: null` clears the lead. A completed cycle's dates do not change. - Complete needs `moveTo`: a cycle ahead by name, `"next"`, or `null` for no cycle. `keep` lists keys of open issues that stay in the completed cycle. The answer has `moved` and `kept`. A draft or a cycle that has not started cannot be completed. - Delete answers `moved`. A completed cycle cannot be deleted. ## Projects, states and labels These change the workspace's setup. A member, and so an agent, changes labels, states or projects only where an admin opened them to members ([details](/docs/agents/agents)). | Method and path | Purpose | |---|---| | `GET /projects` | Projects by key, archived ones too. | | `GET /projects/:key` | A project with its states and labels. | | `POST /projects` | Create a project with the default states. | | `PATCH /projects/:key` | Change name, key, color, archived or rollover. | | `GET /states?project=KEY` | The project's states in the app's order. | | `POST /states` | Create a state. | | `PATCH /states/:name?project=KEY` | Rename, regroup, place or make default. | | `DELETE /states/:name?project=KEY&moveTo=Name` | Delete a state, moving its issues. | | `GET /labels?project=KEY` | Labels the project's issues can use, as a tree. | | `POST /labels` | Create a label. | | `PATCH /labels/:name?project=KEY` | Change name, color or parent. | | `DELETE /labels/:name?project=KEY` | Take a label off every issue and delete it. | - A project reads as `key`, `name`, `color`, `formerKeys`, `archivedAt` and `rollover`. Create takes `key`, `name` and optionally `color`; its states are Backlog (the default), Todo, In Progress, Done and Cancelled. A key another project has is 409, and so is a key another project had before, while that project still has issues. A new `key` in a change keeps the old one as an alias. `rollover: true` completes each cycle by itself once it is over and moves its open issues to the next. - Project and workspace colors: `ink`, `slate`, `signal`, `umber`, `ochre`, `olive`, `forest`, `teal`, `cobalt`, `indigo`, `plum`, `rose`, or `null`. - A state reads as `name`, `group` (`backlog`, `unstarted`, `started`, `completed` or `cancelled`), `default`, `onlyPeople` and `issues`. Create takes `project`, `name`, `group`, and optionally `before` or `after` a state of the same group. `default: true` makes a state the default; `default: false` is refused, as a default is replaced, not turned off. Delete needs `moveTo` when the state has issues or is the default. - A label reads as `name`, `color`, `parent`, `depth`, `workspace` (true for a label of the whole workspace), `onlyPeople` and `issues`. Create takes `project`, `name`, and optionally `color` (`#rrggbb`, or `red`, `orange`, `amber`, `green`, `teal`, `blue`, `indigo`, `purple`, `pink`, `brown`, `gray`, `slate`) and `parent`. A taken name, in any case, is 409. Delete answers `removedFrom`; labels inside it move up a level. - The Only people switch is not changed through the API. ## Workspace, members and views | Method and path | Purpose | |---|---| | `GET /workspace` | The workspace and who the token belongs to. | | `PATCH /workspace` | Change `name` or `color`. Admins only. | | `GET /members` | People and agents: `email`, `name`, `kind`, `role`. Read only. | | `GET /views` | Saved views the token member sees: `name`, `id`, `query`, `layout`, `shared`, `mine`. | Members, roles, invites and tokens are not changed through a token. --- 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 ` 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/`. 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. | --- title: The terminal app summary: What rsva tui shows, how it signs in, where it keeps its copy, and the keys and mouse that drive it. --- `rsva tui` is the live app in a terminal. It keeps a copy of the workspace on disk and stays connected to the server, as a browser tab does: reading and editing are local and immediate, and other people's changes arrive as they are made. It lists issues, opens them, changes them, takes comments, and starts agents on them ([Dispatch an agent](/docs/terminal/dispatch)). It is built for macOS. ## Start it `rsva tui` comes with `rsva`: install it as [Getting rsva](/docs/terminal/cli#getting-rsva) says. Then sign in and start it: ```sh rsva login rsva tui ``` Or start it with a token, the way the other commands run: `RSVA_TOKEN=rsva_… rsva tui` (and `RSVA_URL` for your own server). `rsva tui` needs a terminal. It goes as the first credential it finds: 1. One you name: `RSVA_SESSION`, `RSVA_TOKEN` or `RSVA_KEYCHAIN`. 2. The session of [`rsva login`](/docs/terminal/cli), kept in the Keychain. It opens every workspace you are in. A session the server has ended is skipped. 3. Your own token, in the Keychain under `rsva-own` (or the service `RSVA_OWN_KEYCHAIN` names). It opens that token's one workspace. 4. The agents' token, under `rsva-bot`. The head then says `as `. Signed in with `rsva login`, the TUI opens on the workspace you were last in. **Change workspace…** in the palette switches to another; each workspace opens from its own copy and on its own last query. Without a connection the TUI opens from its copy: on the last workspace when signed in with `rsva login`, and with a token only when `RSVA_WS` names the workspace. When you quit, it prints a short report of what it measured: the time to the first frame and to the data, key-to-frame times and memory. ## Where it keeps its copy The copy lives under your user's cache folder, `~/Library/Caches/rsva` on macOS, in a folder per credential. The folder is named by a hash of the credential, never the credential, and only you can read it. Next to the copy the TUI remembers the workspace it was last in, the last query in each workspace, and the theme you picked. `rsva logout` deletes the copies made with that session. ## The screen - **The head**: the list's name (Open issues, My issues, or Query), the workspace, how many issues, the query, and how many agents are running or waiting. - **The list**, grouped by state. Started states come first, then unstarted ones such as Todo, then the backlog, then the closed ones. The first start shows every open issue (`-group:completed,cancelled`); later starts open on the last query. Within a state the order is the query's `order:`, else the newest change first. - **The card** of the selected issue under the list: its description on the left and its properties on the right. At 80 columns it folds to five rows; under 20 rows there is no card. - **The status line**: the connection, what the last action did, and the Rex session's name when the TUI runs in Rex. - **The keys line**: the keys that act now. `?` shows every key of the screen. `↵` opens the **issue screen**: the title and a line of chips, then the description, the sub-issues and the activity (comments and history) as one feed. From 120 columns wide the properties are in a panel on the right; below that, `i` shows them above the text. ## List keys | Key | What it does | | --- | --- | | `j` `k`, `↑` `↓` | Move. | | `PgUp` `PgDn` | A page up, down. | | `Home` `End` | The first, the last issue. | | `↵` | Open the issue. | | `f` | Filter with a query. | | `/`, `Ctrl+K` | The palette: commands, issues, views. | | `c` | A new issue. | | `C` | A sub-issue of the selected issue. | | `s` | Change the state. | | `p` | Change the priority. | | `a` | Change the assignees. | | `l` | Change the labels. | | `.` | The issue's menu: everything it can do, the cycle, dates, parent and relations too. | | `d` | Dispatch to an agent. | | `r` | Reply: a comment on the issue. | | `g q` | A queue through this list. | | `o` | Open in the browser. | | `e` | Edit the description in `$EDITOR`. | | `y` | Copy the link. | | `Y` | Copy the key. | | `m` | Move to another project. | | `D` | Move to the trash, after a yes. | | `u` | Undo the last change made here. | | `Esc` | Back to Open issues. | | `?` | Every key of the screen. | | `q`, `Ctrl+C` | Quit. | `q` quits from every screen except while you type in a field. ## Issue screen keys | Key | What it does | | --- | --- | | `↑` `↓` | Scroll a line. | | `Space` `b`, `PgDn` `PgUp` | A page down, up. | | `Tab` `Shift+Tab` | The next, the previous heading: sub-issues, activity. | | `g g`, `Home` | The top. | | `G`, `End` | The end, the newest activity. | | `j` `k`, `→` `←`, `]` `[` | The next, the previous issue of the list. | | `i` | The properties, under 120 columns. | | `f` | Filter the list with a query. | | `Esc` | Back. | The issue keys of the list work here too: `s` `p` `a` `l` `r` `d` `.` `c` `C` `o` `e` `y` `Y` `m` `D` `u`, and `/` for the palette. ## Typing - **Filter** (`f`): the query language of the app's `/` field ([Query language](/docs/finding/query)). The list narrows as you type and completions follow the word. `Tab` completes, `↵` applies, `Ctrl+U` clears, `Esc` cancels. - **New issue** (`c`, `C`): one line, `#project @person !priority +label` and the title, with the query's completions. The card at the bottom shows the issue as it will be created, with up to three open issues that look like it. `Ctrl+E` writes a description in `$EDITOR`. `↵` creates; `Esc` keeps nothing. - **Reply** (`r`): a box under the activity. `↵` sends, `Shift+Enter` makes a new line, `@` offers people and `Tab` completes the mention, `Ctrl+E` opens `$EDITOR`. `Esc` leaves the reply and keeps its draft for the next `r`. - **Description** (`e`): the description in your editor (`$VISUAL`, then `$EDITOR`, else `vi`), saved when it changed. It is refused while the copy is behind the server, so it never writes over newer text. - **Trash** (`D`): asks first. `y` or `↵` deletes, `Esc` or `n` does not. `u` brings it back. - **Undo** (`u`): puts back the last change made in this TUI, then the one before. A field someone else changed since is left as it is. ## The palette `/` or `Ctrl+K` opens the palette. It finds commands, issues, saved views and places: Open issues, My issues, each project and, signed in with `rsva login`, your other workspaces. A command that picks a value opens a page of values. Among the commands: - **Go to project…**, **Open view…**, **Change workspace…** - **Order issues by…**, which writes `order:` into the query - **Change theme…**: the web's themes, dark and light, each shown as the cursor rests on it; the one picked is remembered - **Dispatch queue**, **Create an issue…**, **Filter with a query…**, **Undo the last change**, **Quit** - every action on the selected issue, with its key `Esc`, or `Backspace` in an empty field, goes back to all commands. ## The queue `g q` goes through the current list one card at a time. | Key | What it does | | --- | --- | | `↵` | Read the whole issue. | | `d` | Dispatch to Claude. | | `→` | Approve: the project's first unstarted state (Todo in the default workflow), without an agent. Takes the `proposed` label off. | | `←` | Skip: nothing changes. | | `c` | Cancel the issue. | | `o` | Open in the browser. | | `u` | Undo the last decision. | | `Esc` | Back to the list. | The card of an issue labelled `proposed` says it was proposed by an agent and lists up to three open issues that look like it. ## The mouse - A click on a row selects it; a click on the selected row opens it. - A click on a key in the keys line, or on a hint in a panel, presses that key. - A click on a link or a pull request opens it in the browser, `http` and `https` only. A click on an issue's key opens that issue. A click on a property opens its picker. - A click outside an open palette, picker or `?` sheet closes it. - The wheel scrolls. - The TUI takes the mouse, so the terminal's own text selection needs `Shift`. ## Images On the issue screen, images in the description and comments are drawn where the terminal speaks the kitty graphics protocol: Rex, Ghostty and kitty, but not inside tmux. Elsewhere an image shows as its caption. `RSVA_TUI_IMAGES=1` or `0` decides for any terminal. Only files of the workspace on this server are fetched, with the TUI's own credential; an image from another host is never fetched. An image that is not a PNG, or is larger than 1200 pixels, is converted with macOS's `sips`. Images hide under panels. ## Pager and editor The full log of a dispatch opens in your pager: `RSVA_PAGER`, then `PAGER`, else `less`. The TUI owns the screen, so `cat` or an empty value still means `less` here. Texts open in `$VISUAL`, then `$EDITOR`, else `vi`. While the pager or the editor runs, the TUI gives the terminal back and returns when it closes. ## Rex Rex is Superlogical's terminal. The TUI knows it: - In Rex the TUI reports itself as the program `recursiva` while its screen is up, and clears that when it leaves the screen. - The status line shows the name of the Rex session the TUI runs in. - Each dispatched agent runs in a Rex session of its own. The list shows the agent's state on its issue's row, and the head counts the agents running and waiting. See [Dispatch an agent](/docs/terminal/dispatch). --- title: Dispatch an agent summary: How rsva tui starts Claude Code on an issue in its own clone and Rex session, what each step does, and what it needs on your Mac. --- A dispatch starts Claude Code on one issue. The TUI clones the project's repository into a folder of its own, on a branch named after the issue, starts Claude in a new Rex session, and moves the issue to In Progress, delegated to the workspace's agent. Claude reads the issue, makes the change, runs the checks, pushes the branch and opens a draft pull request. Everything runs on your Mac, started by your own keypress: the server never sends a command or a path. A step that fails undoes the steps before it. ## What you need - macOS. The tokens come from the Keychain. - `rsva`, signed in with `rsva login` or your own token ([The rsva command](/docs/terminal/cli)). - [Rex](/docs/terminal/tui), with its `rex` command on the `PATH`. - Claude Code, with its `claude` command on the `PATH`. The TUI reads the agents' state from `claude agents --json`. - `git`, and `pnpm` when the repository has a `pnpm-lock.yaml`. The agent opens its pull request with `gh`. - A local clone of each project's repository, with an `origin` remote, mapped to the project's key (below). - An agent among the workspace's members. With several, `RSVA_AGENT` names the one issues are delegated to, by email. - Two tokens in the Keychain, which the agent runs on: - the agents' recursiva token, under the service `rsva-bot`; - a fine-grained GitHub token with Contents and Pull requests write access to the repositories agents work in, under `rsva-agents-github`. `RSVA_AGENT_KEYCHAIN` and `RSVA_AGENT_GITHUB_KEYCHAIN` name other services, for a Mac that works with more than one server. ### One GitHub token per owner A fine-grained GitHub token belongs to one resource owner: a user or an organization. When agents work in repositories of more than one owner, make a token for each and keep it under `rsva-agents-github-`, the owner in lowercase as it appears in the repository's `origin`. A dispatch looks there first, then under `rsva-agents-github`. With `RSVA_AGENT_GITHUB_KEYCHAIN` set, the same suffix goes on that name. ```sh security add-generic-password -a agents -s rsva-agents-github-acme -w ``` With `-w` last, `security` asks for the token, so it never appears on the command line. For recursiva to see the agent's pull request, and to clean up once it is merged, the repository also needs recursiva's GitHub App installed on it and the repository bound to its project on the server. Without them the token still pushes, but the pull request never shows on the issue. ## Map projects to repositories The settings live in `~/.config/rsva/dispatch.json`: ```json { "repos": { "ABC": "~/code/abc" }, "model": "opus", "effort": "high", "executorEffort": "high" } ``` | Key | What it sets | Default | | --- | --- | --- | | `repos` | A project's key and the path of its local clone. A key the project had before a rename still finds it. | — | | `model` | Claude's model when nothing else is chosen: `fable`, `opus` or `sonnet`. | `opus` | | `effort` | Its effort: `low`, `medium`, `high`, `xhigh` or `max`. | `high` | | `executorEffort` | The executor's effort, when Claude hands the code to one. | `high` | A project without a repository here cannot be dispatched: the TUI says so and does nothing. ## From the TUI Press `d` on an issue: on the list, on the issue screen, in the queue, or **Dispatch to an agent…** in the palette. 1. **Context.** Anything the issue does not say, up to 4000 characters. It goes into Claude's prompt and onto the issue as your comment. `↵` goes on, `Shift+Enter` makes a new line, `Ctrl+E` opens `$EDITOR`, `Esc` goes back. 2. **Model, effort and executor.** The panel shows the Rex session's name, the repository and the branch. `Tab`, `j` `k` or `↑` `↓` move between the rows; `h` `l` or `←` `→` change the value. `↵` launches; `Esc` or `e` goes back to the context. The choice is remembered for the project on this Mac. 3. **The launch.** Each step shows as it runs, with its time. `Esc` hides the log while it runs and the status line follows it; `l` opens the full log in your pager. When it is through, the log closes and the status line says which Rex session Claude is in. If a step fails: `r` tries again, `e` goes back to the context, `y` copies the error, `Esc` closes. One launch runs at a time. Quitting the TUI waits for a launch on its way, so its changes to the issue are not lost. ## From the command line ```sh rsva tui dispatch ABC-12 rsva tui dispatch ABC-12 --model sonnet --effort medium rsva tui dispatch ABC-12 --model opus --executor sonnet echo "Keep the public API as it is." | rsva tui dispatch ABC-12 --context - rsva tui dispatch ABC-12 --dry-run ``` | Flag | What it does | Default | | --- | --- | --- | | `--model M` | Claude's model: `fable`, `opus` or `sonnet`. | `model` in the settings, `opus` | | `--effort E` | `low`, `medium`, `high`, `xhigh` or `max`. | `effort` in the settings, `high` | | `--executor M` | Hand the code to an executor on this model; Claude curates. It must differ from `--model`. | none: Claude works alone | | `--context TEXT` | Your context for the agent. `-` reads it from stdin. | none | | `--dry-run` | Print the repository, the clone's folder, the branch, the Rex session, the `claude` command and the prompt, and stop. | off | The command prints each step as it ends: `✓` done, `✗` failed, `↺` undone. Its last line names the Rex session Claude is working in. `rsva tui agents` lists the agents started from this Mac, one line each: the issue, its state, the model and effort, when it started, and the Rex session. The state is what Claude Code reports, such as `busy`, `idle` or `blocked`; `starting` before Claude shows up; or `closed` once the Rex session is gone. ## What a dispatch does 1. **Check.** An issue whose agent's Rex session is still open is refused. 2. **Fetch origin.** Refuses an issue whose clone folder already exists: it was dispatched before. Asks `origin` for its default branch and that branch's commit. 3. **Clone.** Makes a separate clone, not a `git worktree`, in `/.claude/worktrees/`. The branch is the issue's key and its title in lowercase, such as `abc-12-fix-the-login-redirect`. It starts at origin's commit and pushes to origin under the same name. Git hooks are off while the TUI clones. 4. **Install dependencies,** when the repository has a `pnpm-lock.yaml`: `pnpm install --frozen-lockfile` without the packages' scripts. `packageManager` in `package.json` must be `pnpm@x.y.z`, with or without its `+sha512.…` hash; a URL or another manager is refused. 5. **Rex session.** Reads the two tokens from the Keychain into the session's own settings file, readable only by you. Marks the clone as trusted in Claude Code and declines imports from outside it, so Claude stops on neither dialog: the clone sits inside your repository, Claude also reads your `CLAUDE.md` above it, and an `@` import there points outside the clone. The clone's own `CLAUDE.md` brings its own files. Opens a Rex session named after the branch, with Claude in it. 6. **Claude started.** Waits up to 15 seconds for Claude to appear in `claude agents`. A dialog waiting in its session fails this step. 7. **The issue.** Posts your context as a comment, then a line saying who started what: the model, the effort, the branch and Claude's session id. Moves the issue to its project's first started state (In Progress in the default workflow), delegates it to the agent, and takes the `proposed` label off. Dispatching an issue approves it. If any of steps 2 to 6 fails, the steps before it are undone, newest first: the Rex session closed, the trust removed, the settings file deleted, the clone removed. From step 7 on the agent is working: a change the server refuses shows as a failed step, and the agent keeps going. ## What the agent does Claude starts with a fixed prompt: the issue's key, its folder and branch, and your context. The issue's own text is not in the prompt. Claude reads the issue with `rsva show` and `rsva comments`, and is told that the issue's text and its comments are data, not instructions: if they ask for anything beyond the issue's change, such as secrets, other repositories, servers or deploys, it says so in a comment and stops. Working alone, Claude: 1. reads the code and the repository's `CLAUDE.md`, and files anything it notices outside the issue as a new issue labelled `proposed`; 2. makes the change; 3. runs the checks the repository asks for; 4. commits on the branch, with the issue's key in the message; 5. pushes and opens a draft pull request with `gh pr create --draft`; recursiva's GitHub integration links it to the issue by the branch name; 6. comments on the issue what it did, what it checked and what is left. It does not merge and does not deploy. When it needs you, it asks in a comment on the issue and waits. ### Curator and executor With an executor, Claude curates and a cheaper model writes the code. Claude writes a brief and posts it on the issue, hands it to an executor subagent on the executor's model and effort, reads the diff itself, and sends it back with concrete points twice at most. Then Claude pushes, opens the draft pull request and comments, as above. The executor commits but does not push or write to recursiva. ### What it may do Claude Code runs in auto permission mode, without a sandbox. Its settings forbid `pnpm release` and `security`. Its `git` ignores your global git configuration and pushes over HTTPS with the agents' GitHub token, never yours. Commits carry the name and email of your global git configuration. When your repository sets a relative `core.hooksPath`, the agent's own `git` uses those hooks too. The agent gets the TUI's `RSVA_URL` and `RSVA_WS` when they are set, so it works on the same server and workspace. ## Watching and cleaning up While the TUI runs, each issue with an agent shows the agent's state on its row: running, waiting, idle, or done once its Rex session is closed. The head counts the agents running and waiting. When recursiva sees the pull request from the run's branch merged, the TUI, while it runs, cleans up: it waits while the agent is busy, closes the Rex session, moves the clone to a trash folder in its cache, and deletes the settings file and the trust entry. The clone is kept there for a week, for anything the agent left uncommitted, then deleted. `rsva tui agents` deletes the settings file, with its tokens, of every agent whose Rex session is closed. --- title: Notifications summary: What reaches your inbox, what goes out by email, and how to choose what reaches you where and when. --- Everything that concerns you lands in your Inbox in the app. Email and [Telegram](/docs/notifications/telegram) get only what you choose, per event, in Settings › Notifications. Your own actions never notify you. Agents and bots get no email; agents read their inbox through the [API](/docs/agents/api). ## What concerns you You are involved in an issue if you created it, are assigned to it, or commented on it. Then: | You get | When | |---|---| | Assigned | Someone else assigns you. | | Review | An issue you created moves into review. | | Approved | An issue assigned to you moves into an approved state. | | State changed | Any other state change of an issue you are involved in. | | New comment | A new comment on an issue you are involved in. | | Reply | A reply in a thread you wrote in. | | Mentioned | Someone mentions you in a comment or a description, whether or not you are involved. | Review and approved come from the project's workflow. In the Started group, the first state is work in progress, the second is review, and any later one counts as approved. With the default states (In Progress only) there is no review step until you add one. **Subscribe** on an issue (the bell in its activity header, or `⇧S`) brings you its state changes and new comments though you are not involved. **Unsubscribe** stops them for an issue you are involved in. What is addressed to you, such as an assignment, a review, a mention or a reply, arrives either way. ## Inbox The Inbox has one line per issue, newest first. It keeps 60 days, up to 500 notifications. Its count shows in the sidebar and the browser tab. Read on one device is read everywhere. - **Tabs**: Unread (first) and All. What waits on you, such as a review to decide or an assignment to start, is in My work. - **Filter** by type (Mentions, Reviews, Assigned), sender, project, priority and status group. Display options group, order, show snoozed lines and put unread first. - **Read and unread**, **Archive** (`E`) and **Snooze** (`H`). An archived line comes back when something new happens on the issue. Snooze offers Later today (18:00, until 17:00), Tomorrow (09:00), Next Monday and In a week; a newer event brings the line back early. - **Mark all read** in the header. **Archive all**, **Archive all read** and **Archive all completed** in its menu. - Each of these has Undo. The selected line opens the issue beside the list, with a strip that says who did what and what is asked of you. ## What reaches you where Settings › Notifications › **What reaches you where** is a table: one row per event, a column for Email and one for Telegram. Click a cell to choose **Instantly**, **Digest** or **Off**. Telegram has no digest: Instantly or Off. | Event | Email | Telegram | |---|---|---| | Agent asks for a review: an agent moved your issue into review | Instantly | Instantly | | Review requested: someone hands work back to you | Instantly | Instantly | | Mentioned | Instantly | Instantly | | Assigned to you | Instantly | Off | | Reply to your comment | Digest | Instantly | | New comment | Digest | Off | | State changed | Off | Off | | Due today: your open issues | Digest | Off | | Cycle starts or ends: cycles you lead, on their first and last day | Instantly | Off | These are the defaults. **Due today** and **Cycle starts or ends** are days, not events, so they never show in the Inbox. Set to Instantly, they come at your digest time as one email (and one Telegram message) that lists both. Under the table, **Email, start from** sets the whole Email column at once: **Only what waits on me** (review, plan and mention instantly, the rest in the digest), **Everything instantly**, or **Digest only**. ## Timing - **Quiet hours**: on by default, 22:00 to 08:00 in your time zone. Email that falls inside waits until they end. **Urgent issues still get through** is on by default. Quiet hours need a time zone in Settings › Preferences; your browser's zone is taken on your first visit. - **Already seen**: on by default. A notification waits 10 minutes. If you read or archive it in the app meanwhile, no email goes. - **Per workspace**: **Everything** follows the table, **Only about me** keeps only the rows addressed to you (the two review rows, Mentioned, Assigned to you, Reply to your comment), **Nothing** sends nothing from that workspace. News more than a day old is not sent: a server that was stopped does not mail you its backlog. ## Email Settings › Notifications › **Email** holds the rest: - **Sends to**: your account address. Sign-in codes and security emails always go there, whatever you set. - **Sending**: **One email each**, threaded per issue in your mail client, or **Bundle every 30 minutes**. In a bundle, an urgent issue still goes at once while **Urgent issues still get through** is on. - **Morning digest**: on by default, at 08:00 on weekdays, in your time zone; pick the time and the days. It lists what waits on you, what is due today, what agents finished since the last digest, and the events you set to Digest. **Skip the day when there is nothing** is on by default. - **Weekly summary**: off by default. Mondays at 09:00: cycles that ended, what was done per project, and how much agents did. - **Emails as**: **HTML and text**, or **Text only**. - **Unsubscribe from everything** turns off every email row, the digest and the summary. Sign-in codes and security emails still arrive. Every notification email, digest and summary has an unsubscribe link that works without signing in, and headers that let your mail client unsubscribe in one click. Both do what Unsubscribe from everything does; turn email back on in the settings. If your Telegram chat stops taking messages, for example because the bot was blocked, what was set to Telegram comes by email until you connect it again. ## Replying by email Where the server is set up for it, the Email page has a **Replying** section and a reply to a notification email posts as your comment on the issue, in the comment's thread when the email was about one. It is on by default; turn off **A reply posts as your comment** to stop it. - Only a single notification email has its own reply address. A bundle or a digest does not. - Write above the line "Reply above this line". Only the text above it posts. - The reply must come from your account's address, and your mail provider must vouch for it (DMARC or DKIM). Mail that fails this is dropped without an answer. - Replies are taken for 30 days after the email. - If your reply cannot post, for example because the email is too old, replying is off, you lost access, the issue is in the trash or there was no text, you get an email that says why. - A comment posted this way says "from Email" in the app. A reply is only a comment: it does not approve, send back or snooze. --- title: Telegram summary: How to link Telegram, what the bot sends, and what you can do from a chat or a group. --- recursiva has a Telegram bot. Linked to your personal chat, it sends the notifications you route to Telegram, and with Actions on it also takes replies, commands and button presses as you. Linked to a group, it tells everyone there about chosen events in some projects. Telegram is set up per server: if it is not, Settings › Notifications › Telegram says "Not set up", and email and the Inbox work as usual. ## Link your chat 1. Open Settings › Notifications › **Telegram** and press **Connect Telegram**. This needs a sign-in less than 10 minutes old; if yours is older, the app asks you to sign in again. 2. Open the link, or scan its QR code on your phone. It works for 10 minutes. 3. Press **Start** in Telegram. The settings page updates by itself. 4. Pick **What should come to Telegram?**: **Only what waits on me** (plans, reviews and mentions), **The same as email** (whatever is Instantly for email), or **Everything instantly**. You can change each event later. Then: - The bot's reply to Start names your account by its masked email, with a **Not me** button. If someone else's link connected your chat to their account, Not me unlinks it at once. - Your account's address gets a security email for every chat linked. - **Send a test** sends a test message. **Disconnect** unlinks the chat and deletes its chat ID. ## What arrives Your personal chat follows the Telegram column of [What reaches you where](/docs/notifications/notifications). Telegram has no digest: each event is Instantly or Off. If Due today or Cycle starts or ends is Instantly for Telegram, it comes as one message at your digest time. On the Telegram page: - **Length**: **With the comment** (the default), or **Short**: only what happened and the issue. - **Quiet hours**: **Deliver silently** in your quiet hours (on by default), or, with it off, messages wait until the quiet hours end. With **Urgent issues still get through** on, an urgent issue rings through either way. Under each message are **Open** (the issue in recursiva), **Snooze 2h** (snoozes the issue's line in your Inbox, as the app does) and **⋯** (turns the message into the issue's card, below). With Actions off, only Open. If the chat stops taking messages, for example because you blocked the bot, the page shows a banner. Meanwhile what was set to Telegram comes by email, and the banner counts it. Press **Reconnect**, or unblock the bot, to resume. ## Actions The **Actions** switch on the Telegram page decides whether the chat can act as you. - **Off**: notifications only. Each has Open alone. Commands other than `/mute` and `/help`, buttons, replies, forwards and issue keys are answered with how to turn Actions on. A chat starts with Actions off whenever it is linked. - **On**: buttons, commands and replies change issues, comments and your Inbox, as you would. Turning it on needs a recent sign-in and sends a security email. Turning it off works from any session. Everything done from the chat says "from Telegram" on its history line and comment. ## Replies and issue cards - **Reply** to a notification to comment on its issue. When the notification was about a comment, the reply goes in that comment's thread. - **Send an issue key** alone, or up to five (`WEB-12 WEB-14`), to get each issue's card: key, state, priority, title, assignees, agent, cycle, labels, due date and the last comment. - The card's buttons are **State ▾**, **Priority ▾**, **Assignee ▾**, **Labels ▾**, **Snooze 2h** and **Open**. A pick changes the issue and redraws the card, with **Undo** for ten minutes. A person or a label is switched on or off. - States and labels marked Only people (such as Todo, Approved and `proposed`) are not offered. **No labels** leaves them on. Approving is done in recursiva. - A text reply to a card is a comment on its issue. ## Commands The bot's menu in Telegram lists these. They work in your personal chat. | Command | What it does | |---|---| | `/my` | Your My work, five at a time. | | `/inbox` | Your Inbox, five at a time, with tabs Unread and All. In Unread, **Read** buttons per line and **Mark all read**. | | `/find query` | Searches every workspace you can read with the [query language](/docs/finding/query), for example `/find #WEB @me !urgent`. Five at a time. | | `/triage [#project]` | Open issues labelled `proposed`, oldest first, one card at a time, with **Cancel** (with Undo), **Skip** and **Open**. A "Similar:" line lists up to three open issues that look like it. | | `/new Title` | Creates an issue, see below. | | `/mute 2h` | Pauses everything but urgent, see below. | | `/help` | The commands and the fields `/new` takes. | ### /new The first line is the title, with the short forms of the query language: `#project`, `@assignee`, `!priority`, `+label`, and the keys `state:`, `cycle:`, `parent:`, `due:`, `start:`. Lines after the first are the description. ```text /new Fix the sign-in page on Safari #web !high +bug It fails after the code is typed. ``` - Without `#project`, the issue goes to the project of the last issue you created. - Without `@`, you are the assignee. - An unknown name, or two values for one field, creates nothing; the bot answers with a suggestion. - Sent as the caption of a photo or a file, `/new` attaches it. An album with one `/new` caption attaches every photo. - `/new` as a reply to a card or a notification makes a sub-issue of that issue. - `/new` as a reply to someone else's message takes its text and file. - A message **forwarded** to the bot comes back as a draft with **Create**, **Project ▾** and **Cancel**. The bot answers with the new issue's card. ### /mute `/mute 30m`, `/mute 2h` or `/mute 1d`, a week at most. `/mute off` ends it. `/mute` alone shows where things stand, with **1h**, **2h**, **Until 09:00** and **Off** buttons. While muted, urgent issues still come. Everything else is not sent later: it waits in your Inbox. The Telegram page shows "Muted until …" with **Resume**. ## Sign-in codes With a chat linked, your sign-in code also comes to Telegram, besides email, when you sign in from a browser this account has signed in from before. The message cannot be forwarded, and the bot deletes it once the code is used, replaced or expired. From any other browser the code goes by email only, and the chat gets a note that a sign-in was asked from a new browser, with a **Not me** button that voids that code. ## Group chats A group gets the events of chosen projects in one workspace, so everyone in it sees them. 1. With the workspace open in the app, go to the Telegram page and press **Add a group chat**. The group gets that workspace's events. 2. Add the bot to the group with the link: Telegram asks which group and sends the code there itself. In a group the bot is already in, send the command shown, `/link@ `, instead. The code works for 10 minutes. 3. Back on the page, pick the group's **Projects** and **Events** and save. Nothing goes to the group before that. | Event | When | |---|---| | New urgent issue | An issue is created as urgent, or raised to urgent. | | Plans waiting for approval | An agent moved an issue into review. | | Cycle starts or ends | On a cycle's first and last day, one message at 09:00 in the time zone of the person who linked the group. | - A group gets only what the person who linked it may read in that workspace. - The person who linked it and the workspace's admins can change its projects and events or remove it. - Getting a code, and saving a group with more projects or events than before, needs a recent sign-in. The person who linked it gets a security email for every group linked. - Each group message has **Open** only. `/help` in the group says what it gets and who linked it; the other commands are for your personal chat. - If the bot is removed from the group, the group is marked and gets nothing more until you **Link again**.