@haakco/hostingctl 0.0.0-stage → 1.0.310

package/README.md

@@ -1,3 +1,659 @@
-# Temporary Holding Version
+# hostingctl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The hosting platform's API from a terminal, for a client's laptop and an operator's — one binary, one
+token, the same commands. It is **standalone**: no checkout, no database, no cluster credentials and no
+Infisical. It speaks to the public API over HTTPS with a Bearer token, exactly as the web app does, and it
+generates its own client from `api/openapi.json`, so its request and response types are the contract's own.
+
+Generation does **not** decide which operations have a command — a generated function nobody calls is a
+feature nobody can use. That accounting lives in `src/commands/operation-map.ts`, which names every published
+operation and either the route that reaches it, a shared read, a protocol consumer, or the one policy conflict
+with no route; `just cli-test` fails when an operation is unaccounted for or a mapped route does not exist.
+
+All **370** published operations are accounted for: **362** are reachable from a command, 6 are protocol
+consumers the API calls rather than a person (the asset reader, the broadcast authenticator, the state
+manager's intent resolver, the webhook client, the GitHub webhook and first-party authorization), 1 is the
+company read the `--company` resolver shares, and 1 is deployment rollback, which stays open because the
+platform never downgrades a live release.
+
+## Install
+
+```bash
+npx @haakco/hostingctl --version     # no install at all
+npm i -g @haakco/hostingctl          # install, once
+```
+
+Node 22 or newer runs the CLI, and nothing else — no checkout, no database, no cluster credentials. The
+package also publishes a self-contained executable per platform (`@haakco/hostingctl-linux-x64` and its
+four siblings, `@haakco/hostingctl-linux-arm64`, `@haakco/hostingctl-darwin-arm64`,
+`@haakco/hostingctl-darwin-x64` and `@haakco/hostingctl-windows-x64`); that package's `bin` **is** the
+native binary, so a machine with no Node installs the platform package directly and needs no runtime.
+
+`hostingctl update` brings a copy to the published version: it detects how the copy was installed,
+prints the command it will run, runs it, and reads the installed version again to confirm the change.
+`hostingctl update --check` reports the published version and that command without changing anything.
+For a global npm install the command is `npm i -g @haakco/hostingctl@latest`.
+
+`hostingctl --version` reports the version of the copy that is running; a development build reports
+`0.0.0-dev`.
+
+## Authenticate
+
+**A client** signs in with the platform's **authorization-code/PKCE** flow. The CLI keeps the session in a
+**mode-0600 credential file** at `~/.config/hostingctl/credentials.json`, inside a 0700 directory, and checks
+that mode on read — a wider file is refused rather than read. Access tokens last 60 minutes; the refresh token
+owns the lifetime and rotation is the mechanism, so a command spends the stored session and renews the access
+token silently rather than holding a long-lived credential. The protocol, its rules and the reasons for them
+are owned by
+[authentication patterns](../docs/development/authentication_patterns.md) — this README does not restate
+them.
+
+**For local work**, use the development fixtures owned by
+[test users](../docs/development/test_users.md): they exist only in local, `DevelopmentSeeder` creates
+them, and their password is public development data rather than a credential.
+
+Sign in with the public client's registered ID:
+
+```text
+hostingctl login --api-url https://api.example.com/api/v1 --client-id <client-id>
+```
+
+The browser completes sign-in and consent. Before the session is written, the API is asked who the new token
+is (`GET /me`): a token Passport minted but the API will not act on is a failed sign-in, and the working session
+it would have replaced is left alone.
+
+Without `--token`, subsequent commands use that saved session. For automation, set `HOSTINGCTL_API_URL` and
+`HOSTINGCTL_TOKEN` instead. The isolated local acceptance proved real browser consent and refresh-token
+rotation on 2026-10-08.
+
+### Named sessions
+
+One credential file holds several sessions. Each is a profile:
+
+```text
+hostingctl login --profile staging --api-url https://api.staging.example.com/api/v1 --client-id <id>
+hostingctl whoami --profile staging            # or HOSTINGCTL_PROFILE=staging
+hostingctl auth status                          # the session a command would use, and its expiry
+hostingctl auth logout --profile staging        # revoke at the API, then remove it here
+```
+
+Signing in makes that profile the default; `--profile` or `HOSTINGCTL_PROFILE` selects another. A file in the
+older single-session shape is read as the `default` profile and rewritten in the profile shape on the next
+save, so no one has to migrate by hand. A session is **bound to the target it was issued for**: `--api-url`
+naming a different host is refused before any request rather than spending the token there.
+
+### A machine with no browser
+
+`--no-browser` prints the authorize URL, then reads the callback URL pasted on stdin. This is the case where
+the browser runs on another machine and cannot reach this host's `127.0.0.1:8477` listener. Only the exact
+registered redirect URI is accepted back, the state is compared, and neither the pasted URL nor its code is
+ever echoed. The port is fixed because Passport matches redirect URIs exactly; if `8477` is in use the CLI
+says which port to free instead of silently choosing another one.
+
+### The account and impersonation
+
+`auth` also covers the account itself: `profile`, `password`, `register`, `forgot-password`,
+`reset-password`, `verify-email`, `closure show|request`, `picture set|remove` and `notifications`
+(including `read <id>` and `read-all`). Every secret comes from `--<name>-file <path>` or `--<name>-stdin`,
+never from an argument, and is never printed. `closure request` re-reads the review and sends its digest, so a
+decision made against a different review is refused rather than confirmed.
+
+`auth impersonate start --target <user-uuid> --company <slug> --reason <text> --store-as <profile>` writes the
+impersonation token to **its own profile**. The operator's session is never replaced and is not made non-default;
+act as the target with `--profile <name>`, and `auth impersonate stop` ends it and removes that profile.
+
+Repository operators can reuse the approved in-process login without copying a token:
+
+```text
+just deploy-auth https://hosting-staging.haakdev.com OPERATOR_HOME_STAGING dev cli whoami --json
+```
+
+The helper supplies the CLI's documented environment variables, refuses URL/token overrides and
+preserves its exit status. Build the internal artifact with `pnpm --filter @haakco/hostingctl build`
+first. This adds no Infisical dependency to the standalone CLI. The credential still has only its
+own company authority; CLI writes require approval and `--confirm`.
+
+`src/live.integration.test.ts` is the real call, gated on the environment:
+
+```text
+HOSTINGCTL_API_URL=http://localhost:8000/api/v1 HOSTINGCTL_TOKEN=<token> \
+  pnpm --filter @haakco/hostingctl test
+```
+
+## Usage
+
+```text
+hostingctl whoami            Which account the token belongs to, and what it may do.
+hostingctl whoami --json     The same answer using the API's own field names.
+```
+
+Every command takes `--json`, and automation should prefer it: the field names are the API's, never a
+second naming invented here. Human-readable output is the default.
+
+Read the private supplier traces for a domain with:
+
+```text
+hostingctl registrar history <domain-uuid> --company acme --json
+hostingctl registrar history <domain-uuid> --company acme --page 2 --json
+hostingctl registrar supersede-transfer <domain-uuid> --company acme --operation <operation-uuid> --accept-terms --dry-run
+```
+
+This requires domain management permission and returns up to 100 entries from the preceding month.
+The API decrypts request and response bodies for this explicit read; the output can contain customer
+contact details and should be handled as sensitive evidence.
+The command prints a `--page` hint when older entries remain.
+
+### The command surface
+
+`hostingctl --help` lists every top-level command, and `<command> --help` prints that command's own groups,
+its flags and what each one does. The whole surface, with every flag, is in the
+[command reference](https://hosting.haak.co/docs/cli-reference), which is generated from the CLI's own
+metadata and compared against it in CI. The groups, in one line each:
+
+| Command | Covers |
+| --- | --- |
+| `whoami`, `environments`, `system`, `diagnostics` | The session's identity and reach, every environment in a company, what the cluster still holds, and the platform's health answer |
+| `company` | The company itself, its members and roles, its activity, its logo and favicon, and the invitation journey |
+| `environment` | Create, read, scale, retry; profile coverage, domains and redirects, databases and exports, configuration and secrets, services, site access, shared runtime and application, tools, tuning, retention, portable export, and the release bundle |
+| `application` | Create, rename, remove; build and deploy, build logs, runs and run logs, process schedules; recovery review and confirm; the HTTP cache and path routes; source binding; site access; the WordPress import and URL repair; the administrator credential |
+| `access` | Who may reach one environment: settings, grants, SSH keys, the shared password, and the per-user view |
+| `site-user` | The accounts that sign in to a company's sites |
+| `keys` | The account's personal SSH keys and where each is granted |
+| `email` | The mail service, its names, mailboxes, aliases, sending holds, send-as grants, IMAP sync (including CSV), and the platform's deliverability monitoring |
+| `mailbox` | Mail-client setup, the fallback recovery address and reset links for one mailbox |
+| `dns` | A managed name's zone, its zone-file export, records, signing, handover, and the reviewed template import |
+| `domain`, `registrar` | The names a company holds, their proofs and releases; the registrar's state, price, consent writes and supplier traces |
+| `cancellation`, `deletion-lock`, `backups`, `logs`, `services` | Cancelling an environment, arming its deletion lock, its backup tracks, its retained history, and its service inventory |
+| `realm`, `repository` | One environment's deployment realm; the GitHub connections an application deploys from |
+| `platform` | Platform-only work: domain claims and purge attestations, the client directory, company and account closure, alerts, the GitHub App, Yahoo feedback, and the prepared-content catalogue |
+| `login`, `auth` | Signing in and out; the session's own reads, the account's settings, push tokens and impersonation |
+
+Every write needs `--confirm`; `--dry-run` describes the change and sends nothing.
+
+Options: `--api-url` (or `HOSTINGCTL_API_URL`) — the API base **including `/api/v1`**, which is
+also the frontend's `VITE_API_URL` default — `--token` (or `HOSTINGCTL_TOKEN`), `--json`, `--help`.
+
+Exit status: **0** ok, **1** refused by the API, **2** unusable — bad usage, no token, or an unreachable
+API. A refusal prints the API's message, its actionable `detail` when it sent one, and its `X-Request-Id`,
+which is what joins a failed command to the log line that explains it.
+
+## Access users
+
+Create a native login using an existing public SSH key file, not a private key or a password on argv:
+
+```text
+hostingctl access user add <uuid> --company acme --username acme_accept \
+  --name "Acme Accept" --public-key-file ~/.ssh/id_ed25519.pub --dry-run
+hostingctl access user add <uuid> --company acme --username acme_accept \
+  --name "Acme Accept" --public-key-file ~/.ssh/id_ed25519.pub --confirm
+hostingctl access users <uuid> --company acme --json
+hostingctl access user remove <uuid> --company acme --access-user <user-uuid> --confirm
+```
+
+Use the native user's `uuid` from the listing. Usernames are 3–32 lowercase letters, digits or underscores,
+starting with a letter. `--key-name` overrides the key label, which defaults to `--name`. Missing, empty,
+oversized and private-key files are refused before any request. Writes require `--confirm`;
+`--dry-run` describes the change without sending it.
+
+## Mailbox declaration import
+
+`hostingctl mailbox import preview <email-domain-uuid> --company <slug> --format <csv|yaml> --file <path>`
+reviews a bounded 64 KiB declaration through the company-authorized API. Replace `preview` with
+`confirm` and add `--confirm` to create missing mailboxes; `--dry-run` sends no request. Confirmation
+re-previews the same captured contents and submits its review token. Matching active mailboxes are
+unchanged; conflicts refuse the batch, and accepted creation is not native readiness.
+
+See the [CSV/YAML examples and versioned schema](../frontend/docs-site/docs/email.md#create-several-hosting-mailboxes).
+Passwords, message copying and DNS changes are not part of this declaration.
+
+## Mailbox setup and recovery
+
+Read one mailbox's mail-client settings, hand them over, manage its fallback recovery address, and issue
+reset links. These are the same `email.view`/`email.manage` operations the panel uses.
+
+```text
+hostingctl mailbox setup <email-domain-uuid> <mailbox-uuid> --company acme
+hostingctl mailbox instructions <email-domain-uuid> <mailbox-uuid> --company acme \
+  --recipient user@example.com --confirm
+hostingctl mailbox fallback set <email-domain-uuid> <mailbox-uuid> --company acme \
+  --address backup@example.com --dry-run
+hostingctl mailbox fallback remove <email-domain-uuid> <mailbox-uuid> --company acme --confirm
+hostingctl mailbox recovery-link email <email-domain-uuid> <mailbox-uuid> --company acme \
+  --destination other@example.com --confirm
+hostingctl mailbox recovery-link copy <email-domain-uuid> <mailbox-uuid> --company acme --confirm
+```
+
+`setup` prints the mailbox address and username, the incoming IMAP and outgoing SMTP host, port and
+security, the authentication requirement and the webmail URL — the deployment's named
+`hosting.email.client_setup` values (`mail.hosting.haak.co` IMAP `993` TLS, SMTP `465` TLS, webmail
+`webmail.hosting.haak.co/webmail`), never guessed from your domain or its MX records. Any part the
+deployment left unconfigured prints `Unavailable`.
+
+`fallback set` stores an address that stays **unconfirmed** until its verification link is completed;
+`fallback remove`, and replacing it, revoke outstanding verification and recovery links. `instructions`
+and `recovery-link email` go to `--recipient`/`--destination`, or the stored fallback when omitted, and
+report the message as **queued**, not delivered. `recovery-link copy` prints the reset URL **once** with
+its expiry and a sharing warning; anyone holding it can reset the mailbox password, and issuing any link
+never changes the password. Every write needs `--confirm`; `--dry-run` describes the change without
+sending it.
+
+A mailbox owner recovering access needs no Hosting account:
+
+```text
+hostingctl mailbox recovery request --address user@example.com --confirm
+hostingctl mailbox recovery verify --token-file ~/token --confirm
+hostingctl mailbox recovery reset --token-file ~/token --password-file ~/password --confirm
+```
+
+These three commands are the only ones that run **without a token or session**; point them at the API
+with `--api-url` or `HOSTINGCTL_API_URL`. The recovery token and the new password are read from a
+`--<name>-file` (a regular file no wider than mode 600) or `--<name>-stdin`, never from an argument, and
+are never printed. `verify` confirms a fallback address; `reset` sets a new confirmed password and
+reports that the change is recorded and applied in the background. A password reset does not change your
+mailbox's separate application passwords or your active sessions.
+
+## Platform domain decisions
+
+System administrators confirm ownership of a name and move it between clients. These commands are
+platform-only: a company-scoped or impersonated token is refused by the API, and the CLI reports that
+refusal rather than working around it. Each acts on a domain claim by its own `uuid`.
+
+```text
+hostingctl platform domain show <claim-uuid> --json
+hostingctl platform domain attest <claim-uuid> --reason "the previous holder confirmed the move" --dry-run
+hostingctl platform domain attest <claim-uuid> --reason "the previous holder confirmed the move" --confirm
+hostingctl platform domain revoke <claim-uuid> --reason "the name was taken back" --confirm
+hostingctl platform domain transfer <claim-uuid> --company beta --reason "client request" --confirm
+```
+
+`show` reports the live ownership decision and the **recorded** routing observation separately, so neither
+reads as the other. A transfer answers `pending` while the previous holder's routing withdrawal is only
+asked for, and `completed` once the move is observed; the command prints which, and re-running `show`
+watches it settle. Every decision needs a `--reason`; the three writes need `--confirm`, and `--dry-run`
+describes the change without sending it. `--company` on `transfer` is the client the name moves to.
+
+## Deployment realm lifecycle
+
+Observe one environment's recorded deployment realm, adopt it, retry a failed convergence and record a
+workload's audience name. This is the operator path for the environment's CustD realm boundary.
+
+```text
+hostingctl realm show <environment-uuid> --company acme
+hostingctl realm adopt <environment-uuid> --custd-company <uuid> --owning-user <uuid> \
+  --registration-policy <invite_only|open> --expected-revision <n> [--login-paused] \
+  [--audiences <path>] --dry-run
+hostingctl realm retry <environment-uuid> --company acme --confirm
+hostingctl realm audience <environment-uuid> <workload-uuid> --company acme --audience acme --confirm
+```
+
+`show` prints what Hosting has recorded for that environment's realm — its state, expected and observed
+revisions, whether logins are paused and whether the routes are held — read from the deployment identity the
+access view already carries, so no new endpoint is added for it. **Recorded convergence is not provider
+health, a working sign-in or a released route:** `ready` means the recorded intent converged, and a route
+that is not held is not thereby proven live. `--json` carries the API's own deployment-identity object.
+
+`adopt` records the environment's realm allocation intent, and is **platform-addressed**: the staff actor who
+may attest a CustD company's authority belongs to no company, so the token needs the platform permission for
+it. The authority is existing tenant identity only — the CustD company (`--custd-company`) and its real
+owning user (`--owning-user`) — and no provider project, environment or directory identifier is ever an
+input. `--registration-policy` is `invite_only` or `open`; `--expected-revision` is the revision the caller
+reviewed; `--login-paused` records paused logins; and `--audiences` names a JSON file of audience
+registrations in the API's own shape
+(`[{"audience":"acme","publicClient":true,"redirectUris":["https://acme.test/callback"]}]`), which the API
+validates rather than this CLI inventing registration settings. An omitted file means no recorded audience,
+and the API refuses a list that does not match the environment's recorded workload audiences.
+
+`retry` asks the API to reconcile the realm from its recorded intent: the accepted answer records the retry,
+and reconciliation observes the result. `audience` records one application workload's realm audience name
+(`--audience`), which the adopted intent then has to match. All three writes need `--confirm`; `--dry-run`
+describes the change and sends nothing.
+
+## Email service reads
+
+Read the company's business-email service and the names, mailboxes and aliases attached to it. These
+are the same `email.view` reads the panel uses; the CLI changes nothing here.
+
+```text
+hostingctl email show --company acme
+hostingctl email names --company acme --json
+hostingctl email mailboxes <email-domain-uuid> --company acme
+hostingctl email mailbox <email-domain-uuid> <mailbox-uuid> --company acme
+hostingctl email aliases <email-domain-uuid> --company acme
+```
+
+`show` reports the service state, its entitlement and whether enrollment is available. `names` reports
+each attached name with the readiness checks the platform observed for it, kept apart from the desired
+status: an attached name is not a name whose mail is proven. `mailboxes` and `aliases` follow every
+page the API reports rather than truncating at the first, and `mailbox` reads one record independently
+of index pagination.
+
+## Mailbox import from CSV or YAML
+
+Create many mailboxes at once on one attached name from a `localPart,quota` CSV or a versioned YAML
+document. Uploading and previewing writes nothing; the confirmed import is `email.manage`, the same
+capability as creating one mailbox by hand.
+
+```text
+hostingctl email mailbox-import preview <email-domain-uuid> --company acme --file mailboxes.csv
+hostingctl email mailbox-import confirm <email-domain-uuid> --company acme --file mailboxes.yaml --dry-run
+hostingctl email mailbox-import confirm <email-domain-uuid> --company acme --file mailboxes.yaml --confirm
+```
+
+The `--file` is a `localPart,quota` CSV (`.csv`) or a versioned YAML document (`.yaml`/`.yml`), with the
+same declarations in either format; the format is read from the file's extension and the file is read
+from disk and never printed. `preview` classifies every declaration against the name and reports what
+it would create, what already matches and what is refused, without writing anything. `confirm`
+re-runs that review to obtain the digest the API requires, then creates the reviewed declarations. It
+needs `--confirm`; `--dry-run` describes the batch without sending it. An import is create-only: a
+repeat of matching declarations is a no-op, a conflicting declaration is a refusal, and a refused
+batch creates nothing. Creating a mailbox does not deliver its password; each new mailbox receives its
+credential through its own owner. Imports never configure source accounts, start a sync or change DNS.
+
+## Portable site pattern
+
+Export one authorized environment's supported setup as YAML, then preview and import it into another
+environment you are authorized for. The pattern is portable setup intent with logical references, not
+a clone: no secret value, source-company identifier, observed readiness, message or file leaves the
+platform.
+
+```text
+hostingctl environment portable export <environment-uuid> --company acme
+hostingctl environment portable export <environment-uuid> --company acme --selection selection.json --out acme.yaml
+hostingctl environment portable preview <environment-uuid> --company acme --file acme.yaml
+hostingctl environment portable preview <environment-uuid> --company acme --file acme.yaml --bindings bindings.json
+hostingctl environment portable prepare <environment-uuid> --company acme --file acme.yaml --bindings bindings.json --dry-run
+hostingctl environment portable prepare <environment-uuid> --company acme --file acme.yaml --bindings bindings.json --confirm
+hostingctl environment portable confirm <environment-uuid> --company acme --file acme.yaml --bindings bindings.json --confirm
+```
+
+`export` prints the pattern as YAML on stdout (pipe it, or use `--out <path>`). `--selection` is a JSON
+file naming the sections (`hosting`, `domains`, `dns`, `email`, `access`, `sources`) and the linked names
+to include; the API's own defaults apply when it is omitted, and any section it did not include is
+reported on stderr so the document on stdout stays byte-identical.
+
+`preview` classifies every declaration against the target and writes nothing; it reports each section
+as create, reuse, conflict, unresolved, refused or unsupported, the declared secret names, the ones
+still unset and any blockers. `--file` is the pattern and `--bindings` is a JSON file whose `bindings`
+map the pattern's logical references to authorized target resources (never a name alone) and whose
+`consents` grant the consequential operations a selected section needs. Neither file carries a secret
+value.
+
+The two files are small and explicit. A selection names what leaves the source:
+
+```json
+{
+  "sections": ["hosting", "domains", "dns", "email", "access", "sources"],
+  "domains": ["shop.example.com"],
+  "emailDomains": ["example.com"],
+  "dns": ["example.com"],
+  "access": true,
+  "sources": true
+}
+```
+
+A bindings file maps the pattern's own references to target identifiers and grants the consequential
+operations. `loginKeys` carries the **public** half of a key a declared SFTP/SSH login needs, and a
+consent left `false` keeps its operation refused:
+
+```json
+{
+  "bindings": {
+    "applications": { "web": "<target-application-uuid>" },
+    "repositories": { "web": "<target-repository-selection-uuid>" },
+    "domains": { "shop.example.com": "<company-domain-uuid>", "example.com": "<company-domain-uuid>" },
+    "emailDomains": { "example.com": "<email-domain-uuid>" },
+    "services": { "cache": "<service-uuid>" },
+    "siteUsers": { "person@example.com": "<site-user-uuid>" },
+    "accessUsers": { "deploy": "<access-user-uuid>" },
+    "members": { "person@example.com": "<company-member-user-uuid>" },
+    "aliasRecipients": ["external@example.com"],
+    "loginKeys": { "deploy": "ssh-ed25519 AAAA... deploy@laptop" }
+  },
+  "consents": { "serviceAddition": false, "emailInvitations": false, "autoDeploy": false }
+}
+```
+
+A binding always names a target that already exists: an existing workload, the repository selection
+a source builds from (`repositories`), a company-owned website name and the customer DNS zone a
+record set lives in (both `domains`), the attached email name (`emailDomains`), an existing access
+login (`accessUsers`), an existing agency site user (`siteUsers`), the Company member a grant names
+(`members`), and any alias destination the pattern does not itself declare (`aliasRecipients`). A
+declaration that **creates** a resource — a new application, mailbox or login — needs no binding, and
+a name that merely matches a target is never authorization.
+
+`prepare` records a reviewed draft without applying resource changes. It may create binding metadata
+and advance the configuration generation; this makes declared secret names writable. Set each unset
+value through the existing write-only secret control, then `preview` and `confirm` again. `confirm`
+re-checks current state, records create/reuse intent and queues normal reconciliation. It does not
+purchase, cut over DNS or remove anything, and its answer is accepted intent rather than a readiness
+claim. `prepare` and `confirm` need `--confirm`; `--dry-run` describes the change without sending it. A
+target that changed since the review is refused by the API rather than applied against state nobody saw.
+
+## Managed DNS and import
+
+Inspect a managed name's zone and its standard zone-file export, and review then apply an import. The
+reads use `dns.view`; `dns import` is `dns.manage`.
+
+```text
+hostingctl dns zone <domain-uuid> --company acme
+hostingctl dns export <domain-uuid> --company acme --json
+hostingctl dns import preview <domain-uuid> --company acme --file records.txt
+hostingctl dns import apply <domain-uuid> --company acme --file records.txt --dry-run
+hostingctl dns import apply <domain-uuid> --company acme --file records.txt --confirm
+```
+
+`zone` reports the published record sets, the desired generation and the last generation observed
+applied; `export` prints a heading and then the zone file the API rendered (its `--json` carries the
+file alone in `zoneText` for piping). The import `--file` holds one record set per
+line as `name TTL type value` — the grammar the panel's import box uses — with blank lines and `#`
+comments skipped and repeated `name/type/TTL` lines folded into one set with several values. The file
+is read from disk and never printed.
+
+`preview` classifies every submitted set and writes nothing. `apply` re-runs that review to obtain the
+generation and review token the API requires, then records the reviewed sets and queues the apply
+pass, so an apply is desired state rather than an observed completion. It needs `--confirm`; `--dry-run`
+describes the change without sending it. A zone that changed since the review is refused by the API
+rather than applied against a state nobody saw. There is no `dnssec` read: DNSSEC is a write-only route
+in the API, and the observed mode is part of `dns zone`.
+
+## Creating an environment
+
+Create an environment from a package the platform sells. The CLI reads the package catalog from the API,
+so it offers exactly the packages the platform offers, and it never names a cluster: placement belongs to
+the platform and the create request carries no cluster field.
+
+```text
+hostingctl environment create --company acme --name "Acme Shop" --dry-run
+hostingctl environment create --company acme --name "Acme Shop" --slug acme-shop --package small_sites --confirm
+```
+
+`--name` is the environment's display name. `--slug` is the name it answers on: omitted, the CLI derives one
+from the name (lowercase, each run of other characters folded to a single hyphen, trimmed, capped at 63
+characters), and a slug shorter than three characters or outside lowercase letters, digits and single
+hyphens that start and end with a letter or digit is refused before any request. `--package` names one of the
+catalog's keys and defaults to its first; a key the catalog does not offer is refused before anything is
+sent.
+
+The write needs `--confirm`; `--dry-run` describes it, reads the catalog so the package it names is the one
+the API sells, and sends nothing. The accepted answer is recorded desired state rather than a ready
+environment: reconciliation applies it afterwards, and `--json` carries the API's own created environment
+object.
+
+## Environment databases
+
+Read an environment's own SQL identities, declare one, replace who may consume it, and retire one while
+keeping its data and its backups. These are the same environment-owned databases the configuration review
+shows; no password is read and no credential is issued here.
+
+```text
+hostingctl environment databases <environment-uuid> --company acme
+hostingctl environment database create <environment-uuid> --company acme \
+  --key shop --engine mariadb --dry-run
+hostingctl environment database bind <environment-uuid> <database-uuid> --company acme \
+  --bind <workload-uuid>[,<workload-uuid>] --confirm
+hostingctl environment database bind <environment-uuid> <database-uuid> --company acme --clear-bindings --confirm
+hostingctl environment database review <environment-uuid> <database-uuid> --company acme
+hostingctl environment database retire <environment-uuid> <database-uuid> --company acme --dry-run
+hostingctl environment database retire <environment-uuid> <database-uuid> --company acme \
+  --digest <review-digest> --generation <review-generation> --confirm
+```
+
+`databases` lists each identity with its engine, its configuration key, the applications allowed to consume
+it and any recorded retirement, and carries the API's `canManage` rather than assuming the account may
+write. `create` declares one independent, environment-owned database: `--key` is the stable declaration key
+and `--engine` is `mariadb`, `postgres` or `mysql`; `--bind` grants it to consuming workloads as it is made,
+and omitting it creates a real zero-consumer database. The API owns the key grammar and refuses a bad one.
+
+`bind` replaces the consumer list. `--bind <uuid>[,<uuid>…]` names the new list and `--clear-bindings`
+detaches every application; one is required and they cannot be combined, so an omitted list never clears a
+grant by accident. Detaching stops future credential delivery only — a password an application already holds
+is not revoked — and the shared service refuses to detach a consumer until that workload is stopped and its
+environment generation has reconciled.
+
+`review` reads what retiring one identity would do, what it retains, and the digest and generation a confirmation
+carries back. It reports the API's own `blockedReason` when it cannot proceed (a consumer is still attached, a
+retirement is already open, the environment is cancelled). Copy the digest and generation from that review to
+`retire`; the CLI sends those exact values, and the API refuses them if the inventory or generation changed.
+Recording the request is **accepted work, not a
+completed retirement**: it reports `pending` (or `failed`, which can be reviewed and requested again) until
+a reconcile has observed the SQL server refusing new logins. New logins then stop working; existing SQL
+sessions are **not** terminated and the applications using the database are neither stopped nor unbound. The
+database, every row, the database name, the SQL user name, the credential version and the backup track are
+retained — there is no delete, and no command here removes a database or its data.
+
+All three writes need `--confirm`. `--dry-run` sends no mutation: `create` and `bind` still read the
+environment's current metadata so a stale change is refused rather than applied, while `retire` sends no
+request at all — it does not even read the review.
+
+## Environment configuration and secrets
+
+Read an environment's desired state, review a YAML document against it, record a draft or apply it, and set
+the declared secret values it needs. These are the same routes the panel uses; no value is ever printed.
+
+```text
+hostingctl environment configuration show <environment-uuid> --company acme
+hostingctl environment configuration preview <environment-uuid> --company acme --file acme.yaml
+hostingctl environment configuration save <environment-uuid> --company acme --file acme.yaml --confirm
+hostingctl environment configuration apply <environment-uuid> --company acme --file acme.yaml --confirm
+hostingctl environment configuration apply <environment-uuid> --company acme --file acme.yaml \
+  --application-uuid <existing-workload-uuid> --confirm
+hostingctl environment secret write <environment-uuid> --company acme \
+  --key app_key --value-source file --value-file ~/app-key --confirm
+hostingctl environment secret write <environment-uuid> --company acme \
+  --key app_key --value-source generate --confirm
+hostingctl environment secret import <environment-uuid> --company acme --file secrets.env --confirm
+hostingctl environment secret local <environment-uuid> --company acme --out .env.local
+```
+
+`show` names the current, active and known-good revisions with each declared secret and whether it holds a
+value. `preview` classifies the document and writes nothing; `--apply` reviews it as an apply so the verdict
+is the one an apply relies on. `save` records a **draft** revision (not applied); `apply` records it and queues
+normal reconciliation. Both re-run the review to obtain the hash and generation the API requires, so a
+document that changed since review is refused rather than applied against state nobody saw.
+For a document with one application, `--application-uuid` explicitly adopts an existing workload in that
+environment. The same UUID is sent in preview and save so the reviewed hash covers the intended adoption.
+
+A secret value is never taken from an argument. `--value-source file|stdin` reads it from a private file
+(mode 600) or `--value-stdin`. `--value-source generate` is only for the declared secret a Laravel
+application binds to its `APP_KEY` environment variable — the fixture's `app_key`, or a member-scoped
+`<memberKey>_app_key` — 32 random bytes, base64-encoded and `base64:` prefixed. The secret's own name never
+decides this: the binding in the reviewed document does, so generation refuses a declared secret that is
+not bound to `APP_KEY`. It also refuses to replace a value already in use unless `--replace` says to rotate
+it, because rotating it invalidates data encrypted with the old key. `import` sets several declared secrets
+from a `KEY=VALUE` file (mode 600) and is how an existing key is brought over unchanged. A value is read only
+when the change is sent, so a dry run reads nothing, and no value appears in output, logs or a dry-run
+description. Every write needs `--confirm`; `--dry-run` describes the change and sends nothing.
+
+`local` is the opposite direction and the one to use for a development machine. It reads nothing from the
+platform's secret store: it writes each declared secret's own **local development value** — the `local` field
+in the document, a harmless default such as `password` — into an env file, and names the declared secrets
+that have none so you supply those yourself rather than discovering a blank variable at runtime. Because a
+stored value never appears in the document, there is no path by which a production credential can reach that
+file. It writes to `--out` (mode 600, since you may add a real value to the same file) or to stdout, and it
+needs no `--confirm` because it changes nothing on the platform.
+
+## Environment services
+
+Read one environment's whole service inventory with the generation it was observed at:
+
+```text
+hostingctl services <environment-uuid> --company acme
+hostingctl services <environment-uuid> --company acme --json
+```
+
+The header names the desired and applied generation and the observed status in words — `nothing observed yet`
+when the environment has never been observed, and `ready` with `applied M of N (change outstanding)` when
+the live generation is behind the desired one. Each service follows with whether it is installed and
+running, its replicas, its reserved allocation when it has one, and its consumers.
+
+## Applications
+
+One application's build, deployment, process runs, rename and removal:
+
+```text
+hostingctl application list <environment-uuid> --company acme
+hostingctl application show <environment-uuid> <workload-uuid> --company acme
+hostingctl application deployment <environment-uuid> <workload-uuid> --company acme
+hostingctl application build <environment-uuid> <workload-uuid> --company acme --source <selection-uuid> --confirm
+hostingctl application deploy <environment-uuid> <workload-uuid> <release-uuid> --company acme --confirm
+hostingctl application runs <environment-uuid> <workload-uuid> --company acme
+hostingctl application run-log <environment-uuid> <workload-uuid> <run-name> --company acme
+hostingctl application schedule-run <environment-uuid> <workload-uuid> <schedule-key> --company acme --confirm
+hostingctl application runtime <environment-uuid> <workload-uuid> --company acme --mode stop --confirm
+hostingctl application update <environment-uuid> <workload-uuid> --company acme --label "Shop" --confirm
+hostingctl application removal <environment-uuid> <workload-uuid> --company acme
+hostingctl application remove <environment-uuid> <workload-uuid> --company acme --confirm
+```
+
+`deployment` reports the running, requested and interrupted builds and releases, the bound source and whether
+a push would deploy. `build` queues a build of the application's applied configuration from `--source` (or the
+bound selection), resolved to an exact commit by the source service rather than named here. `deploy` makes an
+existing release the one the application runs. `runs` and `run-log` read the process run history and one run's
+own output, which may report `unavailable` when the cluster cannot answer rather than an empty body.
+`schedule-run` runs a **declared** schedule once, now, beside the schedule's own runs; it does not execute an
+arbitrary command, for which the API has no route. `update` renames the label only, never the immutable name.
+`runtime` records one application's desired runtime from `--mode stop|start|restart`: it reads the
+environment's current generation and sends `running: false` for stop or `running: true` for start and
+restart. Starting or restarting records a fresh runtime revision even if the application is already running,
+and stopping is recorded as desired intent that reconciliation observes afterwards — the accepted answer is
+not an observed stopped state. `--dry-run` makes no request at all, and a moved generation is the API's own
+conflict rather than a silent refetch.
+
+`removal` reviews what removing one application would affect; `remove` re-reads that review and sends its own
+`inventoryDigest`, so a confirmation approves an exact inventory rather than a label and the environment
+generation makes a stale review a conflict. Removal withdraws the runtime through normal reconciliation and
+deletes no retained data; retiring an environment-owned database's data is a separate decision. Every write
+needs `--confirm`; `--dry-run` describes the change and sends nothing.
+
+## Retained log history
+
+Read the platform's bounded history for one of your resources. This is retained, sanitized operational
+history, not the live container tail:
+
+```text
+hostingctl logs environment <environment-uuid> --company acme
+hostingctl logs dns <domain-uuid> --company acme --json
+hostingctl logs mail <email-domain-uuid> --company acme
+hostingctl logs environment <environment-uuid> --company acme \
+  --start 2026-10-14T11:00:00Z --end 2026-10-14T12:00:00Z --limit 100
+```
+
+`environment`, `dns` and `mail` take the environment, DNS domain and mail domain uuid. The API bounds
+every read: at most a six-hour window within the last 24 hours, defaulting to the most recent hour, and
+1–200 entries, defaulting to 100. `--start` and `--end` are ISO instants and `--limit` is a whole number;
+the server enforces the window and the CLI refuses a malformed `--limit` before asking.
+
+A `source` of `unavailable` means the platform could not read the retained history — no configured
+reader, an active ownership interval that cannot be proven, or a boundary failure for an authorized
+resource. An out-of-company UUID is refused before reading history. Unavailable is not the empty
+result of a successful read that matched nothing; the human output distinguishes these states. The
+environment family reads dedicated web-container output; DNS reports zone-transfer initiation, not full
+query history; and mail reports a Postfix delivery attempt, which is transport acceptance rather than
+proof of mailbox receipt.
+
+## What it never does
+
+No cluster or database access, ever. Those credentials belong to the platform, and a client's laptop is not
+where they live. Any rule the CLI appears to need — what a complete resource profile is, which statuses
+exist, who may see an environment — comes from the API's own answer, because a CLI that re-derives platform
+rules becomes a second owner of them.