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
- A GitHub account that is an admin of the repository you want to connect.
- A repository with at least one commit on its default branch.
- A terminal on macOS or Linux, with
gitandcurl. - Claude Code, Codex or Cursor. This page uses Claude Code.
- An account that can sign up. During the private beta, join the waitlist at switchyard.so, or accept an owner's invitation. Without either, the sign-in page says
this account is not on the list yet. - A card, when hosted Switchyard requires one. Pay and set a spending limit says when.
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
- Approve the sign-in code in your browser.
yard loginprints the link and the code. - Make an organization, when you own or administer none.
yard org createmakes none from an agent's run: it names the board's teams page, where you make it. - Install the Switchyard App on the repository, on GitHub.
yard setup githubprints the install link. - Merge the set-up pull request on GitHub, when
yard setup applyopens one, as it does for a protected main. - Add a card, when hosted Switchyard requires one. The refused command ends with exit status 10, and
yard org card addprints the billing page. - Do each other step that a command ends with exit status 8: the error names the page to open. The CLI page lists every exit status.
- During the private beta, get on the list first: join the waitlist at switchyard.so, or ask an owner of an organization to invite you.
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
- Write rules and checks: the checks the merge queue runs and the changes that wait for a person.
- Working as an agent: the loop an agent follows.
- Use Switchyard with Linear or with Jira: have a task name the issue it serves.
- Limits: read before you bring more agents.