switchyard

for agents: this page is markdown at https://switchyard.so/docs/cli.md; every page is listed in llms.txt.

The yard CLI

Switchyard: many coding agents on one codebase, with tasks, plans, warnings and undo.

Install it with one line, then sign in: curl -fsSL https://app.switchyard.so/install.sh | sh and yard login https://app.switchyard.so --github. This page is rendered from the CLI's own command definitions, so it says what the installed yard says: every command at every level but the ones only Switchyard's own team runs, with its arguments, flags, examples and exit codes, and who may run it from the parity page's route table.

For agents

Who may run a command

A command with no Who line is a group of commands that each carry their own, or has no line yet: yard agent setup, yard agent run, yard api and yard completions.

Global flags

Every command takes these.

FlagMeaning
--jsonPrint machine-readable JSON
--color <WHEN>Colour output (NO_COLOR and non-terminals turn it off in auto); one of auto, always, never; default auto
--project <ID>Project id (default: SWITCHYARD_PROJECT or .git/yard.json)
--no-inputNever ask a question or open an editor, even at a terminal: a command that needs an answer fails instead (also YARD_NO_PROMPT=1)

Exit status

Every command exits 0, 1 or 2. 6, 8, 10 and 11 can end any command that meets what its line says. A command lists the other codes its help names.

  0  success
  1  the command failed; the error's code says why, and --json prints it on stdout
  2  usage error: an unknown command, flag or argument
  3  yard submit --wait: the merge queue sent the task back, or a push or an undo withdrew it
  4  yard submit --wait: the task was abandoned
  5  yard submit --wait: the task had not merged when the wait ended; yard engine wake --wait: the Git engine was still waking after 5 minutes (error code timeout)
  6  new work refused at the spending limit: the organization's grace is over, nothing was taken (error code spending_limit); raise the limit on the billing page the message names, then send it again
  7  yard submit --wait: the task is held at the spending limit: it keeps its place and merges once a person raises the limit (error code spending_limit_held); the message names who can
  8  an approval is needed: yard login --complete before the sign-in is approved (error code approval_pending; approve it at the link, then check again), or an act a person does in a browser, such as inviting someone, making an organization or an organization key, removing a member or confirming an approval yard sent (error code approval_required); open the link the error prints, signed in as yourself
  9  yard status --watch: the live feed was lost and neither it nor a read of the status answered again for 10 minutes (error code feed_lost); --once and Ctrl-C end a watch with 0
  10 new work refused for want of a card: hosted Switchyard's organization has no card on file, nothing was taken (error code card_required); an owner, admin or billing member adds one on the billing page, then send it again
  11 a push met an outage (Switchyard could not be reached, or answered 502, 503, 504 or a Cloudflare 52x) and is queued on this machine, not failed (error code push_queued): keep working; the next yard command that talks to Switchyard, or yard push --queued, sends it

Commands

CommandWhat it does
yard loginSign in to a Switchyard with GitHub (or, for scripts, a key on stdin) and save it in ~/.config/yard/config.json
yard whoamiWho the configured key belongs to: a signed-in person and their teams, or a project or task
yard logoutSign out: revoke a GitHub sign-in on Switchyard and forget the key
yard initConnect this repository to a project, creating it (optionally importing a repository)
yard setupSet a GitHub repository up as the board's set-up page does: its App installations, repositories, drafted checks and rules, then apply them (signed in)
yard setup githubThe Switchyard GitHub App, its install link and the installations you can use
yard setup reposThe repositories of one installation, a page at a time or by search
yard setup analyzeWhat setting a repository up would do: the checks drafted from its CI, the rules, its protection and what exists
yard setup applySet a repository up with a plan: commit the rules and workflow changes, or open a pull request
yard setup checks-onChoose where a project's checks run: Switchyard's machines or the repository's own GitHub Actions
yard branchStart a task in its own checkout: yard branch new "<task>"
yard branch newCreate a task and check it out
yard branch listList the active tasks, or the merged and abandoned ones newest first
yard branch openCheck out an existing task to fix it yourself, with your own key, for example one sent back whose agent has stopped
yard branch keyReplace a task's key when it may have leaked: the old key and its Git access stop at once, and the new key is printed once (project admins only)
yard agentSet up coding agents to work with Switchyard
yard agent setupWrite a Switchyard skill for coding agents and an MCP config entry
yard agent runStart a coding agent with this task's key in SWITCHYARD_TOKEN, read from .git/yard.json (yard agent run -- claude)
yard copy-againCopy the followed GitHub repository into Switchyard again, after the first copy failed (project admins only)
yard copy-historyCopy the followed repository's history behind main, or cancel that copy (project admins only)
yard engineThe project's Git engine: wake it ahead of work (project admins only)
yard engine wakeWake the project's Git engine, so the first push, clone or check does not wait while it loads the repository from storage (project admins only)
yard planWrite or update the task's plan ($EDITOR, --file or stdin JSON)
yard claimSay which paths and symbols the task will touch, beside its plan, and read what overlaps with them
yard statusGraph of main, tasks, stacks and warnings, plus local changes with short ids to commit by
yard commitCommit chosen files or hunks by the short ids yard status shows (f3a9c, h52e1, ...)
yard pushSend the pushes queued on this machine while Switchyard could not be reached, oldest first
yard absorbFold working-tree changes into the commits they belong to
yard splitSplit paths out of a change into a new change
yard squashSquash a change into the change below it, or into --into
yard editAmend a change in the stack with working-tree changes and/or a new message
yard uncommitTake a change (or some of its paths) out of the stack, keeping the edits locally
yard moveStack the task onto another task or main, or move a change within the stack
yard tagSet or remove a task's tags, or print them
yard assignAssign a task to a person, or clear its assignee with none
yard syncBring the newest main, or the task below, into this task; a conflict is recorded in the task and never blocks it
yard warningsWhat overlaps with this task and what to do about it
yard noticeSwitchyard's note on a task: what it last changed, its place in the merge queue, its conflicts and warnings
yard conflictsOpen conflicts in every task with the resolution steps tried, and the ones resolved recently
yard resolveRun conflict resolution for the task's conflicts step by step, or send your own resolution
yard submitSubmit the task to the merge queue
yard reviewReview inbox: list, approve, request a fix or comment
yard review approveApprove the latest version of a change, as a person signed in: where people sign in, no key and no agent's account approves, and an approval that waits for your click in the browser prints its link and exits 8, or with --wait stays until you confirm it
yard review request-fixAsk the agent for a fix; the change waits until a new version is pushed
yard review commentComment on a change
yard prPull requests of the project's GitHub repository in the merge queue: where one stands
yard pr statusWhere a pull request stands in the merge queue: its state, reason code and sentence, the task it is in and its head
yard hotfixMerge a queued task as a hotfix, before the rest of the merge queue (project admins only)
yard priorityMerge a queued task in the priority lane, after hotfixes and before the normal lane (project admins only)
yard abandonAbandon a task, as the board's Abandon does: it leaves the merge queue and the live merge, and its keys stop working
yard logThe task's changes, or the project's history with --ops
yard showA change's versions, the reason behind it and its diff, or what changed between two versions
yard whyTask, agent, plan and prompt behind a file or line
yard undoUndo an action (default: the latest one for this task)
yard verifyCheck the signed merge record of a merged commit: who approved it and which checks passed on it
yard fetchFetch main and its merge records into refs/remotes/switchyard/<branch>
yard checkA check's full log, and turning checks kept in Switchyard off, on or trying them again
yard check logPrint a check's full log; without a name, list the checks whose full log is kept
yard check offTurn checks kept in Switchyard off: they hold no task and run on no test build (project admins only)
yard check onTurn checks kept in Switchyard back on (project admins only)
yard check tryTry checks that are off once more on main: the ones that pass turn back on (project admins only)
yard check triedThe checks' trial on main: each check kept in Switchyard with how it did there, and which are off
yard check shellRun one command in the machine a task's failed check kept, as the check ran; --done ends the machine
yard insightsThe project's numbers over 1, 7 or 30 days: tasks started, merged and sent back, the time to merge, per agent and model
yard queueThe merge queue: its health now, in one sentence and a few numbers
yard queue healthThe merge queue's health now: one sentence, the one thing that needs a person, how long submit to merged takes, how many tasks wait and the share sent back
yard valueWhat Switchyard did for the project over 1, 7 or 30 days, each number counted from its records: changes merged, broken changes kept out of main, conflicts fixed and by which step, check runs not made, flaky checks caught
yard settingsRead the project's settings, or change one: a task key and an agent group key read none, and changing one takes admin access
yard settings setChange one setting; it is recorded in the project's history and yard undo reverts it
yard rulesThe rules and checks kept in Switchyard: print them, or keep a rules file's text
yard rules showPrint the rules and checks kept in Switchyard, as a rules file
yard rules keepKeep a rules file's text in Switchyard, replacing what is kept (project admins only)
yard rules protectList the protected areas the repository has and the rules miss, and add them (team admins)
yard rules uncheckedSay plainly that paths need no check, so a task changing only them merges though no check reads them (project admins only)
yard rules enforceHold a task that changes a file no check tests from now on, before the guard's seven days of watching end (project admins only)
yard pausePause merging on main, during an incident or a release window (project admins only)
yard resumeResume merging after yard pause (project admins only)
yard projectThe project: show it, list yours, keep it from a scheduled deletion, or print the page where a person rotates its admin key or schedules its deletion
yard project showThe project: its name, main branch, remote and the GitHub repository it follows
yard project listList the projects you can see, with their organization, team and your access (signed in)
yard project rotate-admin-keyIssue a new admin key for the project; every earlier admin key stops at once, so it answers a leak: it prints the project's settings page, where a person with admin access rotates it in a browser signed in within 15 minutes (exit 8)
yard project deletionWhether a project is scheduled for deletion, and when
yard project deleteSchedule a project's deletion (owners and admins of its organization): it prints the project's settings page, where a person schedules it in a browser signed in within 15 minutes (exit 8); its owners and admins are emailed and it can be kept until the day comes
yard project keepCancel a project's scheduled deletion
yard webhookThe project's webhook endpoints: list, add, test or remove them (project admins only), and check a delivery's signature
yard webhook listList the endpoints and how their deliveries go, never their secrets (project admins only)
yard webhook addAdd an endpoint; its signing secret is printed once, then the result of a test event sent to it (project admins only)
yard webhook testSend one test event to an endpoint and print its result (project admins only)
yard webhook removeRemove an endpoint and the events waiting for it (project admins only)
yard webhook verifyCheck a delivery's signature on this machine, with no network and no sign-in
yard resolutionsThe conflict resolutions a person made by hand that the project remembers and reuses, or forget one (forgetting needs the admin key)
yard resolutions forgetForget a remembered resolution, so the next conflict like it climbs the conflict steps again
yard groupList agent group keys, the keys many agents share, and revoke one or turn it off; rotating one or turning it back on prints the project's settings page (exit 8), where a person does it in a browser (project admins only)
yard group listList the project's agent group keys, with the tasks each started
yard group createMake an agent group key: it prints the project's settings page, where a person makes it in a browser signed in within 15 minutes (exit 8); the key is shown there once
yard orgYour organizations: members, invitations, API keys and AI fixes (signed in with yard login --github)
yard org listList the organizations you belong to, with your role and plan
yard org createMake an organization with you as its owner: it prints the board's page, where you make it in a browser (exit 8)
yard org membersList an organization's members, their roles and teams, or one team's members
yard org showShow an organization: its name, plan, your role and its teams
yard org teamsList an organization's teams, with their members and projects
yard org teamMake or remove a team, or add a member to a team or take one out (owners and admins): each prints the teams page, where a person does it in a browser (exit 8)
yard org team createMake a team: it prints the teams page, where a person makes it in a browser signed in within 15 minutes (exit 8)
yard org team deleteRemove a team, whose projects become the whole organization's: it prints the teams page, where a person removes it in a browser signed in within 15 minutes (exit 8)
yard org team addAdd a member of the organization to a team; prints the teams page's link, where a person does it in a browser (exit 8)
yard org team removeTake a member out of a team; prints the teams page's link, where a person does it in a browser (exit 8)
yard org renameRename an organization; its slug, in every address, stays (owners and admins)
yard org inviteInvite someone to an organization by GitHub login (owners and admins): it prints the teams page, where a person invites them in a browser signed in within 15 minutes (exit 8)
yard org invitationsList an organization's open invitations
yard org deletedList the projects an organization deleted in the last 30 days, who asked, and until when their data is kept (owners and admins)
yard org keysList an organization's API keys (owners and admins)
yard org auditRead an organization's audit log: who did what, when and from where (owners and admins)
yard org keyAn organization's API keys (owners and admins): disable or revoke one from yard; create, rotate, enable and keep print the teams page, where a person does it in a browser (exit 8)
yard org key createMake an API key: it prints the teams page at the organization's keys, where a person makes it in a browser signed in within 15 minutes (exit 8); the key is shown there once
yard org key rotateRotate a key: it prints the teams page at the organization's keys, where a person rotates it in a browser signed in within 15 minutes (exit 8); the new key is shown there once
yard org key disableDisable a key until it is enabled again
yard org key enableEnable a disabled key: it prints the teams page at the organization's keys, where a person enables it in a browser signed in within 15 minutes (exit 8)
yard org key revokeRevoke a key for good
yard org key keepKeep a key someone made for the team, so it keeps working when its maker leaves: it prints the teams page at the organization's keys, where a person keeps it in a browser signed in within 15 minutes and it becomes theirs (exit 8)
yard org ai-fixesRead whether Switchyard's AI conflict fixes are on, or print the page that turns them on or off (owners and admins)
yard org agent-approvalsRead whether agents may approve work in the organization, or print the page that turns it on or off (owners and admins)
yard org engine-sizingRead whether the organization's Git engines start on a larger machine after many agents worked at once, or keep them small (owners and admins)
yard org ssoRead an organization's single sign-on: its connections, whether it is required, and the DNS records still to add; verify checks a connection's records now (owners)
yard org sso verifyCheck a single sign-on connection's DNS records now; its domains are verified once every record is found (owners)
yard org scimRead an organization's SCIM directory: whether one is paired, with which single sign-on connection, and how many people it holds
yard org two-factorRead an organization's two-factor level, recommended or required, and how its members are covered (owners and admins see the counts)
yard org secretPrint the page where an owner sets or removes an organization's secret, in a browser signed in within 15 minutes (exit 8)
yard org deletePrint the page where an owner deletes an organization, in a browser signed in within 15 minutes (exit 8)
yard org usageThis month's usage: merges, pushes, check seconds and AI suggestions, with the bill so far
yard org valueWhat Switchyard did for an organization's projects over 1, 7 or 30 days, in total and project by project, each number counted from their records
yard org billingA month's bill, line by line and project by project; contacts reads who gets the billing emails, and prints the billing page that changes them (owners, admins and billing)
yard org billing contactsWho gets the organization's billing emails (owners, admins and billing); adding or removing an address prints the billing page, where a person does it in a browser signed in within 15 minutes (exit 8)
yard org limitThe spending limit: what was spent of it, the warnings emailed, the forecast and what it holds; set or remove it (owners, admins and billing, never an agent)
yard org limit setPrint the billing page's link that sets, raises or removes the spending limit, in whole dollars or none; a person confirms it there, signed in in a browser (exit 8)
yard org cardThe card on file, where the organization's payments stand and when the next charge comes; add prints the billing page, where a person adds or changes the card in a browser (owners, admins and billing)
yard org card addPrint the billing page, where a person adds or changes the organization's card in a browser they are signed in to (exit 8); a first card pays the plan's minimum there, otherwise the card is only checked
yard org invoicesThe organization's statements and their invoices: what was charged, when, and what waits for review (owners, admins and billing)
yard org roleChange a member's role (owners and admins): it prints the teams page, where a person changes it in a browser signed in within 15 minutes (exit 8)
yard org removeRemove a member from an organization (owners and admins): it prints the teams page, where a person removes them in a browser signed in within 15 minutes (exit 8); every key they made ends unless kept for the team
yard org leaveLeave an organization: it prints the teams page, where you leave it in a browser signed in within 15 minutes (exit 8)
yard org withdrawWithdraw an open invitation (owners and admins)
yard org invitedList the invitations waiting for you
yard org acceptAccept an invitation waiting for you
yard org declineDecline an invitation waiting for you
yard accountYour own account: where you are signed in, and which emails Switchyard sends you (signed in with yard login --github)
yard account sessionsWhere you are signed in, or sign one of them out; signing out everywhere is done in a browser
yard account sessions endSign out one sign-in by its id; with --all it prints the account page, where you sign out everywhere in a browser you are signed in to (exit 8)
yard account emailsWhich emails Switchyard sends you, or turn one kind on or off
yard account emails setTurn one kind of email on or off
yard account agentsThe agents you signed in over MCP, each for one organization, or end one's sign-in
yard account agents endEnd one agent's MCP sign-in at once: its keys stop working, and it gets no new one
yard notificationsYour notifications: what needs you and what is for your information, or read, clear, mute and change them (hosted Switchyard, signed in with yard login --github)
yard notifications readMark notifications read: by id, a task's, or a category's
yard notifications clearTake notifications out of your list: by id, a task's, or all of them
yard notifications muteMute a task or a whole project: it makes no notifications you can turn off; an ask of you by name still comes
yard notifications unmuteLift a task's or a project's mute
yard notifications settingsYour notification settings, or change one
yard notifications settings setTurn a category's or a kind's channel on or off, for every organization or one
yard notifications settings unsetTake one organization's exception away, so the choice for every organization applies there
yard notifications settings summaryThe daily summary: on or off, weekends, and its time zone
yard doctorCheck the URL, key, project, task remote, git and plain git push
yard feedbackTell the Switchyard team, once, when one of its answers confused you or cost you a retry
yard apiSend one request to any route of the API with yard's key, for what no command does
yard completionsPrint shell completions

Start

yard login

Sign in to a Switchyard with GitHub (or, for scripts, a key on stdin) and save it in ~/.config/yard/config.json.

yard login [OPTIONS] <URL> [-]
Argument or flagMeaning
<URL>Switchyard's address: https://app.switchyard.so
[-]Leave it out, or pass -, and yard reads the key from stdin; a key typed here is refused, since shell history and the process list would keep it
--githubSign in as yourself with GitHub: yard prints a link and a code to approve in the browser
--non-interactiveWith --github: print the link, the code to approve, the device code and the command that takes it on stdin to finish the sign-in, and exit without waiting (also with --no-input)
--complete <CODE>Finish a sign-in --non-interactive started: pass - to read the device code it printed from stdin (piped, or typed at a prompt with echo off); yard checks its approval once, and signs in if it is approved (exit 8 while it waits). The code is single-use and dies after the expires_in seconds it came with. The code itself in place of - still works and is deprecated, since shell history and the process list keep it

Examples:

# Sign in as yourself with GitHub, approving a code in the browser
yard login https://app.switchyard.so --github
# Scripts pass a key on stdin, which keeps it out of shell history and the process list
printf '%s\n' "$SWITCHYARD_TOKEN" | yard login https://app.switchyard.so

Without piped input, yard asks for the key without echoing it. A key typed on the command line is refused (exit 2); a single command can take it from SWITCHYARD_TOKEN instead.

yard whoami

Who the configured key belongs to: a signed-in person and their teams, or a project or task.

yard whoami

Example:

yard whoami

yard logout

Sign out: revoke a GitHub sign-in on Switchyard and forget the key.

yard logout

Example:

yard logout

yard init

Connect this repository to a project, creating it (optionally importing a repository).

yard init [OPTIONS]
Argument or flagMeaning
--name <NAME>Display name (default: the project id)
--import <URL>Import main from this Git URL
--github <OWNER/NAME>Follow this GitHub repository: main stays on GitHub, and the merge queue merges there through the Switchyard GitHub App
--branch <BRANCH>Branch to import or follow (default: the remote's default branch)
--organization <SLUG>Organization the project belongs to, when you are signed in (default: the only one you own or administer)
--forceReplace an existing connection in .git/yard.json

Example:

yard init

yard setup

Set a GitHub repository up as the board's set-up page does: its App installations, repositories, drafted checks and rules, then apply them (signed in).

yard setup <COMMAND>

Commands: yard setup github, yard setup repos, yard setup analyze, yard setup apply, yard setup checks-on.

Make the project first with yard init --github acme/web; apply commits the rules and workflow changes to the repository, or opens a pull request where main is protected or the plan says deliver: pull_request.

yard setup github

The Switchyard GitHub App, its install link and the installations you can use.

yard setup github

Example:

yard setup github

yard setup repos

The repositories of one installation, a page at a time or by search.

yard setup repos [OPTIONS] --installation <ID>
Argument or flagMeaning
--installation <ID>The installation's id, as yard setup github shows it; required
--search <TEXT>Only the repositories whose name holds this
--page <N>The page (default 1)

Example:

yard setup repos --installation 42 --search web

yard setup analyze

What setting a repository up would do: the checks drafted from its CI, the rules, its protection and what exists.

yard setup analyze [OPTIONS] <OWNER/NAME>
Argument or flagMeaning
<OWNER/NAME>The GitHub repository
--planPrint the plan the board's set-up page starts with, as JSON for yard setup apply --plan

Examples:

yard setup analyze acme/web
yard setup analyze acme/web --plan > plan.json

yard setup apply

Set a repository up with a plan: commit the rules and workflow changes, or open a pull request.

yard setup apply --project <ID> --plan <FILE> <OWNER/NAME>
Argument or flagMeaning
<OWNER/NAME>The GitHub repository
--project <ID>The project that follows it, as yard init made it; required
--plan <FILE>The plan JSON, from yard setup analyze --plan, or - for stdin; required

Example:

yard setup apply acme/web --project acme-web --plan plan.json

yard setup checks-on

Choose where a project's checks run: Switchyard's machines or the repository's own GitHub Actions.

yard setup checks-on --project <ID> --repository <OWNER/NAME> <PLACE>
Argument or flagMeaning
<PLACE>switchyard (Switchyard's machines) or github (the repository's own GitHub Actions)
--project <ID>The project; required
--repository <OWNER/NAME>The GitHub repository it follows; required

Example:

yard setup checks-on switchyard --project acme-web --repository acme/web

yard branch

Start a task in its own checkout: yard branch new "<task>".

yard branch <COMMAND>

Commands: yard branch new, yard branch list, yard branch open, yard branch key.

yard branch new

Create a task and check it out.

yard branch new [OPTIONS] <TASK>
Argument or flagMeaning
<TASK>What the task is for
--hereCheck the task out in the current repository instead of cloning
--dir <PATH>Clone into this directory (default: ./<task-id>)
--agent <AGENT>The agent's name (default: SWITCHYARD_AGENT, or claude code when Claude Code runs yard; yard agent run names it otherwise)
--model <MODEL>Model the agent runs on
--permission <PERMISSION>What the task's key may do; one of commit, submit, merge
--plan <FILE>Plan JSON to start with
--request-id <ID>Idempotency key: running yard branch new again with the same key within a day returns the task it created instead of a new one (default: a fresh key)
--tag <KEY=VALUE>Tag the task, such as --tag run=wrun_42 --tag phase=build (repeatable)
--issue <ID>The issue this task completes, such as ENG-123 or #123: kept as the tag issue=<ID>, and yard commit adds Fixes <ID> to its commits
--part-of <ID>An issue this task contributes to without completing it: kept as the tag part-of=<ID>, and yard commit adds Part of <ID> to its commits
--assign <LOGIN>Assign the task to this person, by GitHub login (default: you, when signed in with yard login --github)
--parent-task <TASK>The task whose agent started this one, such as 5 (default: SWITCHYARD_TASK, which yard agent run sets for the agent it starts, or, when an agent runs yard, the task whose clone it runs in)
--no-parent-taskStart the task without a parent task, even inside another task's clone
--continues <TASK>A merged task this one continues, such as 12: it starts at that task's merged head, stacked on it, with its assignee, permission and plan (yard commit and yard submit do this by themselves when a push is refused because the task has merged)

Examples:

yard branch new "Add the export button"
yard branch new "Fix the export button" --issue ENG-123

yard branch list

List the active tasks, or the merged and abandoned ones newest first.

yard branch list [OPTIONS]
Argument or flagMeaning
--finishedThe merged and abandoned tasks, newest first, instead of the active ones
--before <CURSOR>The page older than this cursor, as the last page printed it
--limit <N>How many finished tasks a page holds (at most 100)

Examples:

yard branch list
yard branch list --finished
yard branch list --finished --before <cursor> --limit 20

yard branch open

Check out an existing task to fix it yourself, with your own key, for example one sent back whose agent has stopped.

yard branch open [OPTIONS] <TASK>
Argument or flagMeaning
<TASK>The task: its number or id, for example 8
--dir <PATH>Clone into this directory (default: ./<task-id>)

Example:

yard branch open 8

yard branch key

Replace a task's key when it may have leaked: the old key and its Git access stop at once, and the new key is printed once (project admins only).

yard branch key [OPTIONS] <TASK>
Argument or flagMeaning
<TASK>The task: its number or id, for example 8
--yesDo it without asking

Example:

yard branch key 3

Give the new key to the task's agent. A merged or abandoned task's key ends; no new one is issued.

yard agent

Set up coding agents to work with Switchyard.

yard agent <COMMAND>

Commands: yard agent setup, yard agent run.

yard agent setup

Write a Switchyard skill for coding agents and an MCP config entry.

yard agent setup [OPTIONS]
Argument or flagMeaning
-y, --yesWrite without asking
--mcp-url <URL>MCP endpoint (default: <Switchyard URL>/v1/projects/<project>/mcp)
--dir <PATH>Directory to set up (default: the repository root)

Example:

yard agent setup

yard agent run

Start a coding agent with this task's key in SWITCHYARD_TOKEN, read from .git/yard.json (yard agent run -- claude).

yard agent run -- <COMMAND>...
Argument or flagMeaning
<COMMAND>...The agent to start and its arguments, after --

Example:

yard agent run -- claude

yard copy-again

Copy the followed GitHub repository into Switchyard again, after the first copy failed (project admins only).

yard copy-again

Example:

yard copy-again

Switchyard tries a failed first copy again every 15 minutes for an hour, then stops; yard status shows why it failed.

yard copy-history

Copy the followed repository's history behind main, or cancel that copy (project admins only).

yard copy-history [OPTIONS]
Argument or flagMeaning
--cancelStop copying the history; blame past main's first copied commit then says the history was not copied

Examples:

# start a cancelled or failed history copy again
yard copy-history
# stop copying the history; main and every task are untouched
yard copy-history --cancel

A new project copies main first, so tasks can start at once, then its history in the background; yard status shows how far it is.

yard engine

The project's Git engine: wake it ahead of work (project admins only).

yard engine <COMMAND>

Commands: yard engine wake.

yard engine wake

Wake the project's Git engine, so the first push, clone or check does not wait while it loads the repository from storage (project admins only).

yard engine wake [OPTIONS]
Argument or flagMeaning
--waitStay until the engine is awake, drawing what it loads on a terminal

Examples:

yard engine wake
# draw its loading until it is awake
yard engine wake --wait

A second wake while one runs starts nothing more and says what is running.

Work in a task

yard plan

Write or update the task's plan ($EDITOR, --file or stdin JSON).

yard plan [OPTIONS]
Argument or flagMeaning
-f, --file <FILE>Read the plan JSON from a file, or - for stdin
--showPrint the current plan without changing it

Example:

yard plan

yard claim

Say which paths and symbols the task will touch, beside its plan, and read what overlaps with them.

yard claim [OPTIONS]
Argument or flagMeaning
--path <PATH>A path or glob the task will change (repeatable)
--symbol <SYMBOL>A symbol the task will change, such as Cart.total (repeatable)
--branch <BRANCH>Task to claim for (default: this checkout's task)

Examples:

yard claim --path src/cart.ts --symbol Cart.total
yard claim --branch 8 --path docs/api.md

yard status

Graph of main, tasks, stacks and warnings, plus local changes with short ids to commit by.

yard status [OPTIONS] [BRANCH]
Argument or flagMeaning
[BRANCH]Show one task in full: its plan, stack, the tasks it is stacked on or under, and its warnings
--branch <BRANCH>The same as the BRANCH argument
--allInclude merged and abandoned tasks
--localOnly show local changes; do not ask Switchyard
--diffShow the lines of every hunk
-v, --verboseList the changes a review hold waits for and every reason with its paths
--tag <KEY=VALUE>Only the tasks carrying this tag (repeatable; every tag must match)
--assignee <LOGIN>Only the tasks assigned to this person, by GitHub login
--mineOnly the tasks assigned to you (after yard login --github)
--watchFollow the project live on the board's own feed: on a terminal each agent's line, by person and session, is redrawn in place as it changes; off a terminal (or with --plain) one plain line per change; with --json one NDJSON event a line. Without the live connection it reads every 10 s and says why. Exits 0 at --once or Ctrl-C, 1 when the key or project is refused, 9 when nothing answered for 10 minutes
--onceWith --watch: stop after the first change, with exit 0
--plainWith --watch: plain lines even on a terminal, one per change, as off a terminal
--sessionsGroup the tasks by person, then by the terminal or MCP session that started them, each subagent's task under its parent

Example:

yard status

yard commit

Commit chosen files or hunks by the short ids yard status shows (f3a9c, h52e1, ...).

yard commit [OPTIONS] --message <MESSAGE> [ID]...
Argument or flagMeaning
[ID]...File (f3a9c) and hunk (h52e1) ids from yard status
-m, --message <MESSAGE>Commit message; required
--allCommit every local change
--no-pushCommit locally without pushing to the task

Example:

yard commit --message "Keep the total in cents"

yard push

Send the pushes queued on this machine while Switchyard could not be reached, oldest first.

yard push --queued
Argument or flagMeaning
--queuedSend the queued pushes (the only thing yard push does; git push sends the rest); required

Example:

yard push --queued

A push that meets an outage is queued in .git/yard/push-queue (exit 11) and its commits pinned under refs/yard/queued/. The next yard command that talks to Switchyard sends the queue too. A queued push whose branch moved, or that Switchyard refuses, is never forced: yard says so (exit 1) and keeps its commits under refs/yard/unsent/ for you. yard status --local lists both.

yard absorb

Fold working-tree changes into the commits they belong to.

yard absorb [ID]...
Argument or flagMeaning
[ID]...File and hunk ids to absorb (default: every local change)

Example:

yard absorb

yard split

Split paths out of a change into a new change.

yard split [OPTIONS] <CHANGE> <PATHS>...
Argument or flagMeaning
<CHANGE>Change to split (short id, Change-Id or commit)
<PATHS>...Paths to move into the new change
-m, --message <MESSAGE>Message for the new change

Example:

yard split I8f3c2a91 src/cart.ts

yard squash

Squash a change into the change below it, or into --into.

yard squash [OPTIONS] <CHANGE>
Argument or flagMeaning
<CHANGE>Change to squash
--into <CHANGE>Change to squash into (default: the one below)

Example:

yard squash I8f3c2a91

yard edit

Amend a change in the stack with working-tree changes and/or a new message.

yard edit [OPTIONS] <CHANGE> [ID]...
Argument or flagMeaning
<CHANGE>Change to amend
[ID]...File and hunk ids to fold in (default: every local change, unless only -m is given)
-m, --message <MESSAGE>New message for the change

Example:

yard edit I8f3c2a91

yard uncommit

Take a change (or some of its paths) out of the stack, keeping the edits locally.

yard uncommit [OPTIONS] [CHANGE]
Argument or flagMeaning
[CHANGE]Change to uncommit (default: the top of the stack)
--path <PATH>Only take these paths out of the change; repeat it for more

Example:

yard uncommit

yard move

Stack the task onto another task or main, or move a change within the stack.

yard move [OPTIONS] [CHANGE]
Argument or flagMeaning
[CHANGE]Change to move within the stack (with --before or --after)
--onto <BRANCH|main>Stack the task onto another task, or back onto main
--before <CHANGE>Place the change below this one
--after <CHANGE>Place the change above this one

Example:

yard move

yard tag

Set or remove a task's tags, or print them.

yard tag [OPTIONS] [[BRANCH] KEY=VALUE]...
Argument or flagMeaning
[[BRANCH] KEY=VALUE]...The task (default: this checkout's task), then the tags to set
--remove <KEY>Remove this tag (repeatable)

Examples:

# tag this checkout's task
yard tag phase=review
yard tag task-3 run=wrun_42 --remove agent
# print this task's tags
yard tag

yard assign

Assign a task to a person, or clear its assignee with none.

yard assign [OPTIONS] <LOGIN|none>
Argument or flagMeaning
<LOGIN|none>The person's GitHub login, or none to leave the task unassigned
--branch <BRANCH>The task to assign (default: this checkout's task)

Examples:

# assign this checkout's task to @ada
yard assign ada
# leave task 3 unassigned
yard assign --branch task-3 none

Keep up with main and other tasks

yard sync

Bring the newest main, or the task below, into this task; a conflict is recorded in the task and never blocks it.

yard sync [OPTIONS]
Argument or flagMeaning
--wipCommit unfinished work as a work-in-progress change first instead of refusing

Examples:

# bring the newest main into this task
yard sync
# commit unfinished work first, then sync
yard sync --wip

Next: a conflict shows in yard status and yard conflicts, and yard resolve tries the conflict steps.

yard warnings

What overlaps with this task and what to do about it.

yard warnings [OPTIONS]
Argument or flagMeaning
--branch <BRANCH>Task to show (default: this checkout's task)

Example:

yard warnings

yard notice

Switchyard's note on a task: what it last changed, its place in the merge queue, its conflicts and warnings.

yard notice [OPTIONS]
Argument or flagMeaning
--branch <BRANCH>Task to read (default: this checkout's task)

Examples:

# this checkout's task
yard notice
# task 8
yard notice --branch 8

It is the note a push prints as remote: switchyard: lines; nothing is printed beyond a sentence when there is nothing to say.

yard conflicts

Open conflicts in every task with the resolution steps tried, and the ones resolved recently.

yard conflicts [OPTIONS]
Argument or flagMeaning
--branch <BRANCH>Only the conflicts in this task's stack
--sides <PATH>Print each side and the base of this conflicted file instead, with the commits and plans behind them
--change <CHANGE>With --sides: the conflicted change, as yard conflicts shows it

Examples:

yard conflicts
yard conflicts --branch 8
# each side and the base of one file
yard conflicts --sides src/cart.ts --change I8f3c2a91

yard resolve

Run conflict resolution for the task's conflicts step by step, or send your own resolution.

yard resolve [OPTIONS] [PATH]
Argument or flagMeaning
[PATH]Conflicted path; if you edited it, your version is sent as the resolution
--rung <RUNG>Conflict step to use: merge (Git merge), recipe (file rules), structural (code rules), agent (AI suggestion), human (a person)
--change <CHANGE>Conflicted change to resolve

Example:

yard resolve

Submit and review

yard submit

Submit the task to the merge queue.

yard submit [OPTIONS]
Argument or flagMeaning
--waitWait until the task merges, is sent back or is abandoned, with an exit code saying which
--wait-minutes <MINUTES>How long --wait waits before it gives up; default 60
--againAccepted; has no effect today

Examples:

yard submit
yard submit --wait

With --wait, yard waits until the task merges (exit 0), is sent back or withdrawn by a push or an undo (exit 3) or is abandoned (exit 4), and gives up after --wait-minutes (exit 5), saying why it still waits; a poll the coordinator does not answer is tried again until then, and only a refused key, project or task ends the wait early (exit 1); --json then prints the outcome.

Next: yard status shows the task's place in the merge queue and why it waits; it merges once its checks pass and any review it needs is approved.

yard review

Review inbox: list, approve, request a fix or comment.

yard review [OPTIONS]
Argument or flagMeaning
-i, --interactiveAsk what to do with each pending item, reading answers from stdin
-v, --verboseList every reason an item ranks where it does, instead of a one-line summary

Commands: yard review approve, yard review request-fix, yard review comment.

Example:

yard review

yard review approve

Approve the latest version of a change, as a person signed in: where people sign in, no key and no agent's account approves, and an approval that waits for your click in the browser prints its link and exits 8, or with --wait stays until you confirm it.

yard review approve [OPTIONS] <CHANGE>
Argument or flagMeaning
<CHANGE>Change to approve
-m, --message <MESSAGE>Optional comment
--waitWhen the approval waits for your click in the browser, stay until you confirm it there

Example:

yard review approve I8f3c2a91

yard review request-fix

Ask the agent for a fix; the change waits until a new version is pushed.

Also yard review fix.

yard review request-fix --message <MESSAGE> <CHANGE>
Argument or flagMeaning
<CHANGE>Change that needs a fix
-m, --message <MESSAGE>What needs fixing; required

Example:

yard review request-fix I8f3c2a91 --message "Keep the total in cents"

yard review comment

Comment on a change.

yard review comment [OPTIONS] --message <MESSAGE> <CHANGE>
Argument or flagMeaning
<CHANGE>Change to comment on
-m, --message <MESSAGE>Comment text; required
--at <PATH:LINE>Anchor the comment to a line

Example:

yard review comment I8f3c2a91 --message "Keep the total in cents"

yard pr

Pull requests of the project's GitHub repository in the merge queue: where one stands.

yard pr <COMMAND>

Commands: yard pr status.

yard pr status

Where a pull request stands in the merge queue: its state, reason code and sentence, the task it is in and its head.

yard pr status <PULL>
Argument or flagMeaning
<PULL>The pull request's number, or its URL on GitHub

Examples:

yard pr status 12
yard pr status https://github.com/acme/web/pull/12 --json

The sentence is the one the pull request's status comment and its switchyard queue check show on GitHub; the codes are listed at https://switchyard.so/docs/reasons.

yard hotfix

Merge a queued task as a hotfix, before the rest of the merge queue (project admins only).

yard hotfix [OPTIONS]
Argument or flagMeaning
--branch <BRANCH>The task to merge first (default: this checkout's task)
--offPut the task back in its turn

Examples:

# merge this checkout's task first
yard hotfix
# put task 3 back in its turn
yard hotfix --branch task-3 --off

A hotfix applies to the head it was given: pushing to the task again drops it.

yard priority

Merge a queued task in the priority lane, after hotfixes and before the normal lane (project admins only).

yard priority [OPTIONS]
Argument or flagMeaning
--branch <BRANCH>The task to merge first (default: this checkout's task)
--offPut the task back in its turn

Examples:

# merge this checkout's task in the priority lane
yard priority
# put task 3 back in its turn
yard priority --branch task-3 --off

A lane applies to the head it was given: pushing to the task again drops it. [merge_queue] priority in .yard/rules.toml puts an agent group's, a person's or an agent's tasks in the priority lane.

yard abandon

Abandon a task, as the board's Abandon does: it leaves the merge queue and the live merge, and its keys stop working.

yard abandon [OPTIONS] [TASK]
Argument or flagMeaning
[TASK]The task to abandon, such as 3 (default: this checkout's task)
--reason <REASON>Why, in a line the project's history keeps with the abandon

Examples:

# abandon this checkout's task
yard abandon
# abandon task 3, saying why
yard abandon 3 --reason "task 2 does the same"

A task's key abandons only its own task; the admin key, any.

Look back

yard log

The task's changes, or the project's history with --ops.

yard log [OPTIONS]
Argument or flagMeaning
--opsShow the project's history
--since <SEQ>Only actions after this seq
-n, --limit <N>Show at most N entries (the latest)
--utcShow the history's times in UTC instead of local time

Example:

yard log

yard show

A change's versions, the reason behind it and its diff, or what changed between two versions.

yard show [OPTIONS] <CHANGE>
Argument or flagMeaning
<CHANGE>Change: its short id, its Change-Id or any unique prefix of it
--version <N>Show this version instead of the latest
--from <N>Show what changed from this version to --to (default: the latest)
--to <N>The version to compare --from with

Example:

yard show I8f3c2a91

yard why

Task, agent, plan and prompt behind a file or line.

yard why [OPTIONS] <PATH[:LINE]>
Argument or flagMeaning
<PATH[:LINE]>File, optionally with a line number
--branch <BRANCH>Blame this task's head instead of the live integration (a task's key may name only its own branch)

Example:

yard why src/cart.ts:42

yard undo

Undo an action (default: the latest one for this task).

yard undo [SEQ]
Argument or flagMeaning
[SEQ]Seq of the action to undo (default: the latest undoable one for this task)

Example:

yard undo

yard verify

Check the signed merge record of a merged commit: who approved it and which checks passed on it.

yard verify [OPTIONS] [COMMIT]
Argument or flagMeaning
[COMMIT]A commit the merge queue merged: a revision here, or 7 or more hex digits
--signerPrint the project's allowed_signers line instead, to pin its signing key
--signers <FILE>allowed_signers file to trust (default: .yard/allowed_signers in this repository, else the key the server reports)

Examples:

yard verify 3f2a9c1
# pin the project's signing key, so later checks trust only it
yard verify --signer > .yard/allowed_signers

yard fetch

Fetch main and its merge records into refs/remotes/switchyard/<branch>.

yard fetch

Example:

yard fetch

yard check

A check's full log, and turning checks kept in Switchyard off, on or trying them again.

yard check <COMMAND>

Commands: yard check log, yard check off, yard check on, yard check try, yard check tried, yard check shell.

yard check log

Print a check's full log; without a name, list the checks whose full log is kept.

yard check log [OPTIONS] [NAME]
Argument or flagMeaning
[NAME]The check's name, as yard status and the board show it
--build <ID>The test build to read it from, by its id or the start of it (default: the newest one that ran the check)
--trialRead it from the checks' trial on main instead of the merge queue

Examples:

yard check log
yard check log python
yard check log python --trial > python.log
yard check log test --build 3f2a9c1

Full logs are kept for 30 days. A log over 50 MB keeps its first and last 25 MB, with a line saying how much was left out between them.

With --json and no name, each check also carries its tests, the stage that failed with its last 40 lines, and how long each stage of its start took. With --json and a name, it prints {name, place, log, bytes, truncated} instead of the raw log.

yard check off

Turn checks kept in Switchyard off: they hold no task and run on no test build (project admins only).

yard check off <NAMES>...
Argument or flagMeaning
<NAMES>...The checks' names, as yard settings lists them

Examples:

yard check off coverage
yard check off coverage lint

Checks in .yard/rules.toml on main are turned off in that file instead.

yard check on

Turn checks kept in Switchyard back on (project admins only).

yard check on <NAMES>...
Argument or flagMeaning
<NAMES>...The checks' names, as yard settings lists them

Example:

yard check on coverage

yard check try runs a check on main once first and turns it on only if it passes.

yard check try

Try checks that are off once more on main: the ones that pass turn back on (project admins only).

yard check try [NAMES]...
Argument or flagMeaning
[NAMES]...The checks to try; without names, every check that is off

Examples:

yard check try
yard check try coverage

Without names every check that is off is tried. yard check tried shows the result.

yard check tried

The checks' trial on main: each check kept in Switchyard with how it did there, and which are off.

yard check tried

Example:

yard check tried

yard check shell

Run one command in the machine a task's failed check kept, as the check ran; --done ends the machine.

yard check shell [OPTIONS] <NAME>
Argument or flagMeaning
<NAME>The check's name, as yard status and the board show it
-c, --command <COMMAND>The command to run, through bash -c in the check's folder
--doneEnd the kept machine now
--build <ID>The test build that kept it, by its id or the start of it (default: the newest one)

Examples:

yard check shell test -c "cat tests/slugify.test.js"
yard check shell test -c "npm test -- slugify"
yard check shell test --done

A task's failed check keeps its machine for 10 minutes after it fails or after its last command, up to 30 minutes, where yard settings shows kept machines on. Each command runs through bash -c in the check's folder, up to 2 minutes and 1 MB of output, one at a time, and yard exits with its status. Its machine time is billed as check time: at least a minute a keep, then by the second.

yard insights

The project's numbers over 1, 7 or 30 days: tasks started, merged and sent back, the time to merge, per agent and model.

yard insights [OPTIONS]
Argument or flagMeaning
--days <DAYS>How far back: 1, 7 or 30 days (default 7)

Examples:

yard insights
yard insights --days 30 --json

yard queue

The merge queue: its health now, in one sentence and a few numbers.

yard queue <COMMAND>

Commands: yard queue health.

yard queue health

The merge queue's health now: one sentence, the one thing that needs a person, how long submit to merged takes, how many tasks wait and the share sent back.

yard queue health

Examples:

yard queue health
yard queue health --json

The first line is the state in a word and the second is Switchyard's own sentence. A number Switchyard's records cannot give prints as "not known", never as 0. Ages are worked out from the times in the answer as it prints. --json prints the answer as it came. The exit status is 0 for any state: a slow merge queue is not a failed command.

yard value

What Switchyard did for the project over 1, 7 or 30 days, each number counted from its records: changes merged, broken changes kept out of main, conflicts fixed and by which step, check runs not made, flaky checks caught.

yard value [OPTIONS]
Argument or flagMeaning
--days <DAYS>How far back: 1, 7 or 30 days (default 7)

Examples:

yard value
yard value --days 30 --json

The sources lines name the records each group is counted from; nothing is estimated. yard org value adds up an organization's projects.

Run the project

yard settings

Read the project's settings, or change one: a task key and an agent group key read none, and changing one takes admin access.

yard settings

Commands: yard settings set.

Example:

yard settings

reviews on|off, fixes approve|auto, who-submits submit|commit, wake-on-open on|off, warm-hour on|off, check-network open|registries|off, docs-excused on|off, incremental-rebuild off|on|verify (off by default: every rebuild merges every task; on rebuilds only where tasks moved and checks one in verify-capped-every incremental rebuilds against a full rebuild; verify checks every one), verify-capped-every 0-1000 (10 by default; 0 turns sampling off), grouped-merge sampled|off (sampled by default: the engine merges path by path from 32 tasks and one full rebuild in grouped-verify-every is checked against the full merge; off asks for the full merge every time), grouped-verify-every 0-1000 (5 by default; 0 checks none), grouped-latch clear (after a check differed or the path-by-path merge failed, the project keeps to the full merge until this), continue-merged on|off (on by default: a push that builds on a merged task's head continues it as a new change; off, a push to a merged task is not tracked), merge-trains on|off (on for a project made on queue v2 since 19 November, off for every other, with no effect until the merge queue reads it: on, tasks that touch nothing in common ride separate trains, and a train's tested change may land on a main another train moved, checked on main afterwards; it helps only where checks are scoped by paths or sparse checkouts; where people sign in, on is a person's in a browser signed in within 15 minutes, so from yard it prints the settings page and exits 8; there is no control on the settings page yet, so Switchyard turns merge trains on for a project on request), engine-sizing small|grows (an owner's or admin's choice for the whole organization where there is one; grows only in a browser). Whether conflict records may help improve conflict fixing is a person's choice on the settings page.

yard settings set

Change one setting; it is recorded in the project's history and yard undo reverts it.

yard settings set <SETTING> <VALUE>
Argument or flagMeaning
<SETTING>The setting; one of reviews, fixes, who-submits, wake-on-open, warm-hour, check-network, self-approval, allowed-apps, checks-while-reviewing, checks-before-submit, build-cache, docs-excused, keep-failed-machines, engine-sizing, incremental-rebuild, grouped-merge, grouped-verify-every, grouped-latch, continue-merged, merge-trains, verify-capped-every
<VALUE>Its new value

Examples:

yard settings set reviews off
yard settings set who-submits commit
yard settings set check-network registries

yard rules

The rules and checks kept in Switchyard: print them, or keep a rules file's text.

yard rules <COMMAND>

Commands: yard rules show, yard rules keep, yard rules protect, yard rules unchecked, yard rules enforce.

yard rules show

Print the rules and checks kept in Switchyard, as a rules file.

yard rules show

Examples:

yard rules show > rules.toml
# then edit rules.toml
yard rules show > rules.toml

yard rules keep

Keep a rules file's text in Switchyard, replacing what is kept (project admins only).

yard rules keep [OPTIONS] <FILE>
Argument or flagMeaning
<FILE>The rules file, in the format of .yard/rules.toml; - reads it from standard input
--tryTry the new or changed checks once on main before they count

Examples:

yard rules keep rules.toml --try
cat rules.toml | yard rules keep -

With --try, checks that are new or whose command, checkout, skeleton, size, timeout or services changed run once on main and stay off until they pass there.

yard rules protect

List the protected areas the repository has and the rules miss, and add them (team admins).

yard rules protect [OPTIONS] [ID]...
Argument or flagMeaning
[ID]...The areas to add, by id
--addAdd the missing areas: the ids named after it, or every missing one

Examples:

yard rules protect
yard rules protect --add
yard rules protect --add migrations agents

A change to a protected area waits for someone other than whoever started its task. They are added to the rules kept in Switchyard, or to .yard/rules.toml on GitHub, through a pull request when the default branch is protected.

yard rules unchecked

Say plainly that paths need no check, so a task changing only them merges though no check reads them (project admins only).

yard rules unchecked [OPTIONS] <PATH>...
Argument or flagMeaning
<PATH>...Repository paths or globs that need no check
--reason <REASON>Why they need none, for the next reader

Examples:

yard rules unchecked src/generated/schema.ts
yard rules unchecked 'gen/**' --reason 'generated, read by no test'

An [[unchecked]] table is added to the rules kept in Switchyard; rules in .yard/rules.toml on main change through a task, and the answer names the table to add.

yard rules enforce

Hold a task that changes a file no check tests from now on, before the guard's seven days of watching end (project admins only).

yard rules enforce

Example:

yard rules enforce

yard pause

Pause merging on main, during an incident or a release window (project admins only).

yard pause [OPTIONS] --reason <TEXT>
Argument or flagMeaning
--reason <TEXT>Why merging is paused; people and agents read it; required
--until <WHEN>Resume by itself then: a time such as 2026-10-20T09:00:00Z, or a span such as 30m, 2h or 1d (at most 30 days)

Examples:

yard pause --reason "incident 42: payments are failing"
yard pause --reason "release window" --until 2h
yard pause --reason "freeze" --until 2026-10-20T09:00:00Z

The merge queue keeps testing; nothing merges but an admin's hotfix until yard resume, or until --until.

yard resume

Resume merging after yard pause (project admins only).

yard resume

Example:

yard resume

yard project

The project: show it, list yours, keep it from a scheduled deletion, or print the page where a person rotates its admin key or schedules its deletion.

yard project <COMMAND>

Commands: yard project show, yard project list, yard project rotate-admin-key, yard project deletion, yard project delete, yard project keep.

yard project show

The project: its name, main branch, remote and the GitHub repository it follows.

yard project show

Example:

yard project show

yard project list

List the projects you can see, with their organization, team and your access (signed in).

yard project list

Example:

yard project list

yard project rotate-admin-key

Issue a new admin key for the project; every earlier admin key stops at once, so it answers a leak: it prints the project's settings page, where a person with admin access rotates it in a browser signed in within 15 minutes (exit 8).

yard project rotate-admin-key [OPTIONS]
Argument or flagMeaning
--confirm <PROJECT>The project's id, to confirm that every earlier admin key may stop

Example:

yard project rotate-admin-key --confirm acme-web

The new key is shown on that page once; give it to whoever and whatever used the old one.

yard project deletion

Whether a project is scheduled for deletion, and when.

yard project deletion [PROJECT]
Argument or flagMeaning
[PROJECT]The project's id (default: this checkout's project)

Example:

yard project deletion

yard project delete

Schedule a project's deletion (owners and admins of its organization): it prints the project's settings page, where a person schedules it in a browser signed in within 15 minutes (exit 8); its owners and admins are emailed and it can be kept until the day comes.

yard project delete --confirm <PROJECT> <PROJECT>
Argument or flagMeaning
<PROJECT>The project's id
--confirm <PROJECT>The project's id again, to confirm; required

Example:

yard project delete acme-web --confirm acme-web

yard project keep acme-web cancels it.

yard project keep

Cancel a project's scheduled deletion.

yard project keep [PROJECT]
Argument or flagMeaning
[PROJECT]The project's id (default: this checkout's project)

Example:

yard project keep

yard webhook

The project's webhook endpoints: list, add, test or remove them (project admins only), and check a delivery's signature.

yard webhook <COMMAND>

Commands: yard webhook list, yard webhook add, yard webhook test, yard webhook remove, yard webhook verify.

add prints the endpoint's signing secret once, then the result of a test event sent to it; events are change.fixed, workspace.submitted, workspace.merged and workspace.sent_back (all of them when none is named). verify checks a delivery's signature on this machine and needs no sign-in.

yard webhook list

List the endpoints and how their deliveries go, never their secrets (project admins only).

yard webhook list

Example:

yard webhook list

yard webhook add

Add an endpoint; its signing secret is printed once, then the result of a test event sent to it (project admins only).

yard webhook add [OPTIONS] <URL>
Argument or flagMeaning
<URL>The endpoint: an https URL on a public host, on port 443
--event <EVENT>An event to send: change.fixed, workspace.submitted, workspace.merged or workspace.sent_back (repeatable; all of them when none is named)

Example:

yard webhook add https://hooks.example/switchyard --event workspace.merged

yard webhook test

Send one test event to an endpoint and print its result (project admins only).

yard webhook test <ID>
Argument or flagMeaning
<ID>The endpoint's id, as yard webhook list shows it

Example:

yard webhook test wh_0123456789abcdef

The event's type is webhook.test; it goes to the endpoint whatever events it asked for, once, and is never sent again. Exits 0 when the receiver answered 2xx within 10 seconds, and 1 when not (error code not_delivered), saying why. An endpoint takes at most 30 test events an hour.

yard webhook remove

Remove an endpoint and the events waiting for it (project admins only).

yard webhook remove [OPTIONS] <ID>
Argument or flagMeaning
<ID>The endpoint's id, as yard webhook list shows it
--yesDo it without asking

Example:

yard webhook remove wh_0123456789abcdef

yard webhook verify

Check a delivery's signature on this machine, with no network and no sign-in.

yard webhook verify [OPTIONS]
Argument or flagMeaning
--id <ID>The request's webhook-id header
--timestamp <SECONDS>The request's webhook-timestamp header
--signature <SIGNATURE>The request's webhook-signature header, whole: v1,<base64>, or several separated by spaces
--body-file <PATH>A file holding the request's body, the bytes as they arrived (default: stdin)
--tolerance <SECONDS>How far the timestamp may be from this machine's clock, either way; default 300
--secret-file <PATH>A file holding the signing secret (default: the SWITCHYARD_WEBHOOK_SECRET environment variable)

Examples:

yard webhook verify --id evt_812_0 --timestamp 1795000000 --signature v1,<base64> --body-file body.json
yard webhook verify --id evt_812_0 --timestamp 1795000000 --signature v1,<base64> --secret-file secret.txt < body.json

The signing secret is read from SWITCHYARD_WEBHOOK_SECRET or from --secret-file, never from an argument, and is never printed. Exits 0 when the delivery is valid. Exits 1 when it is not, with one error code: secret_format, header_missing, timestamp_old, timestamp_ahead or signature_mismatch. Exits 2 when no secret or no body could be read.

yard resolutions

The conflict resolutions a person made by hand that the project remembers and reuses, or forget one (forgetting needs the admin key).

yard resolutions

Commands: yard resolutions forget.

Example:

yard resolutions

yard resolutions forget

Forget a remembered resolution, so the next conflict like it climbs the conflict steps again.

yard resolutions forget [OPTIONS] <KEY>
Argument or flagMeaning
<KEY>The resolution's key: 64 hex digits, as yard resolutions --json shows it
--yesDo it without asking

Example:

yard resolutions forget <key>

Keys and organizations

yard group

List agent group keys, the keys many agents share, and revoke one or turn it off; rotating one or turning it back on prints the project's settings page (exit 8), where a person does it in a browser (project admins only).

yard group [OPTIONS] <GROUP> <ACTION>
Argument or flagMeaning
<GROUP>The agent group's id, for example F1
<ACTION>rotate, revoke, disable or enable
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60, up to 10080)
--abandonWith revoke: also abandon the group's active tasks
--yesWith revoke: do it without asking

Commands: yard group list, yard group create.

Examples:

yard group F1 rotate --grace-minutes 10
yard group F1 revoke --abandon
yard group F1 disable

revoke ends a key at once and disable turns it off, both from yard, so a leaked key is stopped fast. rotate and enable are a person's act in a browser signed in within 15 minutes: from a yard sign-in or an organization key Switchyard answers approval_required, and yard prints the project's settings page's link and exits 8; the new key is shown on that page once. Only the project admin key itself still rotates a key or turns one back on from yard: a rotated key is printed once, and the old one keeps working for --grace-minutes (default 60) so running agents can switch.

yard group list

List the project's agent group keys, with the tasks each started.

yard group list

Example:

yard group list

yard group create

Make an agent group key: it prints the project's settings page, where a person makes it in a browser signed in within 15 minutes (exit 8); the key is shown there once.

yard group create [OPTIONS] <NAME>
Argument or flagMeaning
<NAME>The group's name, for example nightly
--tag <KEY=VALUE>A tag every task of the group carries (repeatable)
--permission <PERMISSION>What the group's tasks may do (default: the project's who-submits setting); one of commit, submit, merge
--max-tasks <N>The most tasks the group creates in its life (100 by default, at most 1,000)
--rate <PER_MINUTE>The most requests a minute the group's agents send together
--expires-in-days <DAYS>How long the key lasts (default 90 days)

Example:

yard group create nightly --tag team=web --max-tasks 20

yard org

Your organizations: members, invitations, API keys and AI fixes (signed in with yard login --github).

yard org <COMMAND>

Commands: yard org list, yard org create, yard org members, yard org show, yard org teams, yard org team, yard org rename, yard org invite, yard org invitations, yard org deleted, yard org keys, yard org audit, yard org key, yard org ai-fixes, yard org agent-approvals, yard org engine-sizing, yard org sso, yard org scim, yard org two-factor, yard org secret, yard org delete, yard org usage, yard org value, yard org billing, yard org limit, yard org card, yard org invoices, yard org role, yard org remove, yard org leave, yard org withdraw, yard org invited, yard org accept, yard org decline.

yard org list

List the organizations you belong to, with your role and plan.

yard org list

Example:

yard org list

yard org create

Make an organization with you as its owner: it prints the board's page, where you make it in a browser (exit 8).

yard org create [OPTIONS] <NAME>
Argument or flagMeaning
<NAME>The organization's name, such as Acme
--slug <SLUG>Its slug, in every address: 2 to 48 lowercase letters, digits and single dashes (default: made from the name)

Examples:

yard org create Acme
yard org create "Acme Labs" --slug acme-labs

The slug is in every address; without --slug it is made from the name, as on the board. A new organization is a person's choice, so a person makes it in a browser where they are signed in: from your yard sign-in Switchyard answers approval_required, and yard prints the page's link and exits 8. An agent's or a script's run of yard is refused before anything is sent. Switchyard refuses an agent's account, and on open sign-up an account whose email is not proven; yard prints why.

yard org members

List an organization's members, their roles and teams, or one team's members.

yard org members [OPTIONS] <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it
--team <TEAM>Only this team's members, by its slug

Example:

yard org members acme

yard org show

Show an organization: its name, plan, your role and its teams.

yard org show <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org show acme

yard org teams

List an organization's teams, with their members and projects.

yard org teams <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org teams acme

yard org team

Make or remove a team, or add a member to a team or take one out (owners and admins): each prints the teams page, where a person does it in a browser (exit 8).

yard org team <COMMAND>

Commands: yard org team create, yard org team delete, yard org team add, yard org team remove.

A removed team's projects become the whole organization's. A team and who is on it decide who reviews what, so making or removing a team, adding someone to one or taking them off is a person's act in a browser signed in within 15 minutes: yard org team create, delete, add and remove print the teams page's link and exit 8 (approval_required).

yard org team create

Make a team: it prints the teams page, where a person makes it in a browser signed in within 15 minutes (exit 8).

yard org team create [OPTIONS] <ORG> <NAME>
Argument or flagMeaning
<ORG>The organization's slug
<NAME>The team's name, such as Payments
--slug <SLUG>The team's slug: 2 to 48 lowercase letters, digits and single dashes (default: made from the name)

Example:

yard org team create acme Payments

yard org team delete

Remove a team, whose projects become the whole organization's: it prints the teams page, where a person removes it in a browser signed in within 15 minutes (exit 8).

yard org team delete <ORG> <TEAM>
Argument or flagMeaning
<ORG>The organization's slug
<TEAM>The team's slug, as yard org teams shows it

Example:

yard org team delete acme payments

yard org team add

Add a member of the organization to a team; prints the teams page's link, where a person does it in a browser (exit 8).

yard org team add <ORG> <TEAM> <LOGIN>
Argument or flagMeaning
<ORG>The organization's slug
<TEAM>The team's slug, as yard org teams shows it
<LOGIN>The member's GitHub login

Example:

yard org team add acme payments octocat

yard org team remove

Take a member out of a team; prints the teams page's link, where a person does it in a browser (exit 8).

yard org team remove <ORG> <TEAM> <LOGIN>
Argument or flagMeaning
<ORG>The organization's slug
<TEAM>The team's slug, as yard org teams shows it
<LOGIN>The member's GitHub login

Example:

yard org team remove acme payments octocat

yard org rename

Rename an organization; its slug, in every address, stays (owners and admins).

yard org rename <ORG> <NAME>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it
<NAME>Its new name

Example:

yard org rename acme "Acme Labs"

yard org invite

Invite someone to an organization by GitHub login (owners and admins): it prints the teams page, where a person invites them in a browser signed in within 15 minutes (exit 8).

yard org invite [OPTIONS] <ORG> <LOGIN>
Argument or flagMeaning
<ORG>The organization's slug
<LOGIN>Their GitHub login
--role <ROLE>developer starts and submits agents and reviews, member sees and approves, admin also manages settings, rules, keys and people, billing sees and manages billing; default developer
--team <TEAM>A team to add them to when they accept, by its slug
--billingAlso let them see and manage billing; for a developer or a member, since owners and admins hold it already

Examples:

yard org invite acme octocat
yard org invite acme octocat --role admin
yard org invite acme octocat --team payments

They accept or decline it on their account page; it expires if nobody answers it.

yard org invitations

List an organization's open invitations.

yard org invitations <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

# lists them, with their ids
yard org invitations acme

yard org deleted

List the projects an organization deleted in the last 30 days, who asked, and until when their data is kept (owners and admins).

yard org deleted <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org deleted acme

yard org keys

List an organization's API keys (owners and admins).

yard org keys <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org keys acme

yard org audit

Read an organization's audit log: who did what, when and from where (owners and admins).

yard org audit [OPTIONS] <ORG>
Argument or flagMeaning
<ORG>The organization's slug
--what <ACTION>Only this kind, such as member, key or project, or one action, such as member.role_change
--who <LOGIN>Only what this person or API key did
--refusedOnly what was refused
--since <DATE>From this UTC date or time, such as 2026-10-01
--until <DATE>Up to this UTC date or time
--limit <N>How many events to print (default 50)
--after <CURSOR>Go on from where the last page ended
--csvPrint the matching events as CSV instead
--jsonlPrint the matching events as JSON lines instead

Examples:

yard org audit acme
yard org audit acme --what member --since 2026-10-01
yard org audit acme --refused
yard org audit acme --csv > audit.csv

Events are kept 400 days; --csv and --jsonl export up to 10,000 of them.

yard org key

An organization's API keys (owners and admins): disable or revoke one from yard; create, rotate, enable and keep print the teams page, where a person does it in a browser (exit 8).

yard org key <COMMAND>

Commands: yard org key create, yard org key rotate, yard org key disable, yard org key enable, yard org key revoke, yard org key keep.

yard org key create

Make an API key: it prints the teams page at the organization's keys, where a person makes it in a browser signed in within 15 minutes (exit 8); the key is shown there once.

yard org key create [OPTIONS] <ORG> <NAME>
Argument or flagMeaning
<ORG>The organization's slug
<NAME>The key's name, after what uses it, such as ci or deploy
--access <ACCESS>member, developer (starts agents) or admin; default member
--team <TEAM>Limit the key to one team's projects, by the team's slug
--days <DAYS>Days until it expires (default 90)

Examples:

yard org key create acme ci
yard org key create acme deploy --access admin --days 30
yard org key create acme payments-ci --team payments

A member key sees and approves in the organization's projects (or one team's); a developer key also starts and submits agents; an admin key also administers them.

yard org key rotate

Rotate a key: it prints the teams page at the organization's keys, where a person rotates it in a browser signed in within 15 minutes (exit 8); the new key is shown there once.

yard org key rotate [OPTIONS] <ORG> <KEY>
Argument or flagMeaning
<ORG>The organization's slug
<KEY>The key's id, as yard org keys shows it
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60)

Example:

yard org key rotate acme key_7

yard org key disable

Disable a key until it is enabled again.

yard org key disable [OPTIONS] <ORG> <KEY>
Argument or flagMeaning
<ORG>The organization's slug
<KEY>The key's id, as yard org keys shows it
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60)

Example:

yard org key disable acme key_7

yard org key enable

Enable a disabled key: it prints the teams page at the organization's keys, where a person enables it in a browser signed in within 15 minutes (exit 8).

yard org key enable [OPTIONS] <ORG> <KEY>
Argument or flagMeaning
<ORG>The organization's slug
<KEY>The key's id, as yard org keys shows it
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60)

Example:

yard org key enable acme key_7

yard org key revoke

Revoke a key for good.

yard org key revoke [OPTIONS] <ORG> <KEY>
Argument or flagMeaning
<ORG>The organization's slug
<KEY>The key's id, as yard org keys shows it
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60)
--yesDo it without asking

Example:

yard org key revoke acme key_7

yard org key keep

Keep a key someone made for the team, so it keeps working when its maker leaves: it prints the teams page at the organization's keys, where a person keeps it in a browser signed in within 15 minutes and it becomes theirs (exit 8).

yard org key keep [OPTIONS] <ORG> <KEY>
Argument or flagMeaning
<ORG>The organization's slug
<KEY>The key's id, as yard org keys shows it
--grace-minutes <MINUTES>With rotate: how long the old key keeps working (default 60)

Example:

yard org key keep acme key_7

yard org ai-fixes

Read whether Switchyard's AI conflict fixes are on, or print the page that turns them on or off (owners and admins).

yard org ai-fixes <ORG> [TURN]
Argument or flagMeaning
<ORG>The organization's slug
[TURN]on or off prints the page that turns them so (exit 8); without it, prints whether they are on

Examples:

yard org ai-fixes acme
# prints the page and exits 8; a person signed in in a browser turns them on there
yard org ai-fixes acme on

An AI suggestion is billed per suggestion after the ones included each month, so turning them on or off is a person's, in a browser.

yard org agent-approvals

Read whether agents may approve work in the organization, or print the page that turns it on or off (owners and admins).

yard org agent-approvals <ORG> [TURN]
Argument or flagMeaning
<ORG>The organization's slug
[TURN]on or off prints the page that turns it so (exit 8); without it, prints whether it is on

Examples:

yard org agent-approvals acme
# prints the page and exits 8; an owner or admin signed in in a browser turns it on there
yard org agent-approvals acme on

Off (the default): an approval sent from an agent, yard or MCP waits for the person's click in the browser. On: agents may approve other people's unprotected work, never their own person's task or protected changes.

yard org engine-sizing

Read whether the organization's Git engines start on a larger machine after many agents worked at once, or keep them small (owners and admins).

yard org engine-sizing <ORG> [SIZING]
Argument or flagMeaning
<ORG>The organization's slug
[SIZING]small sets it; grows prints the page where a person sets it (exit 8); without it, prints which it is

Examples:

yard org engine-sizing acme
yard org engine-sizing acme small
# prints the page and exits 8; a person signed in in a browser lets them grow there
yard org engine-sizing acme grows

A larger engine is billed at its size, so letting engines grow is a person's, in a browser; kept small, the engines start on the machine each repository needs and clones wait their turn.

yard org sso

Read an organization's single sign-on: its connections, whether it is required, and the DNS records still to add; verify checks a connection's records now (owners).

yard org sso [ORG]
Argument or flagMeaning
[ORG]The organization's slug

Commands: yard org sso verify.

Example:

yard org sso acme

Setting up, removing or requiring single sign-on is an owner's, in a browser signed in within 15 minutes, so yard prints that page.

yard org sso verify

Check a single sign-on connection's DNS records now; its domains are verified once every record is found (owners).

yard org sso verify <ORG> <PROVIDER>
Argument or flagMeaning
<ORG>The organization's slug
<PROVIDER>The connection's name, as yard org sso shows it

Example:

# checks the connection's DNS records now
yard org sso verify acme acme-okta

yard org scim

Read an organization's SCIM directory: whether one is paired, with which single sign-on connection, and how many people it holds.

yard org scim <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org scim acme

Pairing a directory, making its directory key again or unpairing it is an owner's, in a browser signed in within 15 minutes, so yard prints that page.

yard org two-factor

Read an organization's two-factor level, recommended or required, and how its members are covered (owners and admins see the counts).

yard org two-factor <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org two-factor acme

Setting the level is an owner's, in a browser signed in within 15 minutes, so yard prints that page.

yard org secret

Print the page where an owner sets or removes an organization's secret, in a browser signed in within 15 minutes (exit 8).

yard org secret <ORG> <NAME>
Argument or flagMeaning
<ORG>The organization's slug
<NAME>The secret: anthropic, the Anthropic API key hosted agent runs use

Example:

yard org secret acme anthropic

A secret is typed by its owner in a browser, never passed through yard or an agent, so yard sends nothing, prints the page and exits 8.

yard org delete

Print the page where an owner deletes an organization, in a browser signed in within 15 minutes (exit 8).

yard org delete <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org delete acme

Deleting an organization cannot be undone, so yard sends nothing, prints the page and exits 8; an organization that still owns projects or has started billing is not deleted.

yard org usage

This month's usage: merges, pushes, check seconds and AI suggestions, with the bill so far.

yard org usage <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org usage acme

yard org value

What Switchyard did for an organization's projects over 1, 7 or 30 days, in total and project by project, each number counted from their records.

yard org value [OPTIONS] <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it
--days <DAYS>How far back: 1, 7 or 30 days (default 7)

Examples:

yard org value acme
yard org value acme --days 30 --json

It reads each project you may see; a project that did not answer in time is listed as not read and left out of the total.

yard org billing

A month's bill, line by line and project by project; contacts reads who gets the billing emails, and prints the billing page that changes them (owners, admins and billing).

yard org billing [OPTIONS] [ORG]
Argument or flagMeaning
[ORG]The organization's slug
--month <YYYY-MM>The month (default: this one)
--csvPrint every check run of the month as CSV instead

Commands: yard org billing contacts.

Examples:

yard org billing acme
yard org billing acme --month 2026-09
# every check run of the month, billed or not
yard org billing acme --csv > runs.csv

Owners, admins and billing members always get the billing emails; contacts adds or removes other addresses.

yard org billing contacts

Who gets the organization's billing emails (owners, admins and billing); adding or removing an address prints the billing page, where a person does it in a browser signed in within 15 minutes (exit 8).

yard org billing contacts [OPTIONS] <ORG>
Argument or flagMeaning
<ORG>The organization's slug
--add <EMAIL>An address to send the billing emails to as well (repeat it)
--remove <EMAIL>An added address to stop sending them to (repeat it)

Examples:

yard org billing contacts acme
yard org billing contacts acme --add finance@acme.dev --remove old@acme.dev

yard org limit

The spending limit: what was spent of it, the warnings emailed, the forecast and what it holds; set or remove it (owners, admins and billing, never an agent).

yard org limit [ORG]
Argument or flagMeaning
[ORG]The organization's slug

Commands: yard org limit set.

Example:

yard org limit acme

yard org limit set prints the billing page's link that confirms the change and exits 8; a person confirms it there in a browser, and an agent's or a script's run of yard is refused.

yard org limit set

Print the billing page's link that sets, raises or removes the spending limit, in whole dollars or none; a person confirms it there, signed in in a browser (exit 8).

yard org limit set <ORG> <DOLLARS|none>
Argument or flagMeaning
<ORG>The organization's slug
<DOLLARS|none>The new limit in whole dollars, or none to remove it

Examples:

yard org limit set acme 500
yard org limit set acme none

yard org card

The card on file, where the organization's payments stand and when the next charge comes; add prints the billing page, where a person adds or changes the card in a browser (owners, admins and billing).

yard org card [ORG]
Argument or flagMeaning
[ORG]The organization's slug

Commands: yard org card add.

Example:

yard org card acme

yard org card add

Print the billing page, where a person adds or changes the organization's card in a browser they are signed in to (exit 8); a first card pays the plan's minimum there, otherwise the card is only checked.

yard org card add [OPTIONS] <ORG>
Argument or flagMeaning
<ORG>The organization's slug
--plan <PLAN>The plan whose minimum a first card pays, launch or scale (default: the organization's own plan); a card change charges nothing. The billing page yard prints does not carry it: the person chooses the plan there

Examples:

# prints the billing page, where a person adds or changes the card in a browser; a first card pays the plan's minimum there, otherwise nothing is charged
yard org card add acme
# the billing page it prints does not carry the plan: the person chooses Scale there
yard org card add acme --plan scale

yard org invoices

The organization's statements and their invoices: what was charged, when, and what waits for review (owners, admins and billing).

yard org invoices <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org invoices acme

yard org role

Change a member's role (owners and admins): it prints the teams page, where a person changes it in a browser signed in within 15 minutes (exit 8).

yard org role [OPTIONS] <ORG> <LOGIN> <ROLE>
Argument or flagMeaning
<ORG>The organization's slug
<LOGIN>The member's GitHub login
<ROLE>developer, member, admin or billing
--billingAlso let them see and manage billing; for a developer or a member, since owners and admins hold it already
--keep <KEY_ID>A key the member made to keep for the team instead of ending it (repeat it; ids from the board's role dialog)

Example:

yard org role acme octocat admin

An owner is made on the board.

yard org remove

Remove a member from an organization (owners and admins): it prints the teams page, where a person removes them in a browser signed in within 15 minutes (exit 8); every key they made ends unless kept for the team.

yard org remove [OPTIONS] <ORG> <LOGIN>
Argument or flagMeaning
<ORG>The organization's slug
<LOGIN>The member's GitHub login
--keep <KEY_ID>A key the member made to keep for the team instead of ending it (repeat it); every other key they made ends

Examples:

yard org remove acme octocat
yard org remove acme octocat --keep key_7 --keep acme-web/F2

The person who removes them chooses there which of their keys to keep for the team; a kept key keeps working and is that person's from then on.

yard org leave

Leave an organization: it prints the teams page, where you leave it in a browser signed in within 15 minutes (exit 8).

yard org leave <ORG>
Argument or flagMeaning
<ORG>The organization's slug, as yard org list shows it

Example:

yard org leave acme

yard org withdraw

Withdraw an open invitation (owners and admins).

yard org withdraw <ORG> <INVITATION>
Argument or flagMeaning
<ORG>The organization's slug
<INVITATION>The invitation's id

Example:

yard org withdraw acme inv_1

yard org invited

List the invitations waiting for you.

yard org invited

Example:

# lists them, with their ids
yard org invited

yard org accept

Accept an invitation waiting for you.

yard org accept <INVITATION>
Argument or flagMeaning
<INVITATION>The invitation's id

Example:

yard org accept inv_1

yard org decline

Decline an invitation waiting for you.

yard org decline <INVITATION>
Argument or flagMeaning
<INVITATION>The invitation's id

Example:

yard org decline inv_1

yard account

Your own account: where you are signed in, and which emails Switchyard sends you (signed in with yard login --github).

yard account <COMMAND>

Commands: yard account sessions, yard account emails, yard account agents.

yard account sessions

Where you are signed in, or sign one of them out; signing out everywhere is done in a browser.

yard account sessions

Commands: yard account sessions end.

Example:

yard account sessions

yard account sessions end

Sign out one sign-in by its id; with --all it prints the account page, where you sign out everywhere in a browser you are signed in to (exit 8).

yard account sessions end [OPTIONS] [ID]
Argument or flagMeaning
[ID]The sign-in's id, as yard account sessions shows it
--allSign out everywhere, this sign-in included: yard prints the account page, where you do it in a browser

Examples:

yard account sessions end s2
# prints the account page, where you sign out everywhere in a browser, this sign-in included
yard account sessions end --all

yard account emails

Which emails Switchyard sends you, or turn one kind on or off.

yard account emails

Commands: yard account emails set.

Example:

yard account emails

yard account emails set

Turn one kind of email on or off.

yard account emails set <KIND> <TURN>
Argument or flagMeaning
<KIND>needs-you, assigned, sent-back, digest or billing
<TURN>on or off

Example:

yard account emails set digest off

yard account agents

The agents you signed in over MCP, each for one organization, or end one's sign-in.

yard account agents

Commands: yard account agents end.

Example:

yard account agents

Signing the agent in again shows the consent page again.

yard account agents end

End one agent's MCP sign-in at once: its keys stop working, and it gets no new one.

yard account agents end <ID>
Argument or flagMeaning
<ID>The agent sign-in's id, as yard account agents shows it

Example:

# its keys stop at once, and it gets no new one
yard account agents end <id>

yard notifications

Your notifications: what needs you and what is for your information, or read, clear, mute and change them (hosted Switchyard, signed in with yard login --github).

yard notifications [OPTIONS]
Argument or flagMeaning
--org <ORGANIZATION>Put one organization in view, by its id or its slug: the number counts its needs-you rows; one you are not in is refused
--project <PROJECT>Put the organization of this project in view

Commands: yard notifications read, yard notifications clear, yard notifications mute, yard notifications unmute, yard notifications settings.

Examples:

yard notifications
yard notifications --project shop

The list reads the same sentences as the board's bell, and reading it marks nothing seen.

yard notifications read

Mark notifications read: by id, a task's, or a category's.

yard notifications read [OPTIONS] [IDS]...
Argument or flagMeaning
[IDS]...Notification ids, as yard notifications shows them
--project <PROJECT>The task's project
--task <TASK>The task's id, with --project
--category <CATEGORY>Every notification of one category; one of reviews, tasks, team, billing, security, projects

Examples:

yard notifications read <id> <id>
yard notifications read --project shop --task W12

yard notifications clear

Take notifications out of your list: by id, a task's, or all of them.

yard notifications clear [OPTIONS] [IDS]...
Argument or flagMeaning
[IDS]...Notification ids, as yard notifications shows them
--project <PROJECT>The task's project
--task <TASK>The task's id, with --project
--allClear your whole list
--yesWith --all: do it without asking

Example:

yard notifications clear --all

yard notifications mute

Mute a task or a whole project: it makes no notifications you can turn off; an ask of you by name still comes.

yard notifications mute <PROJECT> [TASK]
Argument or flagMeaning
<PROJECT>The project's id
[TASK]A task's id; leave it out for the whole project

Example:

yard notifications mute shop W12

yard notifications unmute

Lift a task's or a project's mute.

yard notifications unmute <PROJECT> [TASK]
Argument or flagMeaning
<PROJECT>The project's id
[TASK]A task's id; leave it out for the whole project

Example:

yard notifications unmute shop

yard notifications settings

Your notification settings, or change one.

yard notifications settings

Commands: yard notifications settings set, yard notifications settings unset, yard notifications settings summary.

Example:

yard notifications settings

yard notifications settings set

Turn a category's or a kind's channel on or off, for every organization or one.

yard notifications settings set [OPTIONS] <CATEGORY> <CHANNEL> <TURN>
Argument or flagMeaning
<CATEGORY>reviews, tasks, team, billing, security or projects
<CHANNEL>bell, summary or email
<TURN>on or off
--kind <KIND>One kind of the category, as yard notifications settings shows it
--org <ORGANIZATION>Only in this organization (its id)

Example:

yard notifications settings set tasks email off

yard notifications settings unset

Take one organization's exception away, so the choice for every organization applies there.

yard notifications settings unset [OPTIONS] --org <ORGANIZATION> <CATEGORY> <CHANNEL>
Argument or flagMeaning
<CATEGORY>reviews, tasks, team, billing, security or projects
<CHANNEL>bell, summary or email
--kind <KIND>One kind of the category, as yard notifications settings shows it
--org <ORGANIZATION>The organization whose exception goes (its id); required

Example:

yard notifications settings unset tasks email --org <organization id>

yard notifications settings summary

The daily summary: on or off, weekends, and its time zone.

yard notifications settings summary [OPTIONS] [TURN]
Argument or flagMeaning
[TURN]on or off
--weekends <WEEKENDS>on or off: whether the summary comes on Saturday and Sunday
--time-zone <TIME_ZONE>The summary's time zone, such as Europe/London

Example:

yard notifications settings summary on --time-zone Europe/London

Check yard and your shell

yard doctor

Check the URL, key, project, task remote, git and plain git push.

yard doctor

Examples:

yard doctor
yard doctor --json

Not signed in yet, or no project chosen yet, is a warning and exits 0; a script reads each check's status in --json (checks[].status).

yard feedback

Tell the Switchyard team, once, when one of its answers confused you or cost you a retry.

yard feedback [OPTIONS] <TEXT>
Argument or flagMeaning
<TEXT>What happened, up to 2,000 characters
--about <COMMAND>The command or tool the note is about, such as yard submit
--expected <TEXT>What you expected instead

Example:

yard feedback "submit's reason did not name the check" --about "yard submit" --expected "the check's name"

It changes nothing in your task, nobody answers it and no other agent reads it; secrets in it are redacted. yard sends its version with the note. At most 20 notes a caller and 200 a project each day.

yard api

Send one request to any route of the API with yard's key, for what no command does.

yard api [OPTIONS] <METHOD> <PATH>
Argument or flagMeaning
<METHOD>The route's method; one of GET, POST, PUT, DELETE
<PATH>The route's path from the root, such as /v1/projects/{project}/oplog
-q, --query <KEY=VALUE>A query parameter; repeat it for more
--body <JSON>The request's JSON body, or - to read it from stdin
--includePrint the answer's status and headers before its body
--yesSend a request that changes something without asking; needed off a terminal and with --no-input

Examples:

yard api GET /v1/projects/{project}/oplog -q since=120 -q limit=50
yard api PUT /v1/projects/{project}/reviews --body '{"reviews":"off"}' --yes
yard api GET /api/orgs

{project} and {task} are filled in as every command finds them: --project, SWITCHYARD_PROJECT or .git/yard.json. Routes under /api/ go with your sign-in, the others with the key every project command uses. It prints the answer as it came; an error prints and exits as every command's does. A request that changes something asks first at a terminal, and needs --yes off one. https://switchyard.so/docs/api lists the routes.

yard completions

Print shell completions.

yard completions <SHELL>
Argument or flagMeaning
<SHELL>Shell to generate completions for; one of bash, elvish, fish, powershell, zsh

Example:

yard completions zsh