docs~/finding/query.md
/esc
~/finding/query.md
finding/query.md · 8 min · updated 2026-11-15 · as markdown

# Query language

Every list of issues in recursiva can be written as one line of text: state:"In Review" assignee:me priority:high,urgent due:<today login. You type it after / in the web app, and the same line works in the terminal app, in rsva issues, in the API and in Telegram's /find. This page describes what that line accepts.

The shape of a query

A query is a list of words separated by spaces.

  • key:value filters by one field: label:bug.
  • A comma means "any of": priority:high,urgent finds issues that are high or urgent.
  • The same key twice adds up the same way: label:bug label:security is label:bug,security.
  • Different keys must all match: label:bug assignee:me finds your bugs.
  • -key:value means "is not": -label:security leaves out issues with that label.
  • Every other word is free text, matched against the title and the issue key.
  • order: says how to sort the list. It does not change which issues are in it.

Keys and names are not case-sensitive: STATUS:todo is state:Todo.

Keys

Key Values Example
project: a project's key or name; a key the project had before a rename still works project:INFRA
state: (or status:) a workflow state's name state:"In Review"
group: a state group: backlog, unstarted, started, completed, cancelled group:started
priority: urgent, high, medium, low, none priority:high,urgent
assignee: (or assignees:) a person's name, email, or the part of the email before @; me; none (no assignees) assignee:me
label: (or labels:) a label's name; none (no labels) label:bug
author: (or creator:, createdby:) the person who created the issue; me author:me
agent: (or delegate:) the agent the issue is delegated to; any (delegated to any agent); none (not delegated); me agent:any
cycle: (or cycles:) a cycle's name or its short form C12; active (each project's cycle in progress today); next (each project's nearest upcoming cycle); none (in no cycle) cycle:active
parent: the parent's issue key (direct sub-issues only); any (every sub-issue); none (top-level issues) parent:INFRA-300
is: blocked (waits on an open issue); blocking (an open issue waits on it); duplicate (marked a duplicate of another issue) is:blocked
has: link: a link, a pull request or a commit is attached (an uploaded file does not count) has:link
start: a date expression (see Dates); none (no start date) start:this-week
due: a date expression (see Dates); none (no due date) due:<today
created: a date expression (see Dates) created:last-7-days
updated: a date expression (see Dates) updated:yesterday
closed: (or completed:) when the issue was completed: a date expression (see Dates); none (not completed) closed:last-7-days
order: (or sort:) updated, created, priority, due, start, manual order:priority

In a project's list, state, label and cycle names are those of that project. In a list across projects, one name stands for every project's state or label of that name.

Short forms

Four keys have a one-character form, typed at the start of a word:

Short form Means Example
# project: #INFRA
@ assignee: @me
! priority: !urgent
+ label: +bug,security

So #INFRA @me !high fix is project:INFRA assignee:me priority:high fix.

A sign counts only at the start of a word and only when something follows it. a@b.c, a lone # and C# stay free text. To search for a word that starts with one of the signs, put it in quotes: "#123". When recursiva writes a query back (in the query field or the page address), it uses the long keys.

Short forms cannot be negated: -#INFRA is free text. Write -project:INFRA instead.

Negation

Put - before a key to leave issues out: -label:proposed, -state:Done, -group:completed,cancelled. An issue with any of the listed values is left out. Negated and plain keys combine: group:started -assignee:me finds started issues not assigned to you.

Every key with a list of values can be negated. Dates and order: cannot: -due:today is an error. For dates, write the range you want instead.

Quoting

Put a value in double quotes when it has a space, a comma or a colon: state:"In Review", assignee:"Zoe Quinn". A quote inside quotes is written \".

A quoted value is always a name, never a keyword. label:none finds issues without labels, while label:"none" finds the label called "none". The same holds for me, any, active and the other keywords.

A query with an unclosed quote runs to the end of the line.

Free text

Words that are not key:value are free text.

  • Each word must appear in the issue's title, in any case: dark mode finds titles that contain both "dark" and "mode".
  • A phrase in double quotes stays together: "dark mode".
  • A word that looks like an issue key, such as infra-12 or 12, is also matched against the key.
  • A word with a colon reads as a key. To search for it as text, quote it: "a:b".

Dates

start:, due:, created:, updated: and closed: take a date expression. Ranges include both ends.

Expression Means
2026-11-01 that day
today, yesterday, tomorrow that day, counted from today
<2026-11-01, <=, >, >= before, on or before, after, on or after a day; due:<today is overdue
2026-11-01..2026-11-30 from one day to another; either end may be left open: 2026-11-01..
this-week, last-week, next-week a calendar week
this-month, last-month, next-month a calendar month
last-7-days, next-2-weeks, last-3-months last-N-… ends today, next-N-… starts today; units are day, week, month or their plurals
none the issue has no such date; only for start:, due: and closed:

Days are counted in your time zone, and weeks start on the first day of the week set in your Preferences. A relative expression stays relative: a saved view with updated:last-7-days shows the last seven days on the day you open it, not the day it was saved.

me, none and any

  • me is you: assignee:me, author:me, agent:me, @me.
  • none means the field is empty: assignee:none, label:none, agent:none, cycle:none, parent:none, due:none, start:none.
  • any means the field is set to anything: agent:any, parent:any.

Order

order: sets the order of the list. It filters nothing.

Value Order
updated last updated first
created last created first
priority urgent, high, medium, low, then no priority
due earliest due date first, issues without one last
start earliest start date first, issues without one last
manual the order you set by dragging

A query takes one order. If it names two, the last one wins. In the web app, order: and Display's Order by are the same setting: changing one changes the other, and Manual writes no order:. A query without order: leaves each screen in its own order.

Mistakes

An unknown key, an unknown name or a bad date is an error with suggestions. In the web app, the errors show under the query field with "Did you mean", and the rest of the query still applies, so one typo does not empty the list. While you type a word, its completions show as "Complete:"; Enter or Tab takes the first one. Esc puts back the filter you had before you started typing.

rsva issues and the API do not run a query with an error. rsva prints the server's message, then its suggestions on a try: line, and exits with code 1.

Telegram's /find lists the errors and runs the part of the query that is valid.

Where you can type a query

  • Web app. Press / on a project's Issues page or a view's page. The View panel opens with the cursor in its query field. The field and the panel's filters are tied both ways, and the list changes as you type. The query is also in the page address as ?q=, so a link opens the same list. See Views.
  • A widget's settings on a project's home take a query in the same field.
  • Terminal app. Press f in the list. See rsva tui.
  • rsva issues. The words after the command are the query:
sh
rsva issues 'state:"In Review"' -label:security order:priority
rsva issues '#INFRA' @me is:blocked
rsva issues --view "My bugs" 'due:<today'

Quote words that contain a space, a quote, <, >, ! 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.

  • API. GET /api/v1/workspaces/:ws/issues?q=… takes the same query. See API.
  • Telegram. /find #INFRA @me runs a query over every workspace you can read. See Telegram.