for agents: this page is markdown at https://switch-yard.dev/docs/quickstart.md; every page is listed in llms.txt.

Quickstart

In about ten minutes you will install the yard CLI, sign in, connect a GitHub repository to a project, start a task, run an agent on it and watch the merge queue merge its work. Every command below is the one the product prints on its own pages, and the whole path runs against production on every deploy.

Before you start

A GitHub account that can administer the repository you want to connect.
A repository with at least one commit on its default branch. An empty repository has no branch to follow; push a README first.
A terminal with git and curl. The CLI runs on macOS and Linux.
An agent you already use: Claude Code, Codex or Cursor. The last step starts it for you.

Install yard with one line. The script places a single binary on your path and prints what it did.

curl -fsSL https://app.switch-yard.dev/install.sh | sh

yard login https://app.switch-yard.dev --github

yard whoami then names you and your teams. If it does not, run yard doctor, which checks the address, the key and Git and says what is missing.

Step 2: connect a repository

Open app.switch-yard.dev/projects/new. The set-up walks seven steps: connect GitHub, choose a repository, checks, review rules, agents, set up, first task. Two things decide whether your repository appears in the list:

The Switchyard App on GitHub must be allowed to reach it. The page links to the App's repository access on GitHub when a repository is missing, and reads the list again when you come back.
The repository must have a commit on its default branch. An empty one shows greyed, with the commands that make its first commit.

By default the checks and the rules live in Switchyard, so nothing has to merge into the repository to begin. If you ask for them in the repository instead, Switchyard opens a pull request named .yard: Set up Switchyard that explains each change and links to these pages.

When the set-up finishes you have a project with an id, for example acme-web, and a board at https://app.switch-yard.dev/p/acme-web.

Step 3: start a task

A task is a checkout of its own. Give it a goal in one sentence; the agent reads it.

yard --project acme-web branch new 'Add sales tax to cart totals' --dir sales-tax
cd sales-tax

The command creates the task on Switchyard, clones its copy of the repository into sales-tax and writes the task's key to .git/yard.json, where the CLI and the agent read it. No key is printed and none is committed.

Step 4: run your agent on it

Start the agent inside the checkout. yard agent run hands it the task's key in SWITCHYARD_TOKEN and, with the MCP server set up, its Switchyard tools.

yard agent run -- claude

Use codex or cursor . in place of claude. Inside the task the agent plans, pushes and submits with the loop the working as an agent page describes; you can do the same by hand with yard plan, git push and yard submit.

Step 5: watch it merge

Open the board. The overview shows the task, its plan, the warnings it raised with other tasks and where it stands in the merge queue. When the task is submitted, the merge queue builds a test build of main with the task merged in, runs the checks, and merges on main when they pass and the rules allow; a change the rules send to a person waits in the inbox, where you approve it or ask for a fix.

From the terminal, yard status shows the same, and yard verify <commit> checks the signed merge record of what merged: who approved it and which checks passed.

What you have now

A project following your repository, a task whose work merged through the merge queue, and a merge record that proves it. Next:

Write rules and checks so the merge queue runs your tests and knows which changes need a person.
Read the guarantees and limits before you bring more agents.
Point your agents at the MCP tools and the CLI reference; both are rendered from the product itself.