switchyard

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

Quickstart

Install the yard CLI, connect a GitHub repository, run an agent in a task and see the merge queue merge its work on main.

You will have: one task, worked by your agent, merged on main of your GitHub repository. Works with: yard and the board. Each step names the MCP tool or the route where one exists. Takes: about 10 minutes.

This page is a tutorial: follow it from start to end. The words it uses (task, merge queue, check) are on the concepts page.

Before you start

Ask your agent to do it

An agent that runs commands in your terminal can do every step of this page that is not a person's: Claude Code, Codex or Cursor. Start the agent in a clone of your repository and paste this prompt. The agent reads the pages as Markdown and works through yard. The steps after this section do the same by hand.

Set Switchyard up for this repository, through to one small task merged on main.

Read these pages first, and follow them:
- https://switchyard.so/llms.txt
- https://switchyard.so/docs/quickstart.md
- https://switchyard.so/docs/cli.md
- https://switchyard.so/docs/agents.md

Rules:
- Run each `yard` command with `--json`, and read its exit status. cli.md lists the exit statuses.
- Never print a key, never paste one into this chat, and never write one into a file that Git commits. `yard` keeps the keys in files of its own and reads them itself, so do not open those files.
- Never guess a command or a flag. Run only what the pages name.
- When a step is mine to do in a browser, stop. A command says so with exit status 8 or 10, or with a hint that names a page. Show me the link and tell me exactly what to click. Wait until I say that it is done, then run the command again.

Steps:
1. Install the CLI when it is missing: `curl -fsSL https://app.switchyard.so/install.sh | sh`. Check it with `yard doctor`.
2. Sign in as me: `yard login https://app.switchyard.so --github --non-interactive`. Show me only its `approval_url` and its `verification_code`, and wait while I approve the code in my browser. Then run the command in its `next_step` with its `stdin` piped in, never on the command line. Exit status 8 means that I have not approved the code yet.
3. Run `yard whoami`. When I own or administer no organization, stop: I make one in my browser, on the teams page at https://app.switchyard.so/teams.
4. Run `yard setup github`. When the Switchyard App has no installation that reaches this repository, show me the install link in the answer and wait while I install the App on GitHub. Then `yard setup repos --installation <id> --search <name>` says whether the repository is ready.
5. Make the project, in this clone: `yard init --github <owner>/<name>`.
6. Draft the checks and rules with `yard setup analyze <owner>/<name> --plan`, and keep the plan in a file outside the repository. Tell me what it holds. Then apply it: `yard setup apply <owner>/<name> --project <project> --plan <file>`. When the answer holds a pull request or a branch in place of a commit, show me its link: I merge it on GitHub.
7. Agree one small first change with me. Start a task for it: `yard branch new "<goal>" --dir <directory>`. Work only in that directory.
8. In that directory, connect yourself: `yard agent setup --yes`. Read the skill that it writes, `.agents/skills/switchyard/SKILL.md`, and follow its loop: `yard plan`, `yard commit`, `yard warnings`.
9. Submit the task and wait: `yard submit --wait`. Exit status 0 means that it merged. 3 means that the merge queue sent it back: fix it and submit again. 5 means that it still waits: tell me why.
10. Verify the merge: `yard verify <commit>`, with the `commit` in the answer of `yard submit --wait`. When that answer has no `commit`, run `yard status` and read the task's merged commit there. When neither has one, tell me so and stop: never guess a commit. Tell me the commit and what its merge record says.

What only you can do

Where the keys are: yard init saves the project's admin key in .git/yard.json of the repository where it ran. It prints the key nowhere, with --json or without, and yard setup apply handles no key. The task's key is in .git/yard.json of the task's directory, and your sign-in is in <home>/.config/yard/config.json. Git commits none of these files. The agent has no need to open them: yard reads the keys itself.

Step 1 — Install the CLI

Install yard, the command line tool that you and your agents use. The script downloads the binary for your machine.

curl -fsSL https://app.switchyard.so/install.sh | sh
Output
yard install: installed yard <version> to <directory>/yard
yard install: next: sign in with yard login https://app.switchyard.so --github

Check what yard finds on this machine:

yard doctor

yard doctor shows the git version, the Switchyard address, the key, and a hint for each item that is missing. Before you sign in, it shows not signed in yet with the hint sign in with yard login https://app.switchyard.so --github, and it exits with status 0.

Every yard command takes --json, for scripts and agents. yard is installed. Next, you sign in.

Step 2 — Sign in

Sign in with GitHub so that yard can act for you.

yard login https://app.switchyard.so --github

yard prints a link and a code, and waits. Open the link, check that the code is the same, and approve it.

Output
Open <link> and approve the code <code> to sign yard in as you.
Waiting for the approval (the code lasts 15 minutes)...
signed in to https://app.switchyard.so as @your-login; yard keeps the key in <home>/.config/yard/config.json

The code and the sign-in each have a lifetime; the limits page gives both. Check who you are:

yard whoami
Output
@your-login Your Name
teams: your-org (owner)

You are signed in. Next, you connect a repository.

Step 3 — Connect a repository

Connect your repository on the board. Open the set-up page:

https://app.switchyard.so/onboarding

The page has five steps: connect GitHub, choose a repository, agents, set up and first task. When hosted Switchyard requires a card, a card and plan step comes before first task. Install the Switchyard App on your repository, choose the repository, keep the drafted checks and rules, and click set up your-org/your-repo. Connect a GitHub repository explains each step and each choice.

Warning: The set-up shows the project's admin key one time only. Copy it to where you keep secrets before you leave the page.

Write down the project's id, for example your-project. The project exists. Next, you start a task.

Step 4 — Start a task

Start a task with its goal in one sentence. yard creates the task and clones the repository into a new directory.

yard --project your-project branch new 'Add sales tax to cart totals' --dir sales-tax

--project names the project. --dir names the directory for the clone.

Output
created task 8 · planning · Add sales tax to cart totals
its agent submits it when the work is done; the checks and review rules decide what merges
...
next: cd ./sales-tax && yard plan

Go into the clone:

cd sales-tax

The task's key is in .git/yard.json. Git never commits that file, and yard does not print the key.

MCP: yard_workspace_create · REST: the task routes on the REST API page

You have a task. Next, you connect your agent to it.

Step 5 — Connect your agent

Write the Switchyard skill and the MCP server entry into the clone, so that the agent has the Switchyard tools.

yard agent setup --yes

--yes writes the files without a question. The command writes .agents/skills/switchyard/SKILL.md, links it from .claude/skills/switchyard, and adds the project's MCP server to .mcp.json, which reads the task's key from SWITCHYARD_TOKEN. Codex and Cursor read their own settings files: Connecting has the entry for Claude Code, Codex and Cursor.

MCP sign-in, with no key. Claude Code and Codex can connect without a key. Add the project's MCP server with its address alone, then sign in from the client: /mcp in Claude Code, or codex mcp login switchyard in a terminal for Codex. Your browser opens Switchyard, you allow the client for one organization, and the agent then works as you on that organization's projects. The board's set up your agent page writes the entry with one command and shows when the agent has signed in. Cursor and other clients connect with a key, which their settings keep in plain text.

The agent is connected. Next, you start it.

Step 6 — Run your agent

Start the agent inside the clone with the task's key.

yard agent run -- claude

yard agent run reads the task's key from .git/yard.json, puts it in SWITCHYARD_TOKEN, and starts the command after --. Use codex or cursor . in place of claude.

Give the agent the goal. The agent plans, pushes and submits with the loop on the working as an agent page.

To do the same by hand: run yard plan, push with git push, then run yard submit. yard submit --wait waits until the task merges, is sent back or is abandoned, and its exit status says which. The CLI page lists every exit status.

The agent works in the task. Next, you see the work merge.

Step 7 — See it merge

Open the board at https://app.switchyard.so/p/your-project. The overview shows the task, its plan, its warnings and its place in the merge queue. The merge queue tests main with the task merged in, runs the checks, and merges on main when the checks pass and the rules allow.

When the rules send a change to a person, the change waits in the inbox. Review a change shows how to approve it or ask for a fix.

When the task merges, the commit is on main on GitHub.

Verify

Run yard verify with the commit on main:

yard verify <commit>

MCP: yard_attestation · REST: GET /v1/projects/<project>/attestations/<commit>

yard verify prints the merge record of that commit: each task with its approvals, a checks line, a signed line that says good signature with the key's fingerprint, and a tree line that says whether the tree matches the commit. The guarantees page says what the record holds.

From code

Every route is HTTPS with JSON answers, listed in the OpenAPI document and on the REST API page. Send a key in the header Authorization: Bearer <key>. Use the task's key for one task, the project's admin key for the project, or an agent group key for many agents.

Read who the key is, and then the project at a glance:

curl -sS https://app.switchyard.so/v1/projects/your-project/me \
  -H "Authorization: Bearer $SWITCHYARD_TOKEN"
curl -sS https://app.switchyard.so/v1/projects/your-project/status \
  -H "Authorization: Bearer $SWITCHYARD_TOKEN"

An error answers as { "error": { "code", "message", "hint" } }, and hint is there only when Switchyard has one. The errors page lists the codes. yard api GET /v1/projects/{project}/status sends the same request with the key that yard holds.

Next