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

## Step 1: install the CLI and sign in

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

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

Sign in as yourself with GitHub. The command opens a page where you approve a code; nothing is typed into the terminal.

```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](https://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.

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

```sh
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](/agents) 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](/rules) so the merge queue runs your tests and knows which changes need a person.
- Read the [guarantees](/guarantees) and [limits](/limits) before you bring more agents.
- Point your agents at the [MCP tools](/mcp) and the [CLI](/cli) reference; both are rendered from the product itself.