CLI reference
This page lists every yard command. To install the CLI and sign in, see
Install the yard CLI; to set up a runner, see
Connect a runner.
yard help (or yard --help, yard -h) prints a summary of the commands.
General
| Command | What it does |
|---|---|
yard version |
Print the version. Also yard --version and yard -v. |
yard update |
Install the newest build from the API this machine is connected to as a runner, and restart the runner's service. |
yard update --check |
Only say whether a newer build exists. |
yard update --force |
Download, verify and install the newest build even when it is the version already running, then restart the service. Use it to repair an install. With --check it only reports. |
When the folder yard is installed in is not on your PATH, yard update,
yard version and yard runner up end with the line that adds it for your
shell; see "yard: command not found".
A runner started from a source checkout is not updated this way, with or
without --force: update the checkout.
yard update needs a runner connected on this machine. On a machine that
only uses the CLI, run the install script again.
Sign-in
| Command | What it does |
|---|---|
yard login |
Sign in: shows a code to confirm in the browser, then keeps a personal API key. |
yard login --with-key |
Sign in with an existing API key, read from standard input or YARD_API_KEY. |
yard whoami |
Who you are signed in as, on which API, and the organization in use. |
yard logout |
Revoke the CLI's key and forget it on this computer. |
yard login flags:
| Flag | What it does |
|---|---|
--api <url> |
The API to sign in to. Default: YARD_API_URL, then the API you last signed in to, then https://api.useyard.app. |
--scopes <list> |
Comma-separated scopes for the new key: read, write, runners. Default: read,write. |
--no-browser |
Print the confirmation address without opening a browser. |
--with-key |
Use a key from standard input or YARD_API_KEY instead of the browser. |
yard whoami takes --json.
Common flags
The commands under Sign-in (except login), Organizations and Workspaces
accept:
| Flag | What it does |
|---|---|
--api <url> |
Which Yard to talk to. Default: YARD_API_URL, then the API you last signed in to, then https://api.useyard.app. |
--org <slug> |
Which organization to use for this command, instead of the one picked with yard org use. |
When you belong to only one organization, it is used without asking.
Organizations
| Command | What it does |
|---|---|
yard org list |
Your organizations. The one commands use is marked with *. Takes --json. |
yard org use <slug> |
Make this organization the default for later commands. |
Workspaces
yard ws is short for yard workspace. A workspace is named by its slug
in the organization, as yard workspace list shows it, or by its id
(ws_…).
| Command | What it does |
|---|---|
yard workspace list |
Workspaces in the organization, with their status and runner. Also plain yard workspace. Takes --json. |
yard workspace status <ws> |
A workspace's status, its runner and your role in it. Takes --json. |
yard workspace shell <ws> |
Open a shell in the workspace's container, in this terminal. |
yard workspace pull <ws> [path] |
Copy a file or folder from the workspace to this computer. Without a path, the whole workspace. |
yard workspace push <ws> <local> [path] |
Copy a local file or folder into the workspace, optionally to path. |
Flags:
| Flag | Command | What it does |
|---|---|---|
--project <slug> |
shell |
Open the shell in a project's container instead of the workspace's. |
--to <dir> |
pull |
Where to put the files. Default: the current folder. |
--json |
list, status |
Print JSON. |
push sends text files only; binary files are skipped with a message (add
them on the canvas instead). If a file was changed in the workspace in the
meantime, the changes are merged rather than overwritten. Folders named
.git and node_modules are skipped.
Runner
Commands for running a runner on this machine. The same commands also work
without runner (yard up, yard start, …) and under the older name
yard-runner.
| Command | What it does |
|---|---|
yard runner up |
Prepare this machine, connect the runner and run it. |
yard runner setup |
Check Docker and build or pull the workspace image. |
yard runner enroll --token <token> |
Connect this machine to Yard with a runner token, without starting it. |
yard runner start |
Run the runner in this terminal, with the saved settings. |
yard runner status |
The saved settings, whether the runner is running and connected, and whether a newer build exists (JSON). |
yard runner doctor |
What this machine offers for hosting workspaces: mode, Docker image, GPU and other capabilities (JSON). |
yard runner help |
Print the command summary. Also yard runner and yard runner --help. |
Only one runner runs per machine. up and start say so, and do nothing,
when one is already running.
yard runner up
| Flag | What it does |
|---|---|
--api <url> |
The API to connect to, with --token. Default: https://api.useyard.app. |
--token <token> |
The runner's token, from Runners → Register runner. |
--mode docker or --mode direct |
How workspaces run: in a container each (default), or as processes on the machine (discouraged). Saved for later runs. |
--yes |
Skip the confirmation for direct mode. |
--service |
Install and start the background service instead of running in this terminal. |
--rebuild |
Build the workspace image again. |
--no-gpu |
Do not build the GPU image. |
--insecure |
Allow a plain http:// API address. |
yard runner setup
| Flag | What it does |
|---|---|
--rebuild |
Build the workspace image again even if it exists. |
--no-gpu |
Do not build the GPU image. |
yard runner enroll
| Flag | What it does |
|---|---|
--api <url> |
The API to connect to. Default: https://api.useyard.app. |
--token <token> |
The runner's token (required). |
--insecure |
Allow a plain http:// API address. |
yard runner service
The background service: launchd on macOS, systemd on Linux. There is no service on Windows.
| Command | What it does |
|---|---|
yard runner service install |
Install the service; it starts now and at every login or boot. |
yard runner service uninstall |
Remove the service. |
yard runner service status |
Whether the service is installed and running, whether it is connected to Yard, and its last log lines. Exits 0 when it runs, 3 when it does not. |
yard runner service start |
Start the service. |
yard runner service stop |
Stop the service. It starts again at the next login or boot. |
yard runner service restart |
Restart the service. |
yard runner service logs |
Show the service's log. |
Flags:
| Flag | Command | What it does |
|---|---|---|
--json |
status |
Print JSON. |
-n <lines>, --lines <lines> |
status, logs |
How many log lines to show (default 10 for status, 50 for logs). |
-f, --follow |
logs |
Keep showing new lines as they are written. |
yard runner direct
Serve terminals and file downloads to browsers on the runner's own https address. An organization admin then sets the address in the runner's Settings on the Runners page. Restart the runner after changing this. See A runner's own address.
| Command | What it does |
|---|---|
yard runner direct set --listen <host:port> |
Listen on this address, behind a proxy or tunnel that serves https. |
yard runner direct set --listen <host:port> --cert <file> --key <file> |
Listen on this address with your own certificate and key. |
yard runner direct off |
Stop serving browsers directly. |
Flags of direct set:
| Flag | What it does |
|---|---|
--listen <host:port> |
Required. For example 127.0.0.1:7443 behind a proxy, or 0.0.0.0:443 with a certificate. |
--cert <file> |
A certificate file. Given together with --key. |
--key <file> |
The certificate's private key file. Given together with --cert. |
Hoster
A hoster serves previews of workspaces under a domain of your own. It runs
on a separate machine with that domain. yard hoster, yard hoster help
and yard hoster --help print a summary.
| Command | What it does |
|---|---|
yard hoster up |
Save the hoster's settings and start serving, in this terminal. |
yard hoster start |
Serve with the saved settings, in this terminal. |
yard hoster status |
Show the saved settings (JSON). |
yard hoster doctor |
Check DNS for yard.<domain> and *.<domain>, the TLS setting, Docker and the proxy image, and whether a runner runs on the same machine. |
yard hoster up flags:
| Flag | What it does |
|---|---|
--api <url> |
The API to connect to (https unless it is this machine). Default: https://api.useyard.app. |
--token <token> |
The hoster's token (required). |
--domain <domain> |
The domain previews are served under (required). |
--web <url> |
Where visitors of team apps sign in. Default: the API URL without a leading api.. |
--listen <host:port> |
Where to listen. Default: 0.0.0.0:443. |
--tls off or --tls manual |
off (default): an https proxy in front serves TLS. manual: use --cert and --key. |
--cert <file> |
Certificate file, with --tls manual. |
--key <file> |
Private key file, with --tls manual. |
DNS: point yard.<domain> at the hoster's machine and *.<domain> at
yard.<domain>.
Apps need Docker on the hoster's machine. With Docker, the hoster runs
Traefik in a container on the --listen address and each app in a container
of its own; without it, the hoster only serves its own pages. See
Apps.
Inside a Yard box
Every Yard terminal and every agent has a yard command of its own. It
needs no sign-in, and it can only reach the workspace it runs in: in a
project's terminal, only that project. It acts as the person whose agent is
running, or who opened the terminal. Everyone in a terminal shares it, and
everything it can do needs edit access to the workspace anyway.
| Command | What it does |
|---|---|
yard whoami |
Who it acts as, with which role, in which workspace and project. |
yard repo list |
The repositories mounted in the workspace, with the status their block on the canvas shows (ready, cloning, fetching, error); a failure also says why and when it happened. |
yard project list |
The open projects. |
yard worktree list [--project <name>] |
A project's checkouts: repository, worktree or read-only, branch. |
yard worktree add <repo> [--readonly] [--project <name>] |
Check a repository out in the project as a worktree on its branch, or make a read-only checkout writable. Yard's Git view, Git panel and agents see it at once. |
yard worktree fetch [<repo>] [--project <name>] |
Refresh origin/* in a project's checkouts (one, or all of them) and print how far each is ahead of and behind its base. Yard fetches with your GitHub connection, so it works without a token in the box. |
yard app list |
The project's apps: state, hosted URLs, and "not on this branch". |
yard app start|stop|restart [<repo>/<app>|--all] |
Start (with what it depends on), stop, or restart one app, or all of them. |
yard app reset [<repo>/<app>|--all] [--keep-data] |
Remove an app's container, image and logs; its data too, unless --keep-data. |
yard app logs <repo>/<app> [--tail 200] [--follow] |
The build and run log. |
yard app db tables|rows|query <repo>/<app> … |
A database app's tables, a page of rows (<table> [--limit] [--offset]), or a read-only query. |
yard app config show [<repo>] |
The resolved app configs, with the layer each comes from. |
yard app config set <repo> <file.json> |
Save an app for this project only ({ "name", "spec" }, or { "apps": [...] }); people promote it. |
yard app ticket <url> |
A short-lived x-yard-ticket header that opens one of the project's team apps (yard-shot uses it by itself). |
--project is only needed in the workspace's own terminal. In a project it is
always that project. --json prints the answer as one line of JSON. A person
adds new repositories to the workspace in Yard: the box cannot.
Environment variables
| Variable | Used by | What it does |
|---|---|---|
YARD_API_URL |
sign-in, org, workspace | 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 |
sign-in, org, workspace | An API key to use instead of the saved one; also read by yard login --with-key. |
YARD_CONFIG_DIR |
sign-in, org, workspace | Where the CLI keeps its settings. |
YARD_CREDENTIAL_STORE |
yard login |
file: keep the key in a file even where there is a keychain. |
RUNNER_API_URL, RUNNER_TOKEN |
runner | Connect the runner from its environment instead of saved settings. |
RUNNER_DATA_DIR |
runner, hoster | Where the runner keeps its data. |
The runner reads more settings from its environment; see Connect a runner.