HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/cli/README.md

@hivegrid/cli

Operator CLI for HiveGrid. Currently ships the backup family of subcommands. The entrypoint is bin/hivegrid-cli.mjs, wired up via 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 for the operator runbook (setup, key management, restore drill, troubleshooting).

Environment variables

Database-backed operator commands use the restricted hivegrid_app connection and require HIVEGRID_CLI_OPERATOR_USER_ID to contain the ID of an existing AdminUser. The CLI validates that identity and binds it as app.user_id; commands with --tenant, --tenantId, or --tenant-id additionally bind that single tenant as app.tenant_id. Do not use the migrator DSN as a CLI bypass. Scaffolding, plugin-authoring and backup commands do not require this variable.

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

pnpm --filter @hivegrid/cli test
pnpm --filter @hivegrid/cli typecheck