The command is yard. The package name is staryard.
uv tool install staryardyard --helpyard alone prints help. Every command prints text, in a terminal and in a pipe. --json prints JSON instead. --json, --no-color, --url, and --token apply to a single command. yard --version prints the version.
Config lives at ~/Library/Application Support/yard/config.json on macOS, or $XDG_CONFIG_HOME/yard/config.json (~/.config/yard/config.json when that is unset). yard login writes that file. YARD_URL and YARD_TOKEN replace the saved values, and --url and --token replace both.
Commands that act on one app find it from the checkout: the origin remote must be an Origin or GitHub URL, and the branch must match the ref of exactly one app. --app overrides that lookup everywhere.
| Command | Use it when |
|---|---|
yard status [--running] [--full] | see the host; --full adds the checks |
yard login | save the host and token |
yard logs CONTAINER | read one container’s journal |
yard events | the merged Podman and Yard timeline |
yard prune | remove what no app needs (--days, --dry-run) |
yard app {ls,new,set,status,logs,deploy,cat,rm} | manage apps |
yard env {cat,get,set,unset,edit} | manage the app env |
yard forge {ls,setup} | connect Origin or GitHub |
yard repo new | create a private repo for the checkout |
yard caddy {cat,edit} | publish the app on a host |
yard token {ls,new,rm} | manage tokens |
Start#
yard login --url <url> --token <token>yard forge setup githubyard forge setup originyard app new --caddy <host>yard login saves the host and the token on this computer.
yard forge setup connects the host to a forge. origin prints the public key, the webhook URL, the event, and the scope to enter in the Origin app form. Then it asks for the App ID that Origin shows (it starts with app_) and opens the install page. github opens GitHub’s app form prefilled from a manifest; one click creates the app, and GitHub sends its ID, key, and webhook secret back to the command through a one-time callback on 127.0.0.1. Then it opens the install page and waits. --org creates the GitHub App in an organization. --public creates an app that any account can install; a private app installs only on the account that owns it. If saving the key in Yard fails, the command keeps it in a private file and the next run finishes the job. --new replaces a connected GitHub App and drops a setup that stopped halfway.
--existing connects a GitHub App that you already have, or one whose setup broke halfway. It asks for the App ID, the path of the private key file, and the webhook secret. --app-id, --key, and --webhook-secret give the same values without a question. When Yard refuses a value, the command asks again. Use --existing on a machine with no browser, too. --no-browser prints the links and opens nothing.
Every setup ends the same way: the command opens the install page and waits up to ten minutes for the installation. A GitHub setup on a connected host prints the app, its installations, and the link that adds another account, and stops.
yard forge ls lists each forge: whether it is connected, its app ID, its installations and their selection, and the last webhook.
yard repo new [NAME] creates a private repo on the forge for the checkout, points origin at it, and pushes the branch with your own git credentials. It needs a commit and no origin remote, and it never runs git add or git commit. The name defaults to the checkout’s folder. The repo lands under the account the Yard app is installed on; --owner picks one when there are several, and --forge picks github or origin when both are connected. The installation must cover all repositories. A failed push leaves origin wired, and the command prints the git push that finishes the job.
yard app new creates the app and deploys it right away, streaming the deploy log as it happens. --env-file PATH, -e/--env KEY=VALUE (repeatable), and --edit-env [PATH] set the app env before that first deploy: the file comes first, each -e pair goes on top, and --edit-env edits the result. The command checks the env before it creates the app. --edit-env needs a terminal. --edit-env opens $EDITOR with those values plus an env template: PATH, or else the first of .env.example, .env.sample, .env.template, and env.example at the top of the checkout. A key left empty in the editor is not saved. --no-deploy only creates it. Inside a checkout, the repo and branch come from it; --repo, --ref, and --app override them. The app name defaults to the repo name, plus -<branch> for a branch other than main or master. Inside a checkout, a --runs path must be a file in it. When no repo is found, the command stops and says to run yard repo new first. --trigger is push or manual — a manual app deploys only on yard app deploy. --caddy HOST writes the site file after the first good deploy: every host to <name>-app-1, on the one TCP port the container exposes, else 8000 for an app with a repo. Repeat --caddy for each host. An image or compose URL app that does not expose exactly one port gets the site printed, with PORT to fill in, and no file. --caddy with --no-deploy is refused.
An app has one source:
--repo URL, a repo on a forge.--refnames the branch,mainby default.--runssays which file in the repo the app runs.--image NAME:TAG, an image from a registry. It needs a tag or a digest.--compose-url URL, a compose file that Yard fetches overhttps://.
Two source flags in one command are refused. --ref and --runs work only with a repo.
--runs is auto, a path in the repo, or yard:<template>. With no --runs, every deploy decides from the commit: a compose file, then a Containerfile, then a Containerfile that Yard writes for the language it finds (How Yard reads a repo). A yard: template must fit the repo, or the deploy stops and names the one that does. An image or compose URL app takes its name from the image’s last segment or the file’s name, unless --app names it. What an app runs explains each source.
yard app set changes the source, the ref, --runs, or the trigger of an existing app. A new source replaces the old one: --image on a repo app drops its repo, ref, and runs. A change to what the app runs takes effect on the next deploy. On a push app, the next check deploys a new source, ref, or explicit runs; a move back to auto waits for the next commit. Otherwise the command prints the deploy line.
Daily#
yard statusyard status --fullyard app statusyard app logsyard app logs --deployyard logs heldso-app-1 -fyard events --app heldsoyard app deployyard status prints the container table: what is up and how long, CPU, memory, the size of the data directory, the revision, the hosts from the site file, and the last deploy. A last line sums the host’s CPU, memory, and data. A revision behind the remote tip shows both. A failed deploy points at yard app logs --deploy; a down container at yard logs <container>. --running hides stopped containers.
yard status --full adds the host checks — podman, the yard network, the apply image, Caddy, its admin socket, and its config, journald, the log driver of each container, the Yard event socket, each app’s healthcheck (Yard’s own too), and for each host its DNS, its certificate, and one HTTPS request through Caddy (/health for Yard, / for an app; a 5xx fails, a 4xx passes). Then the installations, the token, the last webhook, and the last check of each connected forge (a forge that an app uses but that is not connected fails), the daily prune, disk, and each app whose last check could not reach its source. The forge rows read the saved installations and the cached token, so a run asks the forge nothing new. Each row is ok, warn, or FAIL, and a row that is not ok names the next step. The command exits 1 when a check fails; a warning alone does not change the exit code.
yard app status opens one app’s page: the record, the Caddy hosts, the containers, the last deploy, and a log tail.
yard app logs reads the app container’s journal. --deploy reads the log of the last deploy from its deploy container, deploy-<name>. The container stays after the deploy, so the log survives a Yard restart. -f on a running deploy streams it from the first line — push deploys too. --container names another container of the app.
yard logs CONTAINER reads the journal by container name, 12-char id, or full id — even for a container that is gone. --tail defaults to 100 and counts entries read before filters; --since and --until take -15m, -1h, -2d (the minus sign is required), or 2025-01-31 14:00; -f streams.
Both take repeatable --hide EXPR and --only EXPR, applied on the host — there are no default filters. A field rule is key=value or key!=value (a * glob) and key>n or key<n on a JSON record (top-level key first, then attributes); anything else is a substring on the message. Lines sharing a trace_id keep or drop as one trace:
yard logs heldso-app-1 --hide request.path=/healthyard app logs --only status=erroryard logs heldso-app-1 --only 'duration_ns>100000000'yard events is the merged timeline of Podman and Yard events, read forward from a start, oldest first. The start is --since (the last hour by default) or --after <cursor>, and --until sets an end. --lines is how many rows, 200 by default. A full page prints more: yard events --after <cursor> on stderr; run it for the next page. --app, --container, --source podman|yard, and --event PREFIX narrow it. -f streams one table line for each event, and NDJSON with --json: from now, or from --since or --after when you give one. yard events --app heldso --event deploy. is that app’s deploy history.
yard app deploy deploys what the source says now and streams the log live — == runs names what runs before the build output, and Ctrl-C leaves the deploy running (yard app logs --deploy -f rejoins it). It deploys: the ref tip for a repo app, the image the tag points to for an image app, the file at the URL for a compose URL app. There is no --sha: to roll back, change the source — git revert and push, an older tag, or an older URL. A host that still holds the image, localhost/<name>:<sha12> (plus -<stamp> for a template app), skips the build.
Apps#
yard app lsyard app new --repo https://github.com/org/app --caddy app.example.comyard app set --trigger manualyard app rmyard app rm --yesyard app ls lists each app with its source (the repo, the image, or the URL), its ref, and its trigger. An image or compose URL app has no ref.
yard app cat compose prints the compose files of the running deploy, as plain text: the repo file at the deployed commit, Yard’s own compose files, or the fetched compose file. One file prints as it is; several files print each under a # <name> line. yard app cat containerfile prints the Containerfile that the running deploy built: a repo file, or the one Yard wrote. An app that builds no image from a Containerfile, such as an image app, gets a 404 that says so. A file that does not exist yet answers with the reason and the next command.
yard app rm removes the app: its site file, its containers, its clone, its env file, and its data. It first lists what goes and asks you to type the app name; --yes skips the question, and is required when stdin is not a terminal. The yard app cannot be removed.
Env#
yard env catyard env get KEYyard env set KEY=VALUE OTHER=VALUEyard env unset KEYyard env editThe app env is /srv/yard/apps/<name>/env on the host, mode 600. yard env cat prints it, and yard env cat > .env writes a dotenv file. yard env get KEY prints one value. yard env edit opens a copy in $EDITOR and saves it back; in a pipe it reads the new file from stdin instead (yard env edit < env.txt). The next deploy applies the file. The env never appears in an app response or in the journal: an env change logs the key names only.
Caddy#
yard caddy catyard caddy edityard caddy edit < site.caddyEach app has one site file, <name>.caddy. yard caddy cat prints it. yard caddy edit opens it in $EDITOR; in a pipe it reads the new file from stdin. Yard saves the file and loads Caddy. Caddy checks the whole config first. When Caddy refuses the file, Yard keeps the old one. The command prints the error with the file and the line, and asks Edit again? [Y/n]; no leaves Caddy on the site it had. An unchanged file prints No change.. An empty file removes the site. A site file is at most 64 KiB.
The default site sends every host to the app container and holds requests for 10 seconds while a deploy swaps it:
app.example.com, www.app.example.com { reverse_proxy app-app-1:8000 { lb_try_duration 10s lb_try_interval 250ms }}The file is plain Caddyfile. Add a host, basic_auth, forward_auth to a login service, or a handle_path block that sends one path to another container of the app.
Tokens#
yard token lsyard token new <name>yard token rm <name>yard token ls lists each token’s name and when it was made. yard token new <name> prints a token once. A name starts with a letter, then uses lowercase letters, digits, and hyphens, up to 63 characters; yard-* is reserved. yard token rm <name> removes it. You cannot remove the token you use. A removed admin token stays removed: Yard makes the first token only on a host with no token.
Other#
yard prune removes localhost/ images that no container uses. Each app keeps its running image and its 3 newest images; an image older than --days (7 by default) goes even when it is one of the 3. Then Podman’s own image prune removes the untagged build images older than --days; the newer ones are the build cache. --dry-run reports without removing. Its untagged count is a minimum: Podman’s prune also removes the parent layers that it leaves untagged. An app directory stays. yard prune waits up to 10 minutes for the answer. Yard also runs the same prune once a day by itself, first 10 minutes after it starts; YARD_PRUNE_DAYS in the yard app’s env sets the days, and 0 turns the daily run off.
yard <command> --help prints the flags for that command.
See also#
Day to day shows these commands in use.
API is the HTTP API behind every command.
Glossary defines app, site file, forge, check, and the other nouns.