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
- Add
--jsonto any command: the answer is one JSON value on stdout, and a failure is{ "error": { "code", "message", "hint" } }on stdout with a non-zero exit code. The errors page lists the codes. - Add
--no-input, or setYARD_NO_PROMPT=1: yard never asks a question or opens an editor, and a command that needs an answer fails instead. - When a newer yard is out, yard says so in one line on stderr after a command, at most once a day and only at a terminal: never with
--json, never whenCIis set, and never as a failure.YARD_NO_UPDATE_CHECK=1turns it off. - Give a key in
SWITCHYARD_TOKEN, or pipe it toyard login; yard refuses a key typed as an argument. - Sign in without waiting:
yard login <url> --github --non-interactiveprints the link, the code to approve and the device code; piped on stdin,yard login <url> --complete -checks once and exits 8 while the person has not approved it. yard api <METHOD> <path>sends one request to any route with yard's key or sign-in, for what no command does.- Read Who under a command before running it. Some acts are a person's own: yard refuses an agent's or a script's run of them, and some only print a page for a person's browser.
Who may run a command
- agent allowed: a key works. A task key, an agent group key, an organization API key or the project's admin key, or a person's sign-in. The key's access decides the rest: a task key acts in its own task, and a command marked project admins only needs the admin key or an admin's sign-in. The MCP tools for the same routes are named.
- a person's sign-in. It takes the sign-in
yard login --githubsaves, never a key, and the MCP server has no tool for it, unless the line says otherwise. - a person only. yard refuses an agent's or a script's run: it knows Claude Code, Codex, Cursor and Gemini CLI by the variables they set, and CI services by theirs.
- a person in a browser. yard sends it with the person's sign-in, Switchyard answers that a person does it in a browser, and yard prints the page and exits 8; from yard, no key and no sign-in does it.
- browser only. yard sends nothing: it prints the page where a person does it in a browser signed in within 15 minutes.
- project admins only. A key or a sign-in works only with admin access to the project, such as the project's admin key or an admin's sign-in. A task key is refused. The MCP tools for the same routes are named.
- a key or a person's sign-in. Either works.
- the project admin key. Of keys, only this one does it; a person does it in a browser signed in within 15 minutes, and from a yard sign-in yard prints that page and exits 8.
- anyone. It needs no key or sign-in first.
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.
| Flag | Meaning |
|---|---|
--json | Print 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-input | Never 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
| Command | What it does |
|---|---|
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 whoami | Who the configured key belongs to: a signed-in person and their teams, or a project or task |
yard logout | Sign out: revoke a GitHub sign-in on Switchyard and forget the key |
yard init | Connect this repository to a project, creating it (optionally importing a repository) |
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 github | The Switchyard GitHub App, its install link and the installations you can use |
yard setup repos | The repositories of one installation, a page at a time or by search |
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 apply | Set a repository up with a plan: commit the rules and workflow changes, or open a pull request |
yard setup checks-on | Choose where a project's checks run: Switchyard's machines or the repository's own GitHub Actions |
yard branch | Start a task in its own checkout: yard branch new "<task>" |
yard branch new | Create a task and check it out |
yard branch list | List the active tasks, or the merged and abandoned ones newest first |
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 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 agent | Set up coding agents to work with Switchyard |
yard agent setup | Write a Switchyard skill for coding agents and an MCP config entry |
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 copy-again | Copy the followed GitHub repository into Switchyard again, after the first copy failed (project admins only) |
yard copy-history | Copy the followed repository's history behind main, or cancel that copy (project admins only) |
yard engine | The project's Git engine: wake it ahead of work (project admins only) |
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 plan | Write or update the task's plan ($EDITOR, --file or stdin JSON) |
yard claim | Say which paths and symbols the task will touch, beside its plan, and read what overlaps with them |
yard status | Graph of main, tasks, stacks and warnings, plus local changes with short ids to commit by |
yard commit | Commit chosen files or hunks by the short ids yard status shows (f3a9c, h52e1, ...) |
yard push | Send the pushes queued on this machine while Switchyard could not be reached, oldest first |
yard absorb | Fold working-tree changes into the commits they belong to |
yard split | Split paths out of a change into a new change |
yard squash | Squash a change into the change below it, or into --into |
yard edit | Amend a change in the stack with working-tree changes and/or a new message |
yard uncommit | Take a change (or some of its paths) out of the stack, keeping the edits locally |
yard move | Stack the task onto another task or main, or move a change within the stack |
yard tag | Set or remove a task's tags, or print them |
yard assign | Assign a task to a person, or clear its assignee with none |
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 warnings | What overlaps with this task and what to do about it |
yard notice | Switchyard's note on a task: what it last changed, its place in the merge queue, its conflicts and warnings |
yard conflicts | Open conflicts in every task with the resolution steps tried, and the ones resolved recently |
yard resolve | Run conflict resolution for the task's conflicts step by step, or send your own resolution |
yard submit | Submit the task to the merge queue |
yard review | Review inbox: list, approve, request a fix or comment |
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 request-fix | Ask the agent for a fix; the change waits until a new version is pushed |
yard review comment | Comment on a change |
yard pr | Pull requests of the project's GitHub repository in the merge queue: where one stands |
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 hotfix | Merge a queued task as a hotfix, before the rest of the merge queue (project admins only) |
yard priority | Merge a queued task in the priority lane, after hotfixes and before the normal lane (project admins only) |
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 log | The task's changes, or the project's history with --ops |
yard show | A change's versions, the reason behind it and its diff, or what changed between two versions |
yard why | Task, agent, plan and prompt behind a file or line |
yard undo | Undo an action (default: the latest one for this task) |
yard verify | Check the signed merge record of a merged commit: who approved it and which checks passed on it |
yard fetch | Fetch main and its merge records into refs/remotes/switchyard/<branch> |
yard check | A check's full log, and turning checks kept in Switchyard off, on or trying them again |
yard check log | Print a check's full log; without a name, list the checks whose full log is kept |
yard check off | Turn checks kept in Switchyard off: they hold no task and run on no test build (project admins only) |
yard check on | Turn checks kept in Switchyard back on (project admins only) |
yard check try | Try checks that are off once more on main: the ones that pass turn back on (project admins only) |
yard check tried | The checks' trial on main: each check kept in Switchyard with how it did there, and which are off |
yard check shell | Run one command in the machine a task's failed check kept, as the check ran; --done ends the machine |
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 queue | The merge queue: its health now, in one sentence and a few numbers |
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 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 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 set | Change one setting; it is recorded in the project's history and yard undo reverts it |
yard rules | The rules and checks kept in Switchyard: print them, or keep a rules file's text |
yard rules show | Print the rules and checks kept in Switchyard, as a rules file |
yard rules keep | Keep a rules file's text in Switchyard, replacing what is kept (project admins only) |
yard rules protect | List the protected areas the repository has and the rules miss, and add them (team admins) |
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 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 pause | Pause merging on main, during an incident or a release window (project admins only) |
yard resume | Resume merging after yard pause (project admins only) |
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 show | The project: its name, main branch, remote and the GitHub repository it follows |
yard project list | List the projects you can see, with their organization, team and your access (signed in) |
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 deletion | Whether a project is scheduled for deletion, and when |
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 keep | Cancel a project's scheduled deletion |
yard webhook | The project's webhook endpoints: list, add, test or remove them (project admins only), and check a delivery's signature |
yard webhook list | List the endpoints and how their deliveries go, never their secrets (project admins only) |
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 test | Send one test event to an endpoint and print its result (project admins only) |
yard webhook remove | Remove an endpoint and the events waiting for it (project admins only) |
yard webhook verify | Check a delivery's signature on this machine, with no network and no sign-in |
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 forget | Forget a remembered resolution, so the next conflict like it climbs the conflict steps again |
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 list | List the project's agent group keys, with the tasks each started |
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 org | Your organizations: members, invitations, API keys and AI fixes (signed in with yard login --github) |
yard org list | List the organizations you belong to, with your role and plan |
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 members | List an organization's members, their roles and teams, or one team's members |
yard org show | Show an organization: its name, plan, your role and its teams |
yard org teams | List an organization's teams, with their members and projects |
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 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 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 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 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 rename | Rename an organization; its slug, in every address, stays (owners and admins) |
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 invitations | List an organization's open invitations |
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 keys | List an organization's API keys (owners and admins) |
yard org audit | Read an organization's audit log: who did what, when and from where (owners and admins) |
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 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 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 disable | Disable a key until it is enabled again |
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 revoke | Revoke a key for good |
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 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 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 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 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 verify | Check a single sign-on connection's DNS records now; its domains are verified once every record is found (owners) |
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 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 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 delete | Print the page where an owner deletes an organization, in a browser signed in within 15 minutes (exit 8) |
yard org usage | This month's usage: merges, pushes, check seconds and AI suggestions, with the bill so far |
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 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 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 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 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 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 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 invoices | The organization's statements and their invoices: what was charged, when, and what waits for review (owners, admins and billing) |
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 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 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 withdraw | Withdraw an open invitation (owners and admins) |
yard org invited | List the invitations waiting for you |
yard org accept | Accept an invitation waiting for you |
yard org decline | Decline an invitation waiting for you |
yard account | Your own account: where you are signed in, and which emails Switchyard sends you (signed in with yard login --github) |
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 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 emails | Which emails Switchyard sends you, or turn one kind on or off |
yard account emails set | Turn one kind of email on or off |
yard account agents | The agents you signed in over MCP, each for one organization, or end one's sign-in |
yard account agents end | End one agent's MCP sign-in at once: its keys stop working, and it gets no new one |
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 read | Mark notifications read: by id, a task's, or a category's |
yard notifications clear | Take notifications out of your list: by id, a task's, or all of them |
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 unmute | Lift a task's or a project's mute |
yard notifications settings | Your notification settings, or change one |
yard notifications settings set | Turn a category's or a kind's channel on or off, for every organization or one |
yard notifications settings unset | Take one organization's exception away, so the choice for every organization applies there |
yard notifications settings summary | The daily summary: on or off, weekends, and its time zone |
yard doctor | Check the URL, key, project, task remote, git and plain git push |
yard feedback | Tell the Switchyard team, once, when one of its answers confused you or cost you a retry |
yard api | Send one request to any route of the API with yard's key, for what no command does |
yard completions | Print 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 flag | Meaning |
|---|---|
<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 |
--github | Sign in as yourself with GitHub: yard prints a link and a code to approve in the browser |
--non-interactive | With --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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: anyone: it needs no key or sign-in first.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a key or a person's sign-in: either works. MCP:
yard_whoami.
yard logout
Sign out: revoke a GitHub sign-in on Switchyard and forget the key.
yard logout
Example:
yard logout
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: anyone: it needs no key or sign-in first.
yard init
Connect this repository to a project, creating it (optionally importing a repository).
yard init [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--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) |
--force | Replace an existing connection in .git/yard.json |
Example:
yard init
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard setup repos
The repositories of one installation, a page at a time or by search.
yard setup repos [OPTIONS] --installation <ID>
| Argument or flag | Meaning |
|---|---|
--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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<OWNER/NAME> | The GitHub repository |
--plan | Print 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<TASK> | What the task is for |
--here | Check 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-task | Start 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_create.
yard branch list
List the active tasks, or the merged and abandoned ones newest first.
yard branch list [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--finished | The 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_finished.
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 flag | Meaning |
|---|---|
<TASK> | The task: its number or id, for example 8 |
--dir <PATH> | Clone into this directory (default: ./<task-id>) |
Example:
yard branch open 8
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_git_credentials.
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 flag | Meaning |
|---|---|
<TASK> | The task: its number or id, for example 8 |
--yes | Do 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_task_key.
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 flag | Meaning |
|---|---|
-y, --yes | Write 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
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 flag | Meaning |
|---|---|
<COMMAND>... | The agent to start and its arguments, after -- |
Example:
yard agent run -- claude
- JSON: no: yard starts the agent in its own place, so what follows is the agent's output; a failure before it starts prints as JSON with
--json. - Exit codes: the agent's own: yard becomes the agent, so it exits with the status the agent exits with; 1 or 2 when yard fails before the agent starts.
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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_copy_again.
yard copy-history
Copy the followed repository's history behind main, or cancel that copy (project admins only).
yard copy-history [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--cancel | Stop 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_copy_history.
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 flag | Meaning |
|---|---|
--wait | Stay 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 5.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_wake_engine.
Work in a task
yard plan
Write or update the task's plan ($EDITOR, --file or stdin JSON).
yard plan [OPTIONS]
| Argument or flag | Meaning |
|---|---|
-f, --file <FILE> | Read the plan JSON from a file, or - for stdin |
--show | Print the current plan without changing it |
Example:
yard plan
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
--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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_claim.
yard status
Graph of main, tasks, stacks and warnings, plus local changes with short ids to commit by.
yard status [OPTIONS] [BRANCH]
| Argument or flag | Meaning |
|---|---|
[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 |
--all | Include merged and abandoned tasks |
--local | Only show local changes; do not ask Switchyard |
--diff | Show the lines of every hunk |
-v, --verbose | List 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 |
--mine | Only the tasks assigned to you (after yard login --github) |
--watch | Follow 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 |
--once | With --watch: stop after the first change, with exit 0 |
--plain | With --watch: plain lines even on a terminal, one per change, as off a terminal |
--sessions | Group the tasks by person, then by the terminal or MCP session that started them, each subagent's task under its parent |
Example:
yard status
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 9.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
[ID]... | File (f3a9c) and hunk (h52e1) ids from yard status |
-m, --message <MESSAGE> | Commit message; required |
--all | Commit every local change |
--no-push | Commit locally without pushing to the task |
Example:
yard commit --message "Keep the total in cents"
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_warnings.
yard push
Send the pushes queued on this machine while Switchyard could not be reached, oldest first.
yard push --queued
| Argument or flag | Meaning |
|---|---|
--queued | Send 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 11.
- Who: agent allowed: a key works. MCP:
yard_git_credentials.
yard absorb
Fold working-tree changes into the commits they belong to.
yard absorb [ID]...
| Argument or flag | Meaning |
|---|---|
[ID]... | File and hunk ids to absorb (default: every local change) |
Example:
yard absorb
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_absorb.
yard split
Split paths out of a change into a new change.
yard split [OPTIONS] <CHANGE> <PATHS>...
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_split.
yard squash
Squash a change into the change below it, or into --into.
yard squash [OPTIONS] <CHANGE>
| Argument or flag | Meaning |
|---|---|
<CHANGE> | Change to squash |
--into <CHANGE> | Change to squash into (default: the one below) |
Example:
yard squash I8f3c2a91
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_squash.
yard edit
Amend a change in the stack with working-tree changes and/or a new message.
yard edit [OPTIONS] <CHANGE> [ID]...
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_op.
yard uncommit
Take a change (or some of its paths) out of the stack, keeping the edits locally.
yard uncommit [OPTIONS] [CHANGE]
| Argument or flag | Meaning |
|---|---|
[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_op.
yard move
Stack the task onto another task or main, or move a change within the stack.
yard move [OPTIONS] [CHANGE]
| Argument or flag | Meaning |
|---|---|
[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_op.
yard tag
Set or remove a task's tags, or print them.
yard tag [OPTIONS] [[BRANCH] KEY=VALUE]...
| Argument or flag | Meaning |
|---|---|
[[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_tag.
yard assign
Assign a task to a person, or clear its assignee with none.
yard assign [OPTIONS] <LOGIN|none>
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, the project admin key or an organization API key; a task key and an agent group key assign no task. MCP:
yard_assign.
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 flag | Meaning |
|---|---|
--wip | Commit 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_op.
yard warnings
What overlaps with this task and what to do about it.
yard warnings [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--branch <BRANCH> | Task to show (default: this checkout's task) |
Example:
yard warnings
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_notice.
yard conflicts
Open conflicts in every task with the resolution steps tried, and the ones resolved recently.
yard conflicts [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_conflicts,yard_conflict_sides.
yard resolve
Run conflict resolution for the task's conflicts step by step, or send your own resolution.
yard resolve [OPTIONS] [PATH]
| Argument or flag | Meaning |
|---|---|
[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_resolve.
Submit and review
yard submit
Submit the task to the merge queue.
yard submit [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--wait | Wait 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 |
--again | Accepted; 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 3, 4, 5, 7.
- Who: agent allowed: a key works. MCP:
yard_submit.
yard review
Review inbox: list, approve, request a fix or comment.
yard review [OPTIONS]
| Argument or flag | Meaning |
|---|---|
-i, --interactive | Ask what to do with each pending item, reading answers from stdin |
-v, --verbose | List 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, to list the review inbox; at a terminal yard asks a person about each change and sends what they choose as
yard review approve,yard review request-fixandyard review commentdo. MCP: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 flag | Meaning |
|---|---|
<CHANGE> | Change to approve |
-m, --message <MESSAGE> | Optional comment |
--wait | When the approval waits for your click in the browser, stay until you confirm it there |
Example:
yard review approve I8f3c2a91
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github: no key and no agent's account approves, and an approval that waits for the person's click in a browser prints its link and exits 8, or stays until it is confirmed with--wait. MCP:yard_review.
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 flag | Meaning |
|---|---|
<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"
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a key or a person's sign-in: a person signed in or the project admin key; no task key, agent group key or organization API key does it. MCP:
yard_review.
yard review comment
Comment on a change.
yard review comment [OPTIONS] --message <MESSAGE> <CHANGE>
| Argument or flag | Meaning |
|---|---|
<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"
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a key or a person's sign-in: a person signed in or the project admin key; no task key, agent group key or organization API key does it. MCP:
yard_review.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_pr_status.
yard hotfix
Merge a queued task as a hotfix, before the rest of the merge queue (project admins only).
yard hotfix [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--branch <BRANCH> | The task to merge first (default: this checkout's task) |
--off | Put 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_priority.
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 flag | Meaning |
|---|---|
--branch <BRANCH> | The task to merge first (default: this checkout's task) |
--off | Put 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_priority.
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 flag | Meaning |
|---|---|
[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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_workspace_op.
Look back
yard log
The task's changes, or the project's history with --ops.
yard log [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--ops | Show the project's history |
--since <SEQ> | Only actions after this seq |
-n, --limit <N> | Show at most N entries (the latest) |
--utc | Show the history's times in UTC instead of local time |
Example:
yard log
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_change.
yard why
Task, agent, plan and prompt behind a file or line.
yard why [OPTIONS] <PATH[:LINE]>
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_why.
yard undo
Undo an action (default: the latest one for this task).
yard undo [SEQ]
| Argument or flag | Meaning |
|---|---|
[SEQ] | Seq of the action to undo (default: the latest undoable one for this task) |
Example:
yard undo
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
[COMMIT] | A commit the merge queue merged: a revision here, or 7 or more hex digits |
--signer | Print 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_attestation,yard_signer.
yard fetch
Fetch main and its merge records into refs/remotes/switchyard/<branch>.
yard fetch
Example:
yard fetch
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_git_credentials.
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 flag | Meaning |
|---|---|
[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) |
--trial | Read 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_check_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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, with admin access; a task key and an agent group key turn no check off. Where people sign in, turning a check off loosens a review gate, so it is a person's in a browser: yard prints the project's settings page and exits 8. MCP:
yard_checks_off.
yard check on
Turn checks kept in Switchyard back on (project admins only).
yard check on <NAMES>...
| Argument or flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_checks_off.
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 flag | Meaning |
|---|---|
[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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_checks_try.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_checks_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 flag | Meaning |
|---|---|
<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 |
--done | End 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0 when the command succeeds; otherwise the command's own exit status in the kept machine (1 when it has none yard can pass on), and 1 or 2 when yard fails before the command runs.
- Who: agent allowed: a key works. MCP:
yard_check_shell.
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 flag | Meaning |
|---|---|
--days <DAYS> | How far back: 1, 7 or 30 days (default 7) |
Examples:
yard insights
yard insights --days 30 --json
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_insights.
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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_queue_health.
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 flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_value.
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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: agent allowed: a key works, the project admin key or an organization API key; a task key and an agent group key read no settings. MCP:
yard_settings.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, with admin access; a task key and an agent group key change no setting. Where people sign in, a change that loosens a review gate is a person's in a browser: yard prints the project's settings page and exits 8. MCP:
yard_setting.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, the project admin key or an organization API key; a task key and an agent group key read no settings. MCP:
yard_settings.
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 flag | Meaning |
|---|---|
<FILE> | The rules file, in the format of .yard/rules.toml; - reads it from standard input |
--try | Try 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works, with admin access; a task key and an agent group key keep no rules. Where people sign in, rules that loosen the ones kept before are a person's in a browser: a rule changed or dropped, a rule added that merges without review, an owners table dropped or eased, a check dropped or changed, a path excused from checks, or kept rules that no longer parse replaced; yard prints the project's settings page and exits 8. A tightening works from a key: rules added after the ones kept that hold a change for a person or block it, an owners table added or made stricter, a check added. MCP:
yard_rules_keep.
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 flag | Meaning |
|---|---|
[ID]... | The areas to add, by id |
--add | Add 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_unchecked.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_untested_guard_enforce.
yard pause
Pause merging on main, during an incident or a release window (project admins only).
yard pause [OPTIONS] --reason <TEXT>
| Argument or flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_pause.
yard resume
Resume merging after yard pause (project admins only).
yard resume
Example:
yard resume
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_whoami.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard project deletion
Whether a project is scheduled for deletion, and when.
yard project deletion [PROJECT]
| Argument or flag | Meaning |
|---|---|
[PROJECT] | The project's id (default: this checkout's project) |
Example:
yard project deletion
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard project keep
Cancel a project's scheduled deletion.
yard project keep [PROJECT]
| Argument or flag | Meaning |
|---|---|
[PROJECT] | The project's id (default: this checkout's project) |
Example:
yard project keep
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_webhooks.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_webhooks.
yard webhook test
Send one test event to an endpoint and print its result (project admins only).
yard webhook test <ID>
| Argument or flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_webhooks.
yard webhook remove
Remove an endpoint and the events waiting for it (project admins only).
yard webhook remove [OPTIONS] <ID>
| Argument or flag | Meaning |
|---|---|
<ID> | The endpoint's id, as yard webhook list shows it |
--yes | Do it without asking |
Example:
yard webhook remove wh_0123456789abcdef
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: project admins only: a key or a sign-in works only with admin access to the project. MCP:
yard_webhooks.
yard webhook verify
Check a delivery's signature on this machine, with no network and no sign-in.
yard webhook verify [OPTIONS]
| Argument or flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: anyone: it runs on this machine and sends nothing, so it needs no key or sign-in.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
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 flag | Meaning |
|---|---|
<KEY> | The resolution's key: 64 hex digits, as yard resolutions --json shows it |
--yes | Do it without asking |
Example:
yard resolutions forget <key>
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_resolutions.
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 flag | Meaning |
|---|---|
<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) |
--abandon | With revoke: also abandon the group's active tasks |
--yes | With 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: agent allowed: a key works, with admin access, to revoke a key or turn it off. Rotating one or turning it back on is a person's in a browser: from a yard sign-in or an organization API key yard prints the project's settings page and exits 8, and of keys only the project admin key itself still does it. MCP:
yard_agent_group_key.
yard group list
List the project's agent group keys, with the tasks each started.
yard group list
Example:
yard group list
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_agent_groups.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: the project admin key: a person does it in a browser signed in within 15 minutes, and from a yard sign-in yard prints that page (exit 8); no other key does it. MCP:
yard_agent_group_create.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person only: yard refuses an agent's or a script's run.
yard org members
List an organization's members, their roles and teams, or one team's members.
yard org members [OPTIONS] <ORG>
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org show
Show an organization: its name, plan, your role and its teams.
yard org show <ORG>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org show acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org teams
List an organization's teams, with their members and projects.
yard org teams <ORG>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org teams acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug |
<TEAM> | The team's slug, as yard org teams shows it |
Example:
yard org team delete acme payments
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard org rename
Rename an organization; its slug, in every address, stays (owners and admins).
yard org rename <ORG> <NAME>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
<NAME> | Its new name |
Example:
yard org rename acme "Acme Labs"
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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 |
--billing | Also 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard org invitations
List an organization's open invitations.
yard org invitations <ORG>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
# lists them, with their ids
yard org invitations acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org deleted acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org keys
List an organization's API keys (owners and admins).
yard org keys <ORG>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org keys acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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 |
--refused | Only 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 |
--csv | Print the matching events as CSV instead |
--jsonl | Print 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard org key disable
Disable a key until it is enabled again.
yard org key disable [OPTIONS] <ORG> <KEY>
| Argument or flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard org key revoke
Revoke a key for good.
yard org key revoke [OPTIONS] <ORG> <KEY>
| Argument or flag | Meaning |
|---|---|
<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) |
--yes | Do it without asking |
Example:
yard org key revoke acme key_7
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's 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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's browser.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's browser.
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 flag | Meaning |
|---|---|
[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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's browser.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's browser.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key. What is browser only here, yard does not send: it prints the page for a person's browser.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: browser only: yard sends nothing and prints the page where a person does it, in a browser signed in within 15 minutes.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: browser only: yard sends nothing and prints the page where a person does it, in a browser signed in within 15 minutes.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org usage acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
[ORG] | The organization's slug |
--month <YYYY-MM> | The month (default: this one) |
--csv | Print 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key, of an owner, an admin or a billing member lists who gets the billing emails. Adding or removing an address is a person's in a browser: yard prints the billing page and exits 8.
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 flag | Meaning |
|---|---|
[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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person only: yard refuses an agent's or a script's run. It sends nothing: it prints the page where a person does it in a browser signed in within 15 minutes.
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 flag | Meaning |
|---|---|
[ORG] | The organization's slug |
Commands: yard org card add.
Example:
yard org card acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the billing page where a person does it, signed in at any time, and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org invoices acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug |
<LOGIN> | The member's GitHub login |
<ROLE> | developer, member, admin or billing |
--billing | Also 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
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 flag | Meaning |
|---|---|
<ORG> | The organization's slug, as yard org list shows it |
Example:
yard org leave acme
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person in a browser: yard prints the page where a person does it and exits 8; from yard, no key and no sign-in does it.
yard org withdraw
Withdraw an open invitation (owners and admins).
yard org withdraw <ORG> <INVITATION>
| Argument or flag | Meaning |
|---|---|
<ORG> | The organization's slug |
<INVITATION> | The invitation's id |
Example:
yard org withdraw acme inv_1
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org invited
List the invitations waiting for you.
yard org invited
Example:
# lists them, with their ids
yard org invited
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org accept
Accept an invitation waiting for you.
yard org accept <INVITATION>
| Argument or flag | Meaning |
|---|---|
<INVITATION> | The invitation's id |
Example:
yard org accept inv_1
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard org decline
Decline an invitation waiting for you.
yard org decline <INVITATION>
| Argument or flag | Meaning |
|---|---|
<INVITATION> | The invitation's id |
Example:
yard org decline inv_1
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
[ID] | The sign-in's id, as yard account sessions shows it |
--all | Sign 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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2, 8.
- Who: a person's sign-in from
yard login --github, never a key, signs one sign-in out. With--allit is a person's in a browser: yard prints the account page and exits 8.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard account emails set
Turn one kind of email on or off.
yard account emails set <KIND> <TURN>
| Argument or flag | Meaning |
|---|---|
<KIND> | needs-you, assigned, sent-back, digest or billing |
<TURN> | on or off |
Example:
yard account emails set digest off
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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>
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
--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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard notifications read
Mark notifications read: by id, a task's, or a category's.
yard notifications read [OPTIONS] [IDS]...
| Argument or flag | Meaning |
|---|---|
[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
[IDS]... | Notification ids, as yard notifications shows them |
--project <PROJECT> | The task's project |
--task <TASK> | The task's id, with --project |
--all | Clear your whole list |
--yes | With --all: do it without asking |
Example:
yard notifications clear --all
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<PROJECT> | The project's id |
[TASK] | A task's id; leave it out for the whole project |
Example:
yard notifications mute shop W12
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard notifications unmute
Lift a task's or a project's mute.
yard notifications unmute <PROJECT> [TASK]
| Argument or flag | Meaning |
|---|---|
<PROJECT> | The project's id |
[TASK] | A task's id; leave it out for the whole project |
Example:
yard notifications unmute shop
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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 flag | Meaning |
|---|---|
<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>
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
yard notifications settings summary
The daily summary: on or off, weekends, and its time zone.
yard notifications settings summary [OPTIONS] [TURN]
| Argument or flag | Meaning |
|---|---|
[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
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: a person's sign-in from
yard login --github, never a key.
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).
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: anyone: it needs no key or sign-in first.
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 flag | Meaning |
|---|---|
<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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
- Who: agent allowed: a key works. MCP:
yard_feedback.
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 flag | Meaning |
|---|---|
<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 |
--include | Print the answer's status and headers before its body |
--yes | Send 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.
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.
yard completions
Print shell completions.
yard completions <SHELL>
| Argument or flag | Meaning |
|---|---|
<SHELL> | Shell to generate completions for; one of bash, elvish, fish, powershell, zsh |
Example:
yard completions zsh
- JSON:
--jsonprints the answer as JSON, and a failure as{ "error": { "code", "message", "hint" } }. - Exit codes: 0, 1, 2.