CLI reference
Every yard command and flag, for signing in, working with workspaces, running a runner and hosting apps on it.
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 (else https://api.useyard.app), and restart every runner service on this machine. |
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.
On a machine that only uses the CLI, yard update installs the newest
build from https://api.useyard.app; you can also 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 (upload
them in Yard 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. Also logs to <data-dir>/logs/runner.log; --debug logs every git command with git's own trace. |
yard runner status |
The saved settings, whether the runner is running and connected, every organization it serves with its state (connected, connecting, failed and why), and whether a newer build exists (JSON). |
yard runner list |
Every runner service on this machine, with its data directory and state. Takes --json. |
yard runner config show |
The runner's settings and where each one comes from. Takes --json. |
yard runner config set token|mode|api|data-dir|home-root <value> |
Change one setting (home-root: the folder for new workspaces). The service is restarted and followed until it is online; --no-restart only saves it. |
yard runner add-org <org-id> <token> |
Let this runner serve another organization too (a multi runner machine). It starts within seconds, with no restart. Run again for an organization already added, it checks the new and the saved token with Yard: a rotated token is updated, a removed runner is replaced and its directory released, a runner that still works only with --replace. A token Yard refuses, or no answer from Yard, changes nothing. |
yard runner remove-org <org-id> |
Stop serving an organization. Its data stays under <data-dir>/orgs/<org-id>. |
yard runner org-layout rollback |
Restore the state taken before the per-organization data layout. Stop the runner first, then start the previous version. |
yard runner adopt-data-dir --yes |
Let the next runner to connect claim this data directory, when the runner it belonged to is gone for good. |
yard runner adopt-data-dir --org <org-id> --yes |
The same for one added organization's directory, <data-dir>/orgs/<org-id>. The running service opens its session again within seconds. |
yard runner doctor |
What this machine offers for hosting workspaces: mode, Docker image, GPU and other capabilities, and hosting's listen address and any clash with a direct address (JSON). |
yard runner check [--mode docker|direct] |
What this computer has and lacks to host workspaces: room to work, free disk, Git, the container engine (Docker Desktop, OrbStack, Colima, Rancher Desktop), WSL and virtualization on Windows, the workspace image. Each problem names its error code and guide. Exits 0 when the computer can host workspaces. Takes --json. |
yard runner install docker|git|python|wsl |
Install what check found missing: winget on Windows, the Docker Desktop download on a Mac, get.docker.com on Linux. Asks first; --yes when you agreed already. Takes --json. |
yard runner config set control ask|approved|org |
What Yard may do on this computer without asking you (local control). Only works on the computer itself. |
--json on up, setup, check, install |
One JSON object per line on stdout (step, detail, progress, check, install, next with the error code and guide, done), never a question; text for people goes to stderr. This is what Yard for desktop reads. |
yard runner help |
Print the command summary. Also yard runner and yard runner --help. |
One runner serves several organizations (add-org), so a machine rarely
needs more than one. For several runners on one machine, give each its own
data directory with --data-dir <path> on every runner command; each gets its
own service. up and start never run two runners on one data directory.
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 Register runner on the Runners page. |
--mode docker or --mode direct |
How workspaces run: in a container each (default), or as processes on the machine (discouraged). Saved for later runs. |
--home-root <folder> |
The folder for workspaces (default <data dir>/home; on Windows in direct mode the first run asks, Enter for %USERPROFILE%\yard). Saved for later runs. |
--yes |
Skip the confirmation for direct mode. |
--service or --no-service |
Install and start the background service instead of running in this terminal, or do not. Without either, it asks. |
--install-docker or --no-install-docker |
Install Docker when it is missing (Linux), or do not. Without either, it asks. |
--wait <seconds> |
How long to wait for the service to come online. |
--verbose |
Also show the runner's log and what the host commands said. |
--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, and on Windows a Scheduled Task that starts the runner when you sign in (in your desktop session, so a direct-mode runner can open windows and take screenshots).
| 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, or a terminal runner's log file when no service is installed. |
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. |
yard runner hosting
Hosting runs a project's apps on this runner, behind a proxy on this
machine. It is turned on and configured in the runner's settings in Yard
(domain, TLS mode, max apps, free subdomain on yrd.sh); these commands cover
only the parts that stay on the machine. See Apps.
yard runner hosting, yard runner hosting help and
yard runner hosting --help print a summary.
| Command | What it does |
|---|---|
yard runner hosting status |
What the runner last reported (domain, TLS, proxy, ports, tunnel) and the settings on this machine (JSON). |
yard runner hosting doctor |
Check that <domain> and a random *.<domain> name resolve to the same place, the _yard-verify.<domain> TXT record, Docker (and why it does not answer: not on PATH, no permission on the socket, the daemon not running, a timeout), what the running runner itself last saw of Docker and its proxy (with a warning when that differs from this check), the proxy image, that ports 443 and 80 (for http-01) are free or the proxy's (another container that holds one, such as coolify-proxy, is named, with how to move the listen address), a clash with a direct address, the Cloudflare token file for dns-01, the tunnel to the edge (or, in proxy mode, the certificate the edge pins), and the last error. Exits non-zero when something is wrong. |
yard hosting doctor [--json] [--apply] (also yard runner hosting doctor) |
Read-only diagnosis of hosting behind another proxy: states the deployment mode first, then an ok/warn/fail/skipped checklist, the proposed change as a diff and any manual steps. --json prints the report as data. Nothing is changed unless --apply is given, and the route is tested again after. See Hosting behind another proxy. |
yard runner hosting set … |
Save the settings that stay on this machine. Restart the runner (yard runner service restart) to apply them. |
Flags of hosting set:
| Flag | What it does |
|---|---|
--listen <host:port> |
Where the proxy listens. Wins over Listen address in the runner's Hosting settings in Yard; without either, 0.0.0.0:443. --listen yard drops the saved address, so the one set in Yard applies. |
--cert <file> |
A certificate file, for TLS manual. Given together with --key. |
--key <file> |
The certificate's private key file. Given together with --cert. |
--acme-email <email> |
The Let's Encrypt account for TLS http01 and dns01. |
--dns-token-file <file> |
For TLS dns01: a file (mode 0600) with a Cloudflare API token that may edit the zone's DNS. |
--web <url> |
Where visitors of team apps sign in. Default: Yard's web app. |
--tunnel-port <port> |
The local port the tunnel to yrd.sh is served on (127.0.0.1). Default: 7481. |
DNS: <domain> and *.<domain> point at this machine, and
_yard-verify.<domain> has the TXT record shown in the runner's Hosting
settings. With a free subdomain on yrd.sh in tunnel mode, no DNS and no open
port are needed. A direct address and hosting cannot both listen on 443:
move one.
Apps need Docker on the machine. The runner runs Traefik in a container on
the --listen address and each app in a container of its own.
yard hoster
yard hoster was the command of a separate hoster daemon. Hosting is now
part of the runner, and yard hoster stays for one release as an alias that
prints the new command: status and doctor run yard runner hosting status|doctor, start runs yard runner start, and up says to set up a
runner and turn on Hosting in its settings. A hoster's settings
(hoster.json) move into the runner's settings on its first start.
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 a canvas shows (ready, cloning, fetching, error); a failure also says why and when it happened. |
yard project list |
The open projects, each project's sub-projects indented under it (--json names each one's parent). |
yard project family |
The project's parent, siblings (its parent's other sub-projects) and sub-projects, with each one's state, branch and what it is about. |
yard project create --batch <file.jsonl|-> [--parent <project>] [--base main] |
Many sub-projects in one call: one JSON object per line, {"title", "instructions", "repos"?}. None of them starts; each one's instructions are its spec draft, and each starts from the parent's branch (--base main: from the main branch). Under the calling project, or --parent. One line in the chat links to the parent's Sub-projects card. At most 100 sub-projects per turn or terminal. |
yard project create --title "<title>" [--instructions <file>|-] [--repo <repo>[@<branch>]]… [--base <branch>] [--attach <path>]… [--parent <project>|--top-level] |
Create a follow-up project, set up but not started: in a project's box, a sub-project of that project (--parent puts it under another, --top-level under none). A sub-project's repositories start from the parent's branch (pushed first) while it is not merged. The instructions (a file, or - for stdin) are its spec draft: its spec.md holds them from the start, and it starts only when someone sends a message or changes spec.md. Without them the project is empty. Each repository gets a new ctr/… branch from <base>, by default the workspace's main branch of the repository (its default branch unless someone picked another), fetched first, so work merged since is in it; --repo <repo>@<branch> works on that existing branch as it is instead. --repo defaults to the calling project's repositories, and its linked blocks go with it; --attach adds a file (a path relative to ~/workspace). It prints the new project's name and URL, and the calling project's chat links to it. Needs edit access; at most three top-level projects per turn or terminal, and 100 sub-projects. |
yard project message (<project>|--parent|--siblings|--children) (--file <path>|-) [--no-wake] |
From a project's box: send a message to another open project's agent, or to all of the project's family at once (one message against the limit). Family messages keep to the workspace's setting that lets agents message each other, and show as "From …" with its relation (parent, sibling, sub-project). It appears in that project's chat, marked "From <project>" with a link back, and starts its agent on it (after its current turn when it is busy). --no-wake only delivers it; a project not started yet only gets it, and is not started by it; the message also goes on that project's canvas as a note, so its agent reads it in full when it starts. A turn that was itself started by a project message can answer, but its messages never wake the other agent. The sending chat gets a "Message sent to …" line. Needs edit access; at most ten per turn or terminal. |
yard comments list [--all] |
From a project's box: the comments people left on lines of the project's diff (its Changes tab). Each thread with its id, repository, path:line and side, the line as it read, whether it is outdated (the diff no longer has that line as it read), whether and when it was sent to the agent, and who said what. Only open threads; --all lists resolved ones too. |
yard comments resolve <thread> [--note "<what was done>"] |
From a project's box: resolve one of its diff threads once it is addressed. --note answers in the thread first. From an agent's turn the thread is resolved by that agent ("Resolved by Claude Code"), and the note is the agent's comment; from a terminal, by you. The Changes tab updates at once and the thread's notifications settle, as with Resolve there. Needs edit access. |
yard comments reply <thread> "<text>" |
From a project's box: answer in one of its diff threads without resolving it; an answer opens a resolved thread again, and the others in the thread are told. Needs edit access. |
yard chat list |
The chats you may write to: id, what each is about, status. |
yard chat message <chat|canvas:<id>|doc:<id>|project:<slug>> (--file <path>|-) [--no-wake] |
Send a message to another chat of the workspace (a doc's, a canvas's or a project's). It is shown there as from this chat and starts that chat's agent on it; --no-wake only delivers it. |
yard goal show | iteration |
A goal's agent: the goal with its decisions and projects, or the iteration this turn is and why it started. |
yard goal project add "<title>" --plan <file> |
A draft project with that plan as its spec, last on the goal's board. It starts once it is approved. |
yard goal section "<heading>", yard goal update --health <h> --text "<text>", yard goal repo <repo> [--branch <branch>], yard goal met |
Record a section added to goal.md, the goal's health, a repository it builds in, and that the goal is met. |
yard crew run <rule> "<task>" [--agent <name>] [--role <role>] [--wait] [--key <key>], yard crew status, yard crew cancel |
Hand part of the work to a crew rule: a child chat that gets only its task, within the workspace's limits. |
yard preview [<port>] |
The ports something in this project's box listens on, each with its private address, or the address of one port. People who can see the project open it signed in to Yard; a dev server on 127.0.0.1 works too, hot reload included. |
yard preview publish <port> [--public] [--label <name>] [--domain <domain>] [--until process|box|manual], yard preview unpublish <port> |
Give a port an address of its own on this box's runner, for the team or, with --public, for anyone, or take it away. Agents do this only when a person asks. |
yard canvas create "<title>" [--doc <doc id or title>] [--after "<heading>"] |
From the workspace's box: make a canvas of the workspace, listed under Canvases, and print its id, its directory, ~/workspace/sheets/<id>, where the yard-canvas commands work, and its address. With --doc it is also placed in that doc of the workspace as [[canvas:<id>]](title), at the end of the section --after names, or at the end of the doc. Needs edit access to the workspace; at most ten per turn or terminal. |
yard project note (<project>|--parent|--siblings|--children) --title "<title>" (--file <path>|-) |
From a project's box: put a Markdown note on another open project's canvas (or on each of its family's), ending with a line naming the sending project. It appears as canvas/<name>.md in that project, placed where it covers nothing; nothing is posted in its chat. Needs edit access; at most ten per turn or terminal. |
yard worktree list [--project <name>] |
A project's checkouts: repository, worktree or read-only, branch. |
yard worktree add <repo> [--base <branch>] [--readonly] [--project <name>] |
Check a repository out in the project as a worktree on its branch, or make a read-only checkout writable. With --base, a repository the project does not have yet starts from that branch instead of the workspace's, and its pull request goes into it. 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 the GitHub App's read-only access, so it works without a token in the box. |
yard git push [--project <name>] |
From your own terminal: Yard pushes the project's branches with your GitHub connection (the shell itself can only read). Refused in an agent's turn and for viewers. |
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 env <repo>/<app> |
Every variable the app runs with: its value (a secret's is masked), where it comes from (set by Yard, a database, a link to another app, the app's config, or an env value of the workspace or the project) and whether it needs a value or links to an app that is not there. |
yard app config show [<repo>] |
The resolved app configs, with the layer each comes from. In the workspace's box (no project): the workspace's apps over the org defaults, which is what every project sees. |
yard app config set <repo> <file.json> |
Save an app for this project only ({ "name", "spec" }, or { "apps": [...] }); people promote it. Agents propose apps as chat cards instead, and use this only when asked. |
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). |
yard criteria [--project <name>] |
The spec's acceptance criteria, numbered, with a tick on the ticked ones and the commits each stored tick was verified on; the Open: reason under an open one; each one's priority, area and tags when the spec has them ((must · Behaviour · #e2e)); the count, with the open must-haves (only they hold up the merge); and the last yard check. --json gives each item's priority, area and tags. |
yard criteria tick <n> [--note "<how>"] |
Tick criterion n in spec.md. Yard keeps the tick with the HEAD of each worktree in the project's directory (and the note), so it survives the runner losing its copy of spec.md, and the project's counts change at once. |
yard criteria open <n> "<reason>" |
Untick criterion n and put the reason under it (- Open: …). A tick Yard kept for it no longer holds. |
yard spec status [--project <name>] |
The project's state (Draft, Working, Done) and how many criteria are ticked, e.g. Draft · 5/5 criteria ticked, with (done when this turn ends) when an agent asked for Done. --json prints { ok, data: { status, label, criteria, pending } }. |
yard spec status done [--project <name>] |
Mark the project done. Refused while criteria that hold the merge are open (every open one, or the open must-haves of a spec that ranks its criteria) and nobody accepted them as is (it names them), while the project is set up or its spec written, and for a member who can only read the workspace. From an agent's turn it is applied when that turn ends without an error, a stop or a question, and no worktree is removed. From a person's terminal it is Mark done, at once. Only done can be set. |
yard check -- <command…> |
Run a check (yard check -- bun run check), print its output as it comes, and keep its exit code, duration, the last 4 kB of its output and the worktrees' commits in Yard. It exits with the command's own exit code. One argument after -- is run by the shell. |
yard tests config show <repo> |
How Yard runs the repository's tests: the commands, their output formats and the setup, with the latest baseline. |
yard tests config set <repo> <file.json> |
Set them for the workspace ({ "setup", "commands": [{ "name", "run", "format", "timeoutMin" }] }). See Test baselines. |
yard tests baseline <repo> |
Take the baseline at the head of the workspace's branch now and list what fails there. Exits non-zero when no baseline could be taken. |
yard tests compare <repo> [--cached] [--for "<criterion>"] |
Run the checkout's tests and sort the failures into new, also failing on main, and fixed; waits up to 30 minutes. Exits non-zero on new failures or a command with no result. --for marks that spec criterion blocked by the base branch when only the base's failures remain. |
yard tests base <repo> [--setup "<install>"] [-- <command…>] |
Run your last failing yard run in that repository (or the last run of the command after --) again at the head of the base branch, in the same directory, and list which of its failures fail there too and which are new. The result is kept with the run. --setup installs the dependencies first when the repository has no test config (--setup true when it needs none). Exits non-zero on new failures or when the base run has no result. |
yard run [--timeout <minutes>] [--memory [<size>]] -- <command…> |
Run a slow command (tests above all) with its output kept for Yard, so the project shows how far the run is: tests done of the total and the failing ones by name. The output and the exit code stay the command's. $YARD_TEST_PROGRESS names a file the command may write its own progress to. See Test progress. |
yard run [--memory [<size>]] -- <command…> |
Run a command, with its container's memory limit raised to <size> (8g, 6144m; by default the workspace's Check runs may use up to) while it runs, when the workspace allows it and the runner has room. The command always runs; yard run ends with its exit code. See agents. |
yard feedback ["<title>"] --details "<text>" [--area environment] |
Tell the people who build Yard what this environment lacks, with the runner's details, as sent by an agent on behalf of the person whose turn it is. Only when the organization turned on Let agents send feedback about the environment to Yard; at most five per turn. See feedback. |
yard flow list |
The workspace's flows: health, schedule, step count and last run. |
yard flow show <flw_…> |
A flow's steps and its last run, step by step, with why a failing step failed. |
yard flow create <file.json> [--draft [--sheet <sht_…>]] [--source <repo>:<path>]… |
Create a flow from { "name", "steps": […], "schedule", "active", "environmentId" } (the environment by name or id). Prints its id and the commands to run it and put it on the canvas. --draft makes a draft with its block on the canvas the turn was sent from (or the canvas --sheet names), connected to its repositories; in a project's box it is always a draft of the project. --source (repeatable) records a file it was written from. Needs edit access. |
yard flow update <flw_…> <file.json> [--source <repo>:<path>]… |
Change the fields the file holds. New steps mark the flow's linked files as checked; --source links more. Needs edit access. |
yard flow run <flw_…> [--env <name>] |
Run it now on the workspace's runner and print each step: status, response code and time, and for a failing step its error, failed assertions and the start of the body. Exits non-zero unless it passed. Recorded as an agent run from an agent's turn. Needs edit access. |
yard flow runs <flw_…> |
Its recent runs. |
yard cron list|show <cmon_…>|create <file.json> |
Cron monitors: their status, one with its ping URL and executions, or a new one from { "name", "schedule", "graceSeconds", "maxRuntimeSeconds" }. create takes --draft, --sheet and --source like yard flow create; a draft gets its ping URL when it is turned on. |
yard env list |
Monitor environments and their variables; a secret shows only that it is set. |
yard env set <environment> <NAME> [<value>|-] [--secret] [--create] |
Set a variable (- reads the value from stdin, so a secret never appears in the command line); --create makes the environment, with --draft, --sheet and --source like yard flow create. A secret's value is never shown again. Without a value the variable is only named, for a person to fill in (draft environments only), and a secret of a draft is always only named. Needs edit access. |
yard insight list |
The connected databases and the stats on the workspace's canvases. Not available in a project. |
yard insight tables [--source <name>] [--refresh] |
A connected database's tables and columns: names, types and which columns only people see the values of. No value is read. Tables never read before (or with --refresh) are read from the database first, which needs edit access; tables turned off for agents are only counted. Not available in a project. |
yard insight add "<question>" [--source <name>] [--viz stat|table|line|bar] [--sheet <sht_…>] |
Puts a stat on the canvas the turn was sent from (or the canvas --sheet names). The stat's own agent writes one read-only query; a person approves it before it runs. A database whose tables were never read is read first. Needs edit access. |
yard insight ask --sql "<query>"|- --title "<title>" [--viz …] [--value <col>] [--x <col>] [--y <col>,…] |
In a stat's own chat: hands in the query for the stat's question (- reads it from stdin). It is kept as a proposal and does not run until a person approves it on the block. |
yard incident list|show <inc_…> |
Incidents of the workspace's status pages, or one with its updates and postmortem. |
yard incident update <inc_…> <status> "<text>" |
Post an update (investigating, identified, monitoring, resolved); a published incident's subscribers are emailed. Needs edit access. |
yard incident postmortem <inc_…> [--brief] |
Draft a postmortem (or a brief) from the incident's evidence with your own agent account. Claims that cite no evidence are dropped; a person reviews and applies the draft in the app, and it is never published by this. Needs edit access. |
yard edit [--file <path>] |
Checked edits to many files in one call. Blocks come on stdin (or in <path>): a line <<<<edit <path>, the old text, ====edit, the new text, >>>>edit. Text is literal. Without --all the old text must match exactly once; with --all (the path may then be a glob, which skips .git and node_modules) every match is replaced and there must be at least one. Nothing is written unless every block matches: it then prints one line per file (a.ts: 2 edits, +3 -1), else what did not match, with exit code 1. Works without a session; yard edit --help prints the format. |
yard pg start|url|reset|stop |
A PostgreSQL server of this box's own, as your user, on 127.0.0.1 only: start prints its DATABASE_URL (postgres://[email protected]:<port>/yard), url prints it again, reset empties the database, stop stops it. Its data is kept in ~/.cache/yard/pg/<box>; it belongs to the box, not to the agent turn that started it (the turn does not wait on it, and the next turn does not stop it), and it stops with the box. |
yard redis start|url|reset|stop |
A Redis server of this box's own, as your user, on 127.0.0.1 only: start prints its REDIS_URL (redis://127.0.0.1:<port>/0), url prints it again, reset empties it (FLUSHALL), stop stops it. Its data is kept in ~/.cache/yard/redis/<box>; like yard pg, it belongs to the box, not to the turn, and it stops with the box. |
yard needs set desktop|machine [--os windows|macos|linux] [--real-screen] [--gpu] [--kvm] --why "<text>", yard needs show |
What a project needs from a machine its box is not. It is saved on the project and a card in its chat lets a person pick one of the organization's runners to run its checks on (Remote runs in the runner guide). |
yard remote runners|run [--timeout <min>] -- <command…>|status [<run>]|cancel <run> |
Run a command on the runner picked for the project, against its worktrees as they are now (uncommitted changes too). The log streams back and the exit code is yard's; what the command writes to $YARD_OUT comes back under .yard/remote/<run>/, PNGs also under .yard/screenshots/. 30 minutes by default, at most 120. |
yard android setup|start|shot -o <file.png>|install-expo-go [--sdk <n>]|stop |
An Android emulator in this box, to look at a React Native or Expo app's screens. setup downloads a JDK, the Android command-line tools, the emulator and an Android 14 system image into ~/.cache/yard/android (a few GB, once per workspace; run again, it downloads nothing). start boots an emulator on the virtual display and waits for it; it needs /dev/kvm, which a box has only when Android emulator (KVM) is on in the workspace's Runner settings, on a runner whose machine has KVM, and otherwise it refuses at once. shot saves a picture of its screen, install-expo-go installs the Expo Go that matches the app's expo version (then npx expo start --android), stop stops it. |
--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.
Next to yard, yard-shot takes screenshots: yard-shot url <url> (http
and https only), yard-shot file <file.html> and yard-shot dir <folder> [--path /page.html] (a local file or folder, served on 127.0.0.1 inside the
box for the picture), and yard-shot screen (the virtual display; on a
Windows runner in direct mode the PC's desktop, --monitor <n> one monitor
and --window "<part of the title>" one window); each with -o <file.png>.
Agents are asked to tick each criterion with yard criteria tick as soon as
it is verified, and to run the checks that verify it with yard check, so
the project's page shows which commit each tick and the last check were on.
Ticking a box in spec.md by hand still counts. When every criterion is ticked
and the work is committed, they run yard spec status done, so a project
worked on through chat does not stay a Draft.
When you ask a project's agent for a follow-up round (for example after its
pull request was merged), it creates the new project itself with
yard project create and says what it created. The new project waits for you,
with the agent's instructions already in its spec.md: its agent writes the
full spec once you open it and send a message or edit spec.md. Agents cannot start it, push, or open pull requests for it.
A project's agent can also hand work to another open project, or coordinate
work that overlaps, with yard project message (a hand-over or a question,
which wakes that project's agent) and yard project note (material to keep,
on its canvas). Both work while the other project's session is not running.
A project's agent works through the comments people leave on lines of its
diff with yard comments list, and resolves what it addressed with
yard comments resolve <thread> --note "<what was done>". These see only the
box's own project's comments, and do not work in the workspace's box.
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 | Where the runner keeps its data. With the compose file: unset, or a folder inside /var/lib/yard (Several runners on one server). |
RUNNER_HOSTING_LISTEN, RUNNER_HOSTING_CERT, RUNNER_HOSTING_KEY, RUNNER_HOSTING_ACME_EMAIL, RUNNER_HOSTING_DNS_TOKEN_FILE, RUNNER_HOSTING_WEB_URL, RUNNER_HOSTING_TUNNEL_PORT |
runner | The same as the flags of yard runner hosting set; they win over the saved ones. RUNNER_HOSTING_LISTEN also wins over Listen address in the runner's Hosting settings in Yard. |
The runner reads more settings from its environment; see Connect a runner.