Lounge CLI

The previous pages described the application. This page describes the tools used to build, run and observe it: a command-line interface with six primary verbs and the checks associated with them.

A deployed application passes through a small number of recurring states: it is created, revised, placed into service, observed, stopped and later returned to service. The CLI assigns one command to each transition. The user chooses the transition; the tooling handles the ordering of steps, flags and environment variables needed to perform it.

The six verbs, in the order you will meet them:

Two auxiliary verbs exist — lounge dev, a hot-reload development loop, and lounge doctor, described below — but the six above are the life cycle proper. deploy is the once-per-configuration operation that produces reviewable files, while run starts from those files without asking the configuration questions again.

The checking machinery

Three distinct checkers run at different times, examine different things, and belong to different parts of the system.

The doctor examines your development machine. It runs automatically as the first step of lounge install, and on demand as lounge doctor. It verifies the JDK against the version the engine requires, the Maven wrapper, the freshness of the engine artifacts in your local repository, the availability of Docker and PostgreSQL (naming both as optional), and the port the development server wants. Its findings come with the exact remediating command; it fails the install only on hard requirements.

The metal preflight examines a production host. It runs inside lounge deploy --target metal — both when generating files and again under --up — and a copy of its JDK check is embedded in the generated run-metal.sh, because that script travels to machines where the CLI does not exist. This stack compiles with preview features enabled, and a preview-compiled class binds to the exact JDK major that produced it. A newer JDK refuses it just as firmly as an older one. "Version 25 or above" is therefore incorrect; the preflight reads the required major from your project's own build file and insists on equality.

The boot probes belong to the engine itself and run at every production start, regardless of how the application was deployed. They refuse an empty or well-known demo password, refuse a verification key that does not resolve, and refuse spec constructs the active edition does not license. They run independently of the two preceding layers.

The three form a sequence: the wizard generates, the doctor and preflight validate, and the boot probes refuse invalid starts. Each layer remains independent because it can observe defects the others cannot. Two such defects survived weeks of testing on development machines whose caches supplied artifacts that were absent on a customer's machine.

The configuration interview

lounge deploy obtains its configuration from one of three sources: flags, for those who know what they want (and for coding agents, which should always use flags); an interview, for those who do not yet know the platform's vocabulary; or a form in the Lounge UI. The UI submits the same flags to the same verb, so there is one deployment path regardless of how the questions were answered. For any caller that is not a person at a terminal, deploy --report first returns the specification analysis as a single line of JSON, and a deploy invoked without a terminal and without its flags refuses rather than guessing. The interview asks about the application, not about the configuration — whether people will sign in, where their accounts live, whether an operator needs a day-zero login — and derives the configuration from the answers. It first reads project.yaml before asking anything, because the specification already declares most of what a deployment needs: its SQL nodes declare the database requirement, its node types declare the minimum edition, and its ${env.*} references name the values the deployment must supply. A requested edition below what the specification requires is refused during the interview, with the same reasoning the engine would give at boot and before deployment begins. When an operator password is required, the interview generates one rather than relying on an operator-chosen value. (Callers that are not terminals request the same behavior with admin:auto; the password is written to deploy/secrets.env and travels no further — in particular, never through a browser or an agent transcript.)

The interview's output is files, not actions: an environment file in which every entry states its origin, a second file holding only the secrets — created with owner-only permissions and excluded from version control by the scaffold — and a runner for the chosen target. Nothing is applied until --up. The first file is meant for version control; the second is meant to be replaced, in production, by whatever secret manager your organization already trusts, rendering the same names. The engine validates secret quality at boot, while the deployment determines where those secrets are stored.

Two companion references ship inside the download, under docs/guide/: lounge-cli.md is the reference card for every verb and flag, and config-contract.md is the configuration catalog, with the exact failure text each mistake produces.