Docs Install the yard CLI
Install

Install the yard CLI

Updated October 5, 2026

yard is one command-line tool for two jobs: working with your workspaces from a terminal, and turning a machine into a runner. This page covers installing it and signing it in. To host workspaces on a machine, see Connect a runner. Every command is listed in the CLI reference.

The examples use the hosted Yard, https://api.useyard.app, which is also what yard talks to by default. If your organization runs its own Yard, use its API address instead.

macOS and Linux

Run the install script that the API serves:

curl -fsSL https://api.useyard.app/install.sh | sh

The script downloads the newest build for your system (Intel or ARM), checks its SHA-256 checksum and puts yard in ~/.yard/bin, or in /usr/local/bin when you run it as root. It needs curl and tar.

When the folder it installed to is not on your PATH, the script asks whether to add it to your shell's profile, for example Add ~/.yard/bin to PATH in ~/.bashrc? (Enter for yes, n for no). Enter adds the line once (it is never added twice); --yes adds it without asking. Without a terminal to ask on and without --yes it changes nothing and prints the line instead:

Shell The profile The line
bash ~/.bashrc (~/.bash_profile on macOS) export PATH="<folder>:$PATH"
zsh ~/.zshrc The same line
fish (printed only) fish_add_path "<folder>"
Any other ~/.profile The export line

When another yard comes first on your PATH (an older install in /usr/local/bin from a root install, say), the script says so once, with its version and the rm that removes it.

A new profile line reaches new terminals. Run it in the terminal you are in to use yard there straight away. For the default folder it is:

export PATH="$HOME/.yard/bin:$PATH"

Options go after sh -s --:

curl -fsSL https://api.useyard.app/install.sh | sh -s -- --dir ~/bin
Option What it does
--dir <path> Where to put yard.
--api <url> Download from another API than the one the script came from.
--token <token> Also set this machine up as a runner: the guided setup, with its own options such as --data-dir and --install-docker (see Connect a runner).

Without --token the script only installs the tool.

Windows

In PowerShell:

irm https://api.useyard.app/install.ps1 | iex

This puts yard.exe in %LOCALAPPDATA%\Yard\bin and adds that folder to your user PATH. New windows pick that up; for the window you are in, the script prints the line to run ($env:Path += ";<folder>"). Set YARD_DIR first to install somewhere else, or YARD_API to download from another API. Only x64 builds exist. Windows support is experimental.

Check the install:

yard version

Sign in

yard login

This signs in to the hosted Yard, https://api.useyard.app. Only when your organization runs its own Yard, say which one, with --api or YARD_API_URL:

yard login --api https://yard.example.com

yard login shows a short code and opens your browser. Check that the browser shows the same code, then confirm it. The terminal then says who you are signed in as. If you refuse in the browser, nothing is signed in. The code expires after 10 minutes; run yard login again if it does.

Signing in creates a personal API key named "yard CLI on" your computer's name. You can see and revoke it in Account → API keys, like any other API key.

Flag What it does
--api <url> The Yard API to sign in to. Without it: YARD_API_URL, then the API you last signed in to, then https://api.useyard.app.
--scopes <list> What the key may do, comma-separated: read, write, runners. Default: read,write.
--no-browser Do not open the browser. Open the address it prints yourself, on any device.
--with-key Use an API key you already have instead of the browser (see below).

The scopes are the same as for any API key. A command that needs a scope your key lacks says so; sign in again with more scopes.

Sign in with an existing key

On a server or in CI, where there is no browser, pass a key you created in Account → API keys, either on standard input or in YARD_API_KEY:

echo "$KEY" | yard login --with-key

The key is checked against the API before it is kept.

YARD_API_KEY also works without yard login at all: when it is set, every command uses it instead of a saved key.

Who you are signed in as

yard whoami

This prints your name, email address, the API and the organization commands use. Add --json for the same as JSON.

Sign out

yard logout

This revokes the key in Yard, so a copy of it left anywhere stops working too, and removes it from this computer.

Where the key is kept

The CLI keeps its key in your system's keychain when there is one:

  • macOS: the login Keychain.
  • Linux desktops: the desktop's secret store (such as GNOME Keyring), through secret-tool.

Elsewhere (a server, Windows, a container) the key goes in a file only your user can read: credentials.json in the CLI's config folder. The rest of what the CLI remembers (which API, which organization) is in config.json beside it. The config folder is:

  • ~/.config/yard on macOS and Linux ($XDG_CONFIG_HOME/yard when set);
  • %APPDATA%\yard on Windows.
Variable What it does
YARD_CREDENTIAL_STORE=file Always use the file, even where there is a keychain.
YARD_CONFIG_DIR Use another config folder.
YARD_API_URL The API to use when --api is not given. Without either: the API you last signed in to, then https://api.useyard.app.
YARD_API_KEY A key to use instead of the saved one.

The CLI keeps one sign-in per API address, so you can be signed in to several Yards and pick one with --api.

Updating

Run the install script again. It replaces yard with the newest build and keeps your sign-in:

curl -fsSL https://api.useyard.app/install.sh | sh

On a machine that is also a runner, yard update does the same and restarts every runner on it; see Connect a runner.

yard: command not found

Your shell looks for commands in the folders listed in PATH. The install script puts yard in ~/.yard/bin and changes PATH only when you say yes, so a new terminal may not find it. Run it once by its full path:

~/.yard/bin/yard version

It prints the version and then the line that adds its folder to PATH for your shell, with the file to put it in: ~/.bashrc for bash (~/.bash_profile on macOS), ~/.zshrc for zsh, fish_add_path for fish, and for PowerShell on Windows the command that adds it to your user Path. yard update and yard runner up print the same line (the setup started by the install script leaves it to the script). Nothing is printed once the folder is on PATH. yard runner up also names another yard that comes first on PATH, and its header line shows which yard runs.

In a Yard project's terminal yard, yard-canvas, yard-shot and yard-display are always found: they are part of the box. If one is missing there, the runner's box image is older than the runner; it is rebuilt when the runner updates (or with yard runner setup --rebuild).

Next steps