Tasks

The sayr task commands cover the everyday task workflow. Each one takes --org <slug>. Leave it out and the CLI uses your default organization, or at a terminal asks which one. Each also takes --json for scriptable output.

Referring to a task

Commands that act on an existing task take <taskId>: the task's number (the 123 in a key like SAY-123) or its full id. The prefixed key itself, SAY-123, isn't accepted, so drop the prefix. task list and task view print keys, and task create prints the task's URL, which ends in the number.

Create a task

sayr task create "Fix the flaky deploy check" --priority high --status todo
sayr task create "Add dark mode" --description "Follow the **system** setting." --category Design
sayr task create "Cut the v1.2.0 branch" --release v1-2-0

The title is required, except at a terminal: leave it out and guided mode asks for it and offers to add a description, status, priority, category, and release. sayr task create --help shows <title> because scripts and agents have to pass one.

--category takes a category's name or its id. A name is matched exactly, ignoring case, and an unknown or ambiguous one is an error that lists your categories. See Names instead of ids.

On success it prints the task's title and URL. With --json you get id, shortId, title, orgSlug, and publicPortalUrl.

List tasks

sayr task list                                  # open tasks, most popular first
sayr task list --sort newest --limit 5          # the five newest tasks
sayr task list -q "deploy" --sort newest        # search, newest first
sayr task list --release v1-2-0                 # only tasks in a release
sayr task list --include-closed --limit 10 --page 2

As a member you always see both public and private tasks. mostPopular puts the most-voted tasks first (newest first among ties), and trending favours newer tasks with plenty of votes and comments.

Each task prints as a key, status, priority, and title, followed by a footer with the page and total:

SAY-123  in-progress  high    Fix the flaky deploy check
SAY-118  todo         medium  Update the onboarding checklist

Page 1 of 3 — 57 total

With --json the output is { "tasks": [...], "pagination": {...} }. The pagination object has limit, page, totalPages, totalItems, and hasMore. See Scripting & automation for a loop that walks every page.

View a task

sayr task view 123

Prints the task's key and title, status, priority, category, labels, assignees, and creator, then its description as plain text (inline formatting such as bold and links is dropped). If the task has an AI summary, that follows, marked "stale" when it's out of date. The CLI only reads a summary that already exists and never generates one. The first five top-level comments come last, and a comment that has replies includes a hint for reading them.

With --json you get the full task plus comments (the same five) and commentsTotal. The description comes back as its raw ProseKit document rather than plain text. For the rest of the comments, see Comments.

Update a task

Only the flags you pass are changed.

sayr task update 123 --status in-progress
sayr task update 123 --priority urgent --release v1-2-0
sayr task update 123 --no-release
sayr task update 123 --visible private

Every update also needs tasks.read. See Authentication & API keys.

If you pass no field flags at a terminal, guided mode shows the task and asks what to change: title, status, priority, category, release, or visibility. It starts each prompt from the current value, and the release list includes "No release". The description isn't offered, so use --description for that. Anywhere it can't ask (a script, --json), the CLI prints "Nothing to update" and makes no request.

Labels and assignees

Both commands replace the whole set. Anything you leave out of --set is removed. Pass an empty string to clear it.

sayr task label 123 --set bug,frontend      # the task now has exactly these labels
sayr task label 123 --set ""                # remove every label

sayr task assign 123 --set <user-id>        # the task now has exactly this assignee
sayr task assign 123 --set ""               # unassign everyone

• Labels need content.manageLabels. --set takes label names or ids, comma-separated. A UUID is sent as it is, and any other value is matched to a label by exact name, ignoring case, so --set "Backend,Needs review" works. An unknown or ambiguous name is an error that lists your labels, and a label whose name contains a comma has to be passed by id. To see your labels, run sayr labels list. See Organizations, labels & categories and Names instead of ids.
• Assignees need tasks.assign and take user ids, not names. sayr whoami prints yours, and sayr orgs list --json lists every organization's members with their user ids.

Leave out --set on task label at a terminal and guided mode shows your organization's labels with the task's current ones ticked, so you can tick and untick them. --set "" is a value, not a missing option, so it clears the labels without asking.

Putting tasks in releases

--release takes a release's slug or id. It works on task create, task update, and task list (as a filter), and task update --no-release takes a task out of its release. sayr releases list shows both the slug and the id. See Releases.

Related

• Comments: read and post comments on a task
• Guided mode: let the CLI ask for what's missing
• Tasks: the product feature