HiveGrid-Wireframes/hivegrid-cloud/packages/cli/README.md

@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 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

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 @toolctrl/cli test
pnpm --filter @toolctrl/cli typecheck