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