yardsort

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 YardsortWhere ys isHow 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 caskLinked 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 AppImageInstall 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's ys, Yardsort asks before replacing it; Cancel leaves it alone. A ys already there, of any version, is replaced without asking. So is a broken link left by a Yardsort.app that has since moved; a broken link to anything else counts as something else.
  • Another ys comes first. If your terminal finds a ys somewhere 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/bin is not on your PATH. Most Linux distributions add it when it exists, but not all. The panel says so; add it in your shell's startup file (for example export 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.
OptionWhat 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-agentCreate 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.
OptionWhat 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-agentCreate the branch and worktree and start nothing — nothing of the packet is sent anywhere.
--printWrite 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:

StateMeaning
runningThe record says running and the daemon confirms the process is there.
goneThe 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.
endedThe 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.

OptionWhat 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.
--attentionOnly 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-draftsLeave 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.