The ys command line
ys drives Yardsort from a terminal. It reads the same database as the app, so a workspace made
with ys appears in the window and a workspace made in the window appears in ys. It does not
need the app to be running.
An agent started by ys belongs to the daemon,
not to the command — so it keeps working after ys returns, and you can open Yardsort later to
watch it. That is the whole point of it.
Installing
ys comes with the app. Every copy of Yardsort carries it next to its own executable, built from
the same commit, so the two always agree about the database. Whether it is on your PATH depends
on how you installed Yardsort:
| How you installed Yardsort | Where ys is | How it is updated |
|---|---|---|
.deb, .rpm, or the AUR package | /usr/bin/ys, installed with the app. Nothing to do. | By your package manager, with the app. |
| Homebrew cask | Linked onto your PATH by Homebrew. | With the app. |
macOS app (.dmg) | Install ys makes /usr/local/bin/ys, a link into Yardsort.app. macOS asks for your password when that folder needs it. | With the app: the link points into it. Signed and notarized with it, too. |
| Linux AppImage | Install ys copies it to ~/.local/bin/ys. An AppImage is mounted somewhere new every time it starts, so a link would stop working. | When Yardsort starts and finds an older copy there, it replaces it. |
Windows installer (-setup.exe, .msi) | Install ys copies it to %LOCALAPPDATA%\dev.yardsort.app\bin\ys.exe and adds that folder to your user PATH. Terminals opened afterwards find it; ones already open do not. | When Yardsort starts and finds an older copy there, it replaces it. A ys.exe that is running at that moment is renamed aside and removed next time. |
Install ys is in Settings → General → Command line. The first-run checklist on the welcome
screen has it too, while ys is missing or out of date. Both say where your terminal finds ys
and which version it is. It is optional: nothing in the app needs ys.
- Something else is called
ys. If there is already a file at the install location and it is not Yardsort'sys, Yardsort asks before replacing it; Cancel leaves it alone. Aysalready there, of any version, is replaced without asking. So is a broken link left by aYardsort.appthat has since moved; a broken link to anything else counts as something else. - Another
yscomes first. If your terminal finds ayssomewhere else — one you unpacked by hand, say — the panel names it. Installing then puts Yardsort's own copy at the install location, but the other one keeps winning until you remove it. ~/.local/binis not on yourPATH. Most Linux distributions add it when it exists, but not all. The panel says so; add it in your shell's startup file (for exampleexport PATH="$HOME/.local/bin:$PATH") and press Check again.- macOS says to move Yardsort first. A link into an app that is still on its disk image, or that macOS is running from a temporary copy, would break. Drag Yardsort into Applications and open it from there.
To remove it, delete the file or link at the install location, and on Windows the folder's
entry in your user PATH.
Without the app
ys is also a separate download: a single binary in the assets of each
release. Put it anywhere on your PATH.
# Linux
tar -xzf ys-*-linux-x86_64.tar.gz && sudo install ys /usr/local/bin/
# macOS (universal)
tar -xzf ys-*-macos-universal.tar.gz && sudo install ys /usr/local/bin/
On Windows, unzip ys-*-windows-x86_64.zip and put ys.exe in a folder on your PATH.
On macOS, this copy is the same file as the one inside the app: signed with the same Developer ID and notarized by Apple. A notarization ticket cannot be attached to a bare executable, so the first time a copy downloaded with a browser runs, macOS looks the ticket up online — that first run needs a network connection.
Releases up to 0.17.0 carried an unsigned copy instead, which macOS refuses with "ys" Not
Opened when it was downloaded with a browser. Either download it with curl, or clear the flag:
xattr -d com.apple.quarantine ys
A copy installed this way does not update itself.
When the Floor Manager runs it
The Floor Manager is started with YARDSORT_COORDINATOR set. While that
variable is set, ys enforces Floor Manager permission from Settings: read only refuses a
start or a write, ask first (the default) waits until the window records Allow, and trusted runs
the ones that are not destructive. ys workspace delete (with or without --force),
ys task close and ys attach are refused at every level. Your own ys, without that
variable, is not gated. A shell command that is not ys is outside the gate. So is editing
settings.toml so the level is trusted, and ys --data-dir pointed at a profile you made
up. See What it may do.
Commands
Run ys --help, or ys <command> --help, for the full list. Every command takes --json, which
prints a machine-readable version instead of a table.
ys project list
The repositories Yardsort knows about, with how many workspaces each has.
NAME WORKSPACES PATH
yardsort 3 /home/you/projects/yardsort
ys project add <path>
Adds a git repository as a project, as the app's Open project does: a folder inside a repository
adds the repository's root, and one already known is said and left as it is. A folder that is not a
repository is refused; ys does not make one.
$ ys project add ~/src/my-service
Added my-service, at /home/you/src/my-service.
It is how a computer with no screen gets its projects.
ys workspace list
Every workspace, including each project's own local checkout. --project <name> narrows it to
one project and --all includes archived ones. With --json each entry carries a kind, which
is local for a project's own checkout and worktree for one Yardsort made.
ys workspace new <project> "<prompt>"
The main one. Creates a branch and a worktree, then starts an agent in it with your prompt as its first message — the same thing the composer does in the app.
ys workspace new yardsort "fix the flaky login test"
created fix-the-flaky-login-test
branch ys/fix-the-flaky-login-test
path /home/you/yardsort/yardsort/fix-the-flaky-login-test
agent claude (a49add8f)
It keeps working after this command returns. Open Yardsort to watch.
| Option | What it does |
|---|---|
--base <branch> | Branch to start from. Default: the repository's default branch. |
--harness <id> | Which agent to run. Default: the first one found on your PATH. |
--model <model> | Model, for harnesses that take one. |
--effort <level> | Effort or thinking level, for harnesses that take one. |
--no-agent | Create the branch and worktree and start nothing. |
The project can be named or given by id. If the harness you asked for is not configured or not installed, nothing is created at all — no branch, no folder, no record.
If Yardsort is open on the same profile, the workspace shows in the sidebar as soon as the agent prints anything, with the agent in a tab; the tab stays in the background, so whatever you are looking at stays on screen. If it is not open, both are there when it next starts.
ys workspace delete <workspace>
Removes the folder and forgets the workspace, including its session history. The branch is
kept — commits are never thrown away, same as Delete workspace
in the app. Delete the branch yourself with git if you want it gone. A project's own local
checkout cannot be deleted.
ys workspace delete fix-the-flaky-login-test
deleted fix-the-flaky-login-test
branch ys/fix-the-flaky-login-test (kept)
path /home/you/yardsort/yardsort/fix-the-flaky-login-test
The workspace can be a name or an id from ys workspace list --json. A name that matches more
than one workspace is refused, and the ids are printed so you can say which one. Archived
workspaces are included: deleting one removes it for good.
Uncommitted changes and untracked files are refused, and nothing is removed. They live only in
the folder, so there is no way back to them. --force is the confirmation that they should go:
ys workspace delete fix-the-flaky-login-test --force
A process that is already running in the workspace is not stopped. That is what lets a harness
delete the workspace it is standing in and still finish; the folder disappears underneath it and
the command returns. The branch is there either way. ys steps out of the folder before removing
it. On Windows a folder that is still some other program's current directory — the agent or shell
that launched the command — cannot be removed, and nothing is deleted.
ys workspace handoff <workspace>
Prints the handoff packet for a workspace: what Yardsort recorded there — the task, where the
branch stands and who wrote each changed file, what each agent run did, and what is not known —
written as the next agent's first message. In a project that shares its agents' conversations it
also says what was said in them, as ys workspace context would, within 16,000 characters. The same text the app's Hand off… button starts
from (see handing work to another agent),
without Assist's ordering of the files, which the command line has no key for.
ys workspace handoff fix-the-flaky-login-test
ys workspace handoff fix-the-flaky-login-test > handoff.md
The workspace can be named or given by id. --json gives { "text", "runs", "events" }.
Nothing is started: pipe the text where you want it, or paste it as an agent's first message.
ys workspace fork <workspace> "<prompt>"
Forks a workspace: a new workspace on a new branch made from its branch, in its own worktree, with an agent started there — what Fork into new workspace… in the app's workspace menu does (see Fork into new workspace…). Your prompt is the new workspace's task and names it. After it, the agent gets the workspace's handoff packet worded for a fork: that its commits are the new branch's history and its uncommitted files are not, what it was asked, what its agents did, and the project's memory when the project shares it.
ys workspace fork fix-the-flaky-login-test "add a retry to the login request"
created add-retry-login-request
from fix-the-flaky-login-test
branch ys/add-retry-login-request
path /home/you/yardsort/yardsort/add-retry-login-request
agent claude (5c01e2b7)
It keeps working after this command returns. Open Yardsort to watch.
1 file uncommitted in fix-the-flaky-login-test stayed there: a fork starts from the commits.
| Option | What it does |
|---|---|
--harness <id> | Which agent to run. Default: the first one found on your PATH. |
--model <model> | Model, for harnesses that take one. |
--effort <level> | Effort or thinking level, for harnesses that take one. |
--no-agent | Create the branch and worktree and start nothing — nothing of the packet is sent anywhere. |
--print | Write the message the agent would be given — your prompt, then the packet — and create nothing. |
The workspace can be named or given by id. A workspace that is not on a branch (a detached
checkout) cannot be forked, and the command says so. Files changed and not committed stay where
they are; commit them there first to bring them along. --json gives what ys workspace new
does, plus forkedFrom and leftUncommitted; with --print, { "text", "branch", "uncommitted" }.
ys workspace context [workspace]
What was said in a workspace's other conversations, for an agent joining the work: every message you typed and the agent's reply at the end of each turn, newest turn first, read from each agent's own transcript. Tool calls, their output and the agents' reasoning are left out. See what agents can read of each other.
ys workspace context # the workspace this is run in
ys workspace context fix-the-flaky-login-test # one by name or id, from anywhere
ys workspace context --conversation 3f2a1b9c # one conversation, by the id it shows
ys workspace context --conversation 3f2a1b9c --turn 12 # one turn whole
ys workspace context --since 2026-10-25T13:00Z # only turns from then on, in UTC
ys workspace context --budget 64000 --json
It answers only in a project that shares its conversations — on unless you untick Share conversations between this project's agents in the Memory view — and otherwise says so. Run by an agent Yardsort started, it leaves out that agent's own conversation.
The digest fits in --budget characters (32,000 by default, about 8,000 tokens): each
conversation's first message, its task; then its newest five turns, whole when they fit; then
older turns, shortened, newest first. What did not fit is listed by turn number, and --turn
shows any one of them whole — the message and everything the agent wrote in that turn, its
commentary between tool calls too, still without the tool calls. --turn needs --conversation
when there is more than one. --json gives { "conversations": [{ "id", "harness", "model", "startedAt", "lastTurnAt", "running", "forkedFrom", "turnCount", "turns": [{ "n", "at", "user", "reply", "shortened" }], "omitted", "unreadable" }] }, or, with --turn, that one turn with
everything the agent said.
Every built-in agent's conversations are read: Claude Code, Codex, Grok, Cursor, OpenCode, OMP and pi. A custom agent's is listed with the reason it is not there.
ys session list
Agent conversations. Running ones by default; --all includes those that have ended, and
--workspace <name> narrows it to one.
ID WORKSPACE HARNESS STATE TITLE
6051993d fix-the-flaky-login-test claude running fix the flaky login test
The state column compares two things, because they can disagree:
| State | Meaning |
|---|---|
running | The record says running and the daemon confirms the process is there. |
gone | The record says running but the process is not — it died with nobody watching. Yardsort settles the record the next time it starts, or when you resume it. |
running? | The record says running and there is no daemon to ask. |
ended | The conversation finished, and the record says so. |
ys session resume <session> and ys session fork <session>
Continue a conversation in a new terminal, as Resume and Fork do in the app: name it by its
id, or the start of one, from ys session list --all.
ys session resume 6051993d # the same conversation, after its agent ended
ys session fork 6051993d # a copy, running or not, that goes its own way
Resume keeps the session's record and its id; it refuses one that is still running. Fork
starts a session of its own, recorded as forked from that one. Either starts in the session's
workspace with its agent, model and effort, keeps running after the command returns, and prints the
id to ys attach it by. Both need the terminal daemon, which they start if it is not running, and
refuse, saying why, when it cannot be: an agent started without one would end with the command. A
session that says it is running though its process went with the daemon (gone above) is settled
first, and then resumes; when the daemon cannot say whether it is running, nothing is changed and
the resume is refused, saying why.
They work for an agent that can continue a conversation: one Yardsort gave an id, such as Claude Code, or the most recent one in its folder, such as Codex. When one cannot, they say why, as the app does.
ys attach [target]
Puts a running session on your terminal: the screen is repainted where it got to, and what you
type goes to the agent. Ctrl-] detaches, and the agent carries on — detaching is not
stopping, exactly as closing the Yardsort window is not stopping.
ys attach # when only one thing is running
ys attach fix-the-flaky-login-test
ys attach 6051993d # the start of an id from `ys session list`
With nothing named it attaches to the only running session, and asks which one you meant if there
is more than one, listing each with an id to name it by. A workspace's name picks its agent when it
has one; when two agents share a workspace, name one by the id ys session list prints. A shell
has no workspace name or record, so reach it by the id that list of choices gives.
Attaching matches the session to your terminal's size, and follows it if you resize the window.
If the app has the same session open in a tab, that tab's size and yours are the same setting —
whichever changed last wins, and the app sets it again when you next focus the tab. --no-resize
leaves the size alone, at the cost of a program drawing to a width you cannot see.
You can attach to a session the app also has open; both see the same output, and either can type. When a program asks its terminal something — where the cursor is, or which colours it uses — only the one attached last answers, so the program hears one answer; while you are attached, that is your terminal, not the app's. Only sessions that are still running can be attached to.
ys logs [target]
Prints what a session has on its screen, without taking the terminal over — including sessions
that have finished, which is the one thing attach will not do.
ys logs # the only session, if there is one
ys logs fix-the-flaky-login-test
ys logs 6051993d # the start of an id from `ys session list`, as for attach
ys logs --lines 20 # just the end of it
ys logs --json # the text as a JSON field, for scripts
ys logs --raw # escape sequences and colours, exactly as the app would repaint
Without --raw the screen is replayed through a terminal emulator and handed back as plain text,
so it can be read, grepped or piped. Scrollback comes too, as far back as the session kept it.
Screens live in the background process, not in the database. It stops once nothing is
connected and nothing is running — so a finished agent's last screen is readable while Yardsort
is open, or while other agents are still working, and gone a short while after the last of them
stops. ys logs says so rather than reporting an empty screen. Nothing is written to disk: a
screen can hold anything the agent printed, and Yardsort does not keep a copy of that.
ys activity list
The newest recorded activity: when each agent, shell or run command started in a
workspace and how it ended, newest first. --workspace <name> narrows it to one workspace,
--limit <N> changes how many rows (50 by default), and --json prints the same rows as a JSON
array with the event's full payload.
WHEN WORKSPACE EVENT SOURCE DETAILS
2026-09-24 20:44:15Z fix-the-login process.exited yardsort/lifecycle exit 0, via spool
2026-09-24 20:44:02Z fix-the-login tool.completed claude/hook Edit src/login.rs, 12 ms
2026-09-24 20:43:59Z add-a-footer usage.reported codex/session_file 29842 tokens
2026-09-24 20:43:41Z rename-the-cli tool.completed opencode/plugin write src/main.rs
2026-09-24 20:43:12Z tidy-the-tests approval.resolved grok/session_file run_terminal_command, allow, waited 4210 ms
2026-09-24 20:43:05Z add-a-footer turn.completed omp/extension 19963 tokens
2026-09-24 20:42:50Z rename-the-cli file.reported_write cursor/hook src/main.rs
2026-09-24 20:43:58Z fix-the-login process.started yardsort/lifecycle claude, opus, reporting via hook
Rows from claude/hook, codex/session_file, opencode/plugin, grok/session_file,
omp/extension, pi/extension and cursor/hook are what the agents themselves reported or
recorded, when
capture is on for them; the rest is what Yardsort saw.
Any ys command that reads the daemon first takes the exits it kept while nothing was
connected into the database, so a session list after an agent finished on its own says ended
rather than gone.
ys memory
A project's memory: short lessons for its agents, which you approve in the app. Meant as much for the agents Yardsort starts as for you — any of them can run it.
ys memory list # approved entries, newest first
ys memory search timezone tests # approved entries containing every word
ys memory propose "The tests need TZ=UTC."
Run inside a workspace, it is about that workspace's project; elsewhere, name it with
--project <project>. list and search answer in a project that shares its memory with its agents — which it does unless you turned the switch in the Memory view off — and say so otherwise; propose works either way. propose adds a proposal for you to review in the Memory view and says
so; when an agent Yardsort started runs it, the proposal records which agent and which
workspace. There is no command to approve, edit, reject or revoke: those are yours, in the app or
with yardsort-host memory at a terminal of your own, because an
agent can run anything ys offers. A note synced from another computer is listed with the rest,
cited with that computer's name. --json works as everywhere.
ys sync status
Which projects sync with your other computers, and how the last pass went:
NAME SYNC
widgets syncing
gadgets waiting
On your other computers, in widgets:
fix-login on Build box ys/fix-login #91 (4b3c2d1e)
Last synced: 2m ago
Under the projects, each synced project's workspaces on your other computers: name, computer,
branch, the tasks it was started from, (archived) when it is, and the start of its id. Checking one out here is yours, in
the window or with yardsort-host sync checkout. A project's state is syncing, waiting (to reach the server), removing (from the server) or
refused, with the server's reason. A problem with the last pass, and how many changes wait to go
up, are shown when there are any. With Remote off it says so. It reads the records only, and that
is all ys offers of sync: turning a project on, linking, stopping and removing are yours, in the
app's Project settings or with yardsort-host sync at a
terminal of your own, because an agent can run anything ys offers.
ys task
A project's tasks — its GitHub issues — as the Tasks view lists them. Meant as much for the agents Yardsort starts as for you: it is how an agent answers what is open? and which of these need an answer?
ys task list # open tasks, most recently updated first
ys task list --needs-answer # the ones waiting on a maintainer
ys task list --state all --label bug --assignee @me --author grace --search "worktree" --limit 20
ys task show 91 # one in full: description and conversation
ys task start 91 --print # the message an agent would be given; nothing is made
ys task start 91 # a workspace and an agent on it, started from the task
ys task create "Title" --body "…" # open a new one — see below
KEY STATE UPDATED AUTHOR LABELS TITLE
#92 open, needs answer 2026-10-02 grace bug Worktrees on a network drive are slow
#88 open 2026-10-01 ada enhancement Document the daemon's socket
Run inside a workspace, it is about that workspace's project; elsewhere, name it with
--project <project>. --state is open (the default), closed or all. --label can be
given more than once and asks for all of them; --assignee and --author take a login or
@me, which is whoever gh is logged in as; --search looks in titles, and finds a number
with or without its #. What needs an answer is the
rule the app uses, from the same code.
show takes 91, #91 or the issue's URL — a URL of another repository's issue is refused,
not answered with this project's issue of that number — and prints its state, labels, assignees, the
description as it was written and the conversation, oldest first, with maintainers and bots
marked. A comment hidden on GitHub is printed as hidden, not as its text.
With --json, list prints an array of tasks — key, url, title, state, closedAs,
author, labels, assignees, comments, createdAt, updatedAt, needsAnswer,
linkedPullRequests — and show prints { task, body, comments }.
It asks gh each time it is run and keeps nothing, so it needs the
GitHub CLI installed and logged in, and does not need the app. It
reads what the app reads: every open issue up to the 200 most recently updated, and the 50 most
recently updated closed ones. When a repository has more, or part of a list could not be read,
it says so on standard error — beside the answer, so a script reading the JSON can still tell.
start is ys workspace new with the first message
written from the task — the same message the app's Delegate puts in the composer, described
in Tasks — the workspace named after the task
(91-worktrees-network-drive), and the task recorded against it. It takes the same --base,
--harness, --model, --effort and --no-agent, and prints the same thing with a task
line. A closed task is refused, and so is a link to another repository's issue; nothing is
created in either case. There is no composer in a terminal, so the message is not shown
before the agent starts. ys task start 91 --print writes the message an agent would be
given and stops — nothing is created or started — so read that first when someone you do not
know wrote the issue; with --json it is { prompt, task }. The mark on the message's two
lines is made anew each time, so the one a later start sends differs in that and in nothing
else, unless the issue changed in between.
ys workspace list --json says which task each workspace was started from, in tasks.
The rest write to GitHub, at once and as whoever gh is logged in as:
ys task create "Crash on start" --body "It crashes." --label bug --assignee @me
ys task create "Crash on start" --body-file notes.md # or --body-file - for standard input
ys task comment 91 "Which version is this?" # or --body-file
ys task edit 91 --add-label bug --remove-label question --assign @me --unassign grace --title "…"
ys task close 91 --reason not-planned --yes # completed, unless --reason says
ys task reopen 91 --yes
create prints the new task's key and link ({ key, url } with --json). An issue is public
the moment it is created, and a comment notifies everyone following the task: there is no list
of proposals to approve first, as there is for memory. An agent that runs these
has its own permission prompt in front of them, and that is the gate.
close and reopen do nothing without --yes: they say what they would close or reopen — the
key, the title, who opened it — and exit with an error, so neither can happen as a side effect
of a command run to look. A task that is already closed, or already open, is refused either
way.
A description or a comment is handed to gh on its standard input, never as an argument, so
its length and its characters do not matter. A link to another repository's issue is refused
before anything is written.
The issue text it prints was written by whoever opened or commented on the issue. An agent reading it should treat it as a description of work, not as instructions.
ys pr
The open pull requests of every project on GitHub, read through gh as the
Pull requests view reads them, and a workspace on one for reviewing it.
Nothing is written to GitHub. A workspace's pull requests in
other repositories are followed with ys pr track.
ys pr list # every project's open pull requests, most recently updated first
ys pr list --project api-gateway # one project's
ys pr list --attention # only those that need attention (below)
ys pr list --reviews none # nobody has reviewed it yet
ys pr checkout 12 --project api-gateway # a workspace on #12's branch, to review it in
PROJECT PR STATE REVIEW CHECKS AUTHOR ATTENTION TITLE
web #48 open review required passing 12/12 grace not reviewed Add a retry to the uploader
web #45 open changes requested failing 10/12 ken checks failing, changes requested Tidy the settings page (in tidy-settings)
A pull request with a Yardsort workspace on its branch says which, after its title.
| Option | What it does |
|---|---|
--project <name> | One project, by name or id. Default: all of them. |
--reviews <how> | The view's review filter: none, required, approved, changes, by-me, not-by-me, awaiting-me. Me is whoever gh is logged in as. Your own pull requests are not counted as ones you have not reviewed, and a review asked of a team you are in is not counted as asked of you. |
--attention | Only those with a reason in the ATTENTION column: failing checks, conflicts with the base, changes requested, your review asked for by name, or no review at all on one that is not a draft. |
--author <login> | Only those opened by this login. @me is whoever gh is logged in as. |
--no-drafts | Leave drafts out. |
--limit <n> | At most this many. |
Up to 200 open pull requests are read per repository, as in the view. A project that cannot be read
— not on GitHub, no remote, its folder missing, gh failing — is named on standard error, and the
others are still listed. With --json, each pull request carries its reviews, reviewRequests,
checkCounts, mergeable, workspace, and attention as a list of checksFailing, conflicts,
changesRequested, awaitingYou and unreviewed.
checkout fetches the pull request's branch from the project's remote and opens a workspace on
it, as the view's Start workspace does: no new branch, and no agent started. A branch that
is already here is opened as it is, and it says how far behind it is. One from a fork is
pr/<number>, following the pull request. If a workspace already has the branch, checkout says
which and makes nothing, but it still fetches the pull request and says how many commits the
workspace is behind it, so a second review does not read old code unnoticed. The workspace is
left as it is. With --json, existing is true and behind the count, or null when the
remote could not be reached, with the reason on standard error. A merged or closed pull request is refused. Then
ys workflow run code-review --workspace <name> has an agent review it. That does not work yet for
a pull request from a fork, because the review finds a pull request by its branch name. It is how
the Floor Manager reviews other people's pull requests.
Pull requests in other repositories
track, tracked and untrack are about pull requests a workspace follows in other
repositories — one an agent opened in a nested clone inside a parent project's folder, say. A
project's own pull requests need nothing from here: Yardsort finds them by their branch. See
Pull requests in other repositories.
ys pr track https://github.com/owner/lib/pull/12 # follow it with this workspace
ys pr tracked # the ones this workspace follows
ys pr untrack https://github.com/owner/lib/pull/12
Tracking https://github.com/owner/lib/pull/12 with bump-the-client. Yardsort shows its checks and reviews beside the workspace's own.
Run by an agent Yardsort started, it is about that agent's workspace — even from a folder outside
the worktree, such as the nested clone the pull request was opened in — and records which
conversation opened it. Elsewhere it is the workspace whose folder it runs in, or name one with
--workspace <workspace>. Tracking the same link twice changes nothing. A link that is not a
GitHub pull request is refused, and so is one of the project's own repository. The app shows a
newly tracked one the next time it asks about the project: within a minute, or when its window
comes back into focus. --json works as everywhere.
ys workflow
The workflows Yardsort knows: the built-in ones and the files in your profile's
workflows folder.
ys workflow list # every workflow, whether it is ready, and where it comes from
ys workflow show code-review # the file that would be used, then any problems on stderr
ys workflow copy code-review # your own copy to edit, used instead of the built-in
ys workflow validate fix-ci.yaml # each problem as file:line:column: message; exit 1 if any
ys workflow validate - # the same, reading the file from standard input
ys workflow save fix-ci.yaml # check it, then write it into your folder; refused with problems
ys workflow run ping --workspace fix-login --input note=hi # queue a run; Yardsort must be open
ys workflow run ping --project app --name nightly-ping # the same, in a new workspace made for it
ys workflow runs # runs, newest first, with WAITING ON and PRS columns
ys workflow runs --run 3f2a9c1e # one run: its result, pull requests, steps, artifacts, approvals
ys workflow approve 3f2a9c1e sign-off --feedback "ship it"
ys workflow reject 3f2a9c1e sign-off
ys workflow request-changes 3f2a9c1e sign-off --feedback "split the migration"
ys workflow ask --question "What should the timeout be?" # from the workflow's agent
ys workflow summary --text "The timeout should be 30 seconds."
ys workflow answer 3f2a9c1e discover --text "30 seconds" # you, not the agent; asks for the code
ys workflow cancel 3f2a9c1e # stop a run; agents it started keep running
ys workflow continue 3f2a9c1e # take a failed run up again from the step that failed
ask and summary are how an agent in a clarifying step talks to you. They find the
step from the session Yardsort started, or you name --run and --step. A question
only printed in the terminal is not asked. answer is yours: a session Yardsort started
cannot use it, and neither can the Floor Manager. It asks for the one-time code shown in
the window and in the notification, the same way approve does. Leave --code out to
type it with echo off, or pass --code - and the code on standard input. The window does
not ask for the code. The same session receives the answer. summary is refused while a question is still waiting for an answer. A clarifying step finishes
when the agent records summary, or when until: exited and the session has ended
with no question still open. Going quiet does not finish it. A session that ends
with no summary fails the step.
See Asking a question.
copy writes into the workflows folder and never overwrites; --as <new-id> makes a second
workflow instead of a replacement. save checks a file and, only when it has no problems,
writes it into the folder: over your own file with the same id, wherever that file is; as your
copy of a built-in when the id is a built-in's; otherwise as a new <id>.yaml. It reads
standard input for -, except from the Floor Manager at ask first, where the file must be named
so the confirmation can show it. An open Yardsort window shows the change within a second or
two. validate needs no profile, so it works on any machine, in CI, or on a file an agent has just
written. list also prints where the workflows folder is.
run checks the workflow, the workspace and every input before it queues anything, and refuses
while Yardsort is closed, because the app is what carries runs out. It refuses on a
computer with no screen too, where yardsort-host has the
profile and carries no runs out yet; so do ys test run and ys schedule run. Inside a workspace's folder,
or in an agent's terminal there, --workspace can be left out. It prints the run's id and
returns at once. A workflow that names {{ pr.* }} before any wait_pr_activity needs the
GitHub CLI (gh), logged in, and an open pull request for the workspace's branch. One whose
{{ pr.* }} steps all come after that wait can start before the pull request exists; the run
looks again. gh not answering refuses either, and a workflow about a pull request elsewhere
still needs that one. A run id can be shortened to its first characters, as runs prints it.
--json works as everywhere.
continue takes a failed run up again: the step that failed and the steps skipped after it
run again, and the steps that succeeded are kept. It prints the step it continues from, and
with --json the run and every step that will run again. Like run, it needs Yardsort open.
Any run that has not failed is refused, and so is one whose workflow is already running in
that workspace. See Continuing a failed run.
approve, reject and request-changes record your decision on a step that is waiting
for approval. Leave --code out and ys asks at the terminal without echoing, when both
standard input and standard error are terminals. Otherwise it fails at once: pass
--code - and pipe the code in. On Windows the prompt needs cmd, PowerShell, or Windows
Terminal. Git Bash and mintty use --code -. --code - reads one line from standard
input. --code <code> warns, because the code stays in your shell history and in the
process list. runs does not print that code. Yardsort does not have to be open: a
correct code is stored, and the app applies it once on its next tick. Five wrong codes
stop ys until the app shows a new one, and a restart does not clear that. --feedback is a note. It is
required for request-changes. A decision is recorded once, and one on a run that has
already ended is refused. A session Yardsort started cannot use these, and neither can the
Floor Manager. This is not a sandbox: a process running as you that writes the database
directly is not stopped. The plain list has a WAITING ON column. runs --run <id> says
Blocked: waiting for your approval. when it is, shows a step that is still waiting, the
artifacts it reads, and the decision once it is recorded. --json includes waitingOn,
pendingApprovals and decisions, and not the code. See
An approval. See
Running a workflow,
Requesting a code review, and
The software factory.
ys test
A workspace's smoke tests: the .yaml files in its worktree's
.yardsort/tests folder.
ys test list # the tests in this workspace, whether each is ready, and where they are
ys test list --workspace fix-login
ys test show health # the file that would be used, then any problems on stderr
ys test validate health.yaml # each problem as file:line:column: message; exit 1 if any
ys test validate - # the same, reading the file from standard input
ys test example # a complete, valid test to start from
ys test guide # the file format, written for an agent
ys test run health # queue a run in this workspace; Yardsort must be open
ys test run health --workspace fix-login --input user=demo@example.test
ys test wait 8c1d # block until the run ends, print the verdict; exit 0, 1 or 2
ys test wait 8c1d --timeout 5m
ys test runs # runs, newest first; --workspace narrows, --run 8c1d shows one
ys test log 8c1d # the first failed step's output, or the last step's
ys test log 8c1d --step server --stderr
ys test cancel 8c1d # stop a run; a running one tears down first
list, show and run read the worktree of the workspace this is run in, or in an agent's
terminal there, so --workspace can be left out inside one; outside, name it. validate,
example and guide need no profile, so they work on any machine, in CI, or on a file an agent
has just written. --json works as everywhere; list --json says for each test whether it is
runnable and whether it usesBrowser.
run queues the run and returns at once with its id. Yardsort must be open: the app carries runs
out, and a run of a file you have not approved in the app waits there first, on a card at the
top of the workspace — run says so, and there is no way to approve from here. wait blocks until the run ends and prints the verdict
the way an agent can act on it: the status, the step that failed and why, and the last lines of
any server the test started. It exits 0 when the run passed, 1 when it failed and 2 for anything
else — cancelled, refused, errored, or still going when --timeout (20 minutes unless said)
passed. log prints what a step's process wrote, or the body an http step got; --json gives
the file's path and the step's outputs instead. A run can be named by the start of its id, as
runs prints it. See Smoke tests.
ys schedule
Schedules: standing instructions to start a workflow or a smoke test, once at a set time or again and again.
ys schedule list # every schedule: what it runs, where, when, next time, last result
ys schedule add --test login --workspace local --weekly mon-fri 09:00
ys schedule add --workflow code-review --workspace fix-login --input reviewer=codex --daily 18:30
ys schedule add --test login --at "2026-11-06 18:00" # once
ys schedule add --workflow ping --every 2h # 15m, 2h, 1d
ys schedule add --test login --monthly last 06:00 # a day from 1 to 28, or last
ys schedule add --workflow nightly --cron "0 3 * * *" --if-missed skip --notify always
ys schedule add --workflow fix-tests --project app --keep 3 --daily 02:00 # a new workspace each run
ys schedule show Nightly # its inputs, its rules, and its next five times
ys schedule pause Nightly # off: keeps its place and its history, fires nothing
ys schedule resume Nightly # on again, from now
ys schedule run Nightly # start its run now; Yardsort must be open
ys schedule runs Nightly # its history: every time it came due and what became of it
ys schedule remove Nightly # the schedule and its history; the runs it started stay
add takes what to run, --workflow <id> or --test <id>, and exactly one way of saying when:
--at, --every, --daily, --weekly, --monthly or --cron. Times are this computer's
local time. --workspace takes a workspace's name or id, and can be left out inside a
workspace's folder or in an agent's terminal there. --project <name> takes its place for a
workflow that should get a new workspace for each run:
--workspace-name says what they are called (the workflow's id otherwise), --base the branch
each starts from (the default branch otherwise), and --keep how many of them may be there at
once, 5 unless you say. At that many, a time is refused until you archive or delete one; show
lists the ones still there. Give each input as --input id=value.
--name names it; otherwise it takes the workflow's or the test's own name. --if-missed is
run-once (the default) or skip, and --notify is failure (the default), always or
never. Everything a run would be refused for is checked before anything is written, and add
prints when the schedule will first fire.
A schedule is named by its name, its id, or the start of its id, as list prints it. --json
works as everywhere.
Schedules fire while Yardsort is open, so add, list, show and resume say so when it is
not. They do not need it open: ys writes the schedule, and the app acts on it within a second
of starting. run does need it, as ys workflow run does. ys cannot approve a smoke test
file, so add --test says when the file has not been approved in the app: its first run will
wait for you there. add --workflow is refused when the workflow runs a smoke test that would
wait for you: see Schedules.
ys trigger
Triggers: standing instructions to start a workflow or a smoke test when something happens in a workspace — an agent says its work is done, finishes a turn or exits, a test or a workflow run ends, something happens on the workspace's pull request, or a custom event is raised.
ys trigger presets # the ready-made triggers, and the question each asks
ys trigger list # every trigger: what it listens for, what it runs, where, how it stands
ys trigger add --preset address-reviews --workspace fix-login
ys trigger add --preset review-when-done --input reviewer=codex --workspace fix-login
ys trigger add --on pr.review --from anyone --workflow address-review --cap 5
ys trigger add --on workspace.done --workflow smoke-then-tell --input suite=login --workspace fix-login
ys trigger add --on agent.settled --new-commits --clean --quiet 3m --test login --session 4c1e
ys trigger add --on test.finished --of-test login --verdict failed --workflow fix-it --cap 2
ys trigger add --on custom.migration-written --test migrations --workspace fix-login
ys trigger show Tell # its events, filters, inputs, limits and last fire
ys trigger pause Tell # off: keeps its history, fires nothing
ys trigger resume Tell # on again; only what happens from now counts
ys trigger reset Tell # lift its cap
ys trigger fires Tell # its history: every fire and what became of it
ys trigger remove Tell # the trigger and its history; the runs it started stay
add takes a --preset from presets, with its one answer as --input, or one or more --on
events — workspace.done, agent.settled, agent.exited, test.finished,
workflow.finished, pr.opened, pr.review, pr.comment, pr.checks_failed,
pr.checks_passed, pr.conflicted, pr.merged, pr.closed, and custom.<name> for what
ys event emit raises — and what to run, --workflow <id> or --test <id>.
--workspace takes a workspace's name or id, and can be left out inside a workspace's folder or
in an agent's terminal there; --session <id> instead makes a trigger that belongs to one agent
session. Give each input as --input id=value. The filters are --new-commits and --clean
for agent.settled, --failed-exit for agent.exited, --of-test <id> and --verdict passed|failed for test.finished, --of-workflow <id> and --outcome succeeded|failed for
workflow.finished, --drafts for pr.opened, --from others|anyone and --no-bots for
pr.review and pr.comment, and --state approved|changes_requested|commented for
pr.review. --quiet 2m waits that long after the last event before starting the run (two
minutes by default for reviews and comments), --cap is how many runs it may start before it
stops (3 by default), and --notify is failure
(the default), always or never. Everything a run would be refused for is checked before
anything is written. A trigger on a pr.* event reads the workspace's pull request with gh as
it is saved, so that what is on it already is not news, and says which pull request it watches.
One whose workflow is about a pull request elsewhere (context: tracked_pull_request, such as
code-review-elsewhere) reads, and watches, each one the workspace tracks with
ys pr track instead, and takes only pr.* events: see
Pull requests elsewhere.
A trigger is named by its name, its id, or the start of its id, as list prints it. --json
works as everywhere. Triggers fire while Yardsort is open, so add, list, show and resume
say so when it is not; ys writes the trigger either way, and the app listens within a second
of starting.
ys workspace done
Says the work in a workspace is committed and ready to be looked at, for a
trigger on workspace.done. An agent runs it in its own terminal;
elsewhere, run it in the workspace's folder or give --workspace <name>.
ys workspace done
ys workspace done --note "Login validates on blur; tests added."
--note is passed to what the trigger starts as {{ event.note }}. It prints whether a trigger
there listens for it. --json gives { workspace, workspaceId, head, note, heard }.
ys event emit
Raises a custom event in a workspace, for a trigger on
custom.<name> there. An agent, a smoke test's run step, a script or you run it in the
workspace's folder; elsewhere, give --workspace <name>.
ys event emit migration-written
ys event emit migration-written --note "0042 adds users.last_seen"
A name is lowercase letters, digits, - and _, starting with a letter or a digit;
custom.migration-written is taken too. --note is passed to what the trigger starts as
{{ event.note }}. It prints whether a trigger there listens for that name, and when none does,
the names they listen for. Run from a smoke test's run step, a run it starts counts one step
further along a chain. --json gives
{ event, workspace, workspaceId, head, note, heard, listenedFor }.
ys activity export
Every recorded event as NDJSON on stdout — one JSON object per line, oldest first, with the
same fields --json shows. --workspace <name> narrows it. Pipe it wherever you like; nothing
else exports it.
ys doctor
Where ys is looking and whether it can get there: the data directory, the database, the daemon,
which agents are on your PATH, how much activity is recorded, and where the exit spool and the
agents' inbox are and whether anything is waiting in them. The first thing to run when ys and
the app seem to disagree.
Profiles
ys looks for the same data directory the app uses. --data-dir <dir> points it at another one,
which is how you reach a throwaway profile:
ys --data-dir /tmp/ys project list
YARDSORT_DATA_DIR works too, as it does for the app.
ys never creates a database. If it cannot find one it says which path it tried, rather than
starting an empty one and telling you that you have no projects — see
Troubleshooting.