# 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.switch-yard.dev/install.sh | sh` and `yard login https://app.switch-yard.dev --github`. Every command takes `--json` for machine-readable output, and every failure prints a `hint:` line that says what to do next. This page is rendered from the CLI's own command definitions, so it says what the installed `yard` says.

## Global flags

| Flag | Meaning |
| --- | --- |
| `--json` | Print machine-readable JSON |
| `--color <WHEN>` | Colour output (NO_COLOR and non-terminals turn it off in auto) |
| `--project <ID>` | Project id (default: SWITCHYARD_PROJECT or .git/yard.json) |

## Commands

| Command | What it does |
| --- | --- |
| `yard login` | Save the coordinator URL and key 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 the coordinator and forget the key |
| `yard init` | Connect this repository to a project, creating it (optionally importing a repo) |
| `yard branch new` | Create a task and check it out |
| `yard plan` | Write or update the task's plan ($EDITOR, --file or stdin JSON) |
| `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 hotfix` | Merge a queued task as a hotfix, before the rest of the merge queue (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 status` | Graph of main, tasks, stacks and warnings, plus local changes with stable ids |
| `yard warnings` | What overlaps with this task and what to do about it |
| `yard sync` | Restack the task onto main; conflicts are recorded, never blocking |
| `yard commit` | Commit chosen files or hunks by stable id (f3a9c, h52e1, ...) |
| `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 move` | Stack the task onto another task or main, or move a change within the stack |
| `yard uncommit` | Take a change (or some of its paths) out of the stack, keeping the edits locally |
| `yard edit` | Amend a change in the stack with working-tree changes and/or a new message |
| `yard submit` | Submit the task to the merge queue |
| `yard resolve` | Run conflict resolution for the task's conflicts step by step, or send your own resolution |
| `yard conflicts` | Open conflicts in every task with the resolution steps tried, and the ones resolved recently |
| `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 log` | The task's changes, or the project's history with --ops |
| `yard undo` | Undo an action (default: the latest one for this task) |
| `yard fetch` | Fetch main and its merge records into refs/remotes/switchyard/<branch> |
| `yard verify` | Check the signed merge record of a merged commit: who approved it and which checks passed on it |
| `yard review` | Review inbox: list, approve, request a fix or comment |
| `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 github connect` | Print a one-time link that creates Switchyard's GitHub App on GitHub (needs the operator key) |
| `yard github status` | Show which GitHub App Switchyard uses (needs the operator key) |
| `yard doctor` | Check the URL, key, project, task remote and git |
| `yard completions` | Print shell completions |
| `yard review approve` | Approve the latest version of a change |
| `yard review request-fix` (also `yard review fix`) | Send the change back to its agent with a fix request |
| `yard review comment` | Comment on a change |

## Examples from the help

### yard login

```
Pass the key on stdin, which keeps it out of shell history and the process list:
  printf '%s\n' "$SWITCHYARD_TOKEN" | yard login https://switchyard.example.workers.dev
Without piped input, yard asks for the key without echoing it.
Or sign in as yourself with GitHub, approving a code in the browser:
  yard login https://switchyard.example.workers.dev --github
```

### yard tag

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

### yard assign

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

### yard hotfix

```
Examples:
  yard hotfix                      merge this checkout's task first
  yard hotfix --branch task-3 --off  put task 3 back in its turn
A hotfix applies to the head it was given: pushing to the task again drops it.
```

### yard pause

```
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.
```

## Exit status

```
  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
```