# CLI reference Every `bay` command, grouped by what it acts on, with its flags and defaults. `bay` with no arguments prints the same list from the binary itself, which is the final word for the version you run. Every command below is a thin client of the control API, except `serve`, `doctor`, `version`, `connector` and `stack exec`. A client runs on the host, as root or a member of `bay-control`, and finds the socket from `BAY_SOCKET`, else at `./bay-data/control.sock`. On a host installed with the guide's unit, run `export BAY_SOCKET=/run/bay/control.sock`. `--control-socket PATH` overrides it for one command. An app instance is written `name/env`, a stack environment `stack/env`. A stack's service is the instance `stack.service/env`, as in `bay logs mcs.web/production`. ## Server | Command | Flags | | ----------- | ----------------------------------------------------------------------------------------------------------- | | `bay serve` | `--root ./bay-data` data directory | | | `--addr :8080` HTTP listener, `--tls-addr :8443` HTTPS listener | | | `--base-domain HOST` domain apps without their own are served under | | | `--tls`, `--acme-email MAIL`, `--acme-ca URL`, `--acme-ca-root FILE.pem` (a private CA) | | | `--acme-http-port N`, `--acme-tls-port N` challenge ports, default 80 and 443 | | | `--control-socket PATH`, `--control-group bay-control` | | | `--backup-interval 24h` (`0` disables), `--keep-releases 2` (minimum 2; per app, and stack revisions too) | | `bay doctor [--root /opt/bay/data] [--control-socket PATH]` | can this host run Bay; exits 1 on a failed check. On a live host pass the socket, or ports 80 and 443 fail | | `bay version` | the binary's version (`dev` for a local build) | ## Apps | Command | Does | | ----------------------------------------------------------- | ------------------------------------------------------------------------ | | `bay deploy (FILE\|-) [--name N] [--env E] [--domain D]... [--secrets-file F]` | deploy an artifact; `-` reads stdin | | `bay deploy --image REF@sha256:... --port N --name N [--health /path] [--env E] [--domain D]... [--secrets-file F]` | deploy a container image, by digest | | `bay deploy // (FILE\|-\|--image ...)` | deploy into a stack's app service | | `bay list` | every instance, as a JSON array | | `bay status [--json] [--backup-interval D]` | releases, process, traffic, backup freshness, warnings; exits 1 on a warning. `D` judges staleness against another schedule | | `bay logs (\|--name N [--env E]) [-n\|--lines 200] [--since 15m] [--grep RE] [--json]` | the container's log, at most 2000 lines; `--since` and `--grep` filter those on the client | | `bay stop ` | out of service until `start` or a deploy; survives reboots | | `bay start ` | back into service | | `bay remove [--purge]` | unregister; data kept unless `--purge` | | `bay env set (-\|FILE)` | merge `KEY=VALUE` lines; a changed value restarts the app | | `bay env list ` | variable names only | | `bay harden --relax writable-rootfs[,capabilities]` | lift isolation defaults for this app; replaces the previous set | | `bay harden --memory 1g\|default` | memory ceiling, 64m to 64g (default 512m) | | `bay harden --clear` | remove every relaxation; the memory ceiling stays | See [Deploying](https://latest.alepha.dev/bay/docs/guides-deploying.md) and [Operating](https://latest.alepha.dev/bay/docs/guides-operating.md). ## Runtimes and images | Command | Does | | ----------------------------------------- | ------------------------------------------------------------------- | | `bay runtimes` | pinned runtime images, and what each app runs | | `bay runtimes update` | pull newer digests; restart the apps whose image moved | | `bay runtimes set ` | this app's own image, from its next start | | `bay runtimes clear ` | back to the image Bay picks | | `bay config registry-mirror (HOST\|--clear)` | pull Docker Hub images through a mirror | ## Backups and storage | Command | Does | | ------------------------------------------------------------------------- | ---------------------------------------------------------- | | `bay config s3:backups --endpoint URL --bucket B [--region R] [--keep 14]` | where backups go; keys from `BAY_S3_ACCESS_KEY`, `BAY_S3_SECRET_KEY` | | `bay config s3:apps --endpoint URL --bucket B [--region R]` | where apps store uploads; keys from `BAY_STORAGE_ACCESS_KEY`, `BAY_STORAGE_SECRET_KEY` | | `bay config s3 --endpoint URL --bucket B [--region R] [--keep N]` | both from one credential (warned about) | | `bay backup ` | snapshot, verify, upload, now | | `bay backups ` | stored snapshots | | `bay restore [--key K]` | restore the latest or a given snapshot; old DB set aside | | `bay backup list / [service]` | a stack's service dumps | | `bay backup restore / [--from S/E] [--yes]` | restore a service dump | | `bay storage migrate ` | copy local uploads into the apps bucket, then repoint | See [Backups](https://latest.alepha.dev/bay/docs/guides-backups.md). ## Stacks | Command | Does | | -------------------------------------------------------------------- | -------------------------------------------------------- | | `bay stack deploy / (DIR\|compose.yml\|ARCHIVE\|-) [--dry-run]` | apply a bundle as a new revision (none: reapply) | | `bay stack rollback / --to N` | reapply revision N with the digests it pinned; `--keep-releases` prunes older revisions | | `bay stack list` | every stack environment | | `bay stack ps /` | services, kind, state, domains | | `bay stack logs / [-n 200]` | a service's log | | `bay stack restart / ` | app services blue/green, others in place | | `bay stack volumes /` | named volumes, sizes, and which no backup covers | | `bay stack exec / ` | `docker exec -it` in a service: needs a terminal and Docker access | | `bay stack env set\|list\|unset / ...` | stack variables; values from stdin or a file | | `bay stack route / ` | serve a full domain from a service | | `bay stack route list\|remove / ...` | list or remove routes | | `bay stack registry add / HOST --username U` | private registry; password from stdin | | `bay stack registry list\|remove / ...` | list or remove registries | | `bay stack stop\|start /` | durably out of service, or back | | `bay stack destroy / [--purge [--yes]]` | remove containers, routes and revisions; `--purge` also deletes volumes, variables and registries | See [Stacks](https://latest.alepha.dev/bay/docs/guides-stacks.md). ## Lore connector These edit a file beside `state.json` directly, so they run as root with `--root DIR` (or `BAY_ROOT`). They take `--control-socket PATH` (or `BAY_SOCKET`) too: `set` and `clear` tell the running `bay serve` to re-read the file through it, and `show` asks it for the connection state. | Command | Does | | ------------------------------------ | --------------------------------------------------- | | `bay connector set ` | enrol this host as an estate | | `bay connector show` | Lore URL, estate, connection state; never the secret | | `bay connector clear` | forget the Lore URL and secret | See [Lore connector](https://latest.alepha.dev/bay/docs/guides-lore-connector.md). ## Environment variables | Variable | Read by | | ------------------------------------------------- | -------------------------------- | | `BAY_SOCKET` | client commands: control socket | | `BAY_ROOT` | `bay connector`: data directory | | `BAY_S3_ACCESS_KEY`, `BAY_S3_SECRET_KEY` | `bay config s3:backups`, `s3` | | `BAY_S3_ENDPOINT`, `BAY_S3_BUCKET` | `bay config s3:backups`, when the flags are omitted | | `BAY_STORAGE_ACCESS_KEY`, `BAY_STORAGE_SECRET_KEY` | `bay config s3:apps` | | `BAY_STORAGE_ENDPOINT`, `BAY_STORAGE_BUCKET` | `bay config s3:apps`, when the flags are omitted | | `DOCKER_HOST` | `bay serve`, `bay doctor`: the Docker socket, `unix://` only; `tcp://` is refused |