Track HiveGrid Cloud planning reference

hivegrid-cloud/packages/cli/README.md

@@ -0,0 +1,41 @@
+# @toolctrl/cli
+
+Operator CLI for the ToolCTRL boilerplate. Currently ships the `backup` family
+of subcommands. The entrypoint is `bin/toolctrl-cli.mjs`, wired up via
+[citty](https://github.com/unjs/citty) for consistent subcommand handling.
+
+## Subcommands
+
+| Command           | Description                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `backup:create`   | Dump Postgres + (optional) Storage + (optional) ClickHouse, encrypt, upload to S3. |
+| `backup:list`     | List S3-stored backups with manifest metadata.                         |
+| `backup:restore`  | Download, decrypt, extract; restore Postgres + Storage from a backup.  |
+| `backup:verify`   | Test-restore Postgres dump into a `verify_<uuid>` schema, sanity-check. |
+| `backup:rotate`   | Apply daily/weekly/monthly retention policy against the backup bucket. |
+
+See [`docs/operations/backup.md`](../../docs/operations/backup.md) for the
+operator runbook (setup, key management, restore drill, troubleshooting).
+
+## Environment variables
+
+The CLI uses a backup-scoped S3 credential set so the backup bucket can be
+isolated from the application bucket:
+
+- `BACKUP_S3_ENDPOINT`, `BACKUP_S3_REGION`, `BACKUP_S3_BUCKET`
+- `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY`
+- `BACKUP_S3_FORCE_PATH_STYLE`
+- `BACKUP_ENCRYPTION` (`age` | `gpg` | `none`, default `age`)
+- `BACKUP_AGE_PUBLIC_KEY` (required when encryption is `age`)
+- `BACKUP_AGE_IDENTITY_FILE` (required for `restore` / `verify` with age)
+- `BACKUP_RETENTION_DAILY` (default `7`)
+- `BACKUP_RETENTION_WEEKLY` (default `4`)
+- `BACKUP_RETENTION_MONTHLY` (default `12`)
+- `BACKUP_INCLUDE_CLICKHOUSE` (`true` to include ClickHouse snapshots)
+
+## Development
+
+```sh
+pnpm --filter @toolctrl/cli test
+pnpm --filter @toolctrl/cli typecheck
+```