# bak

Asynchronous Pi session backup and restore through S3-compatible object storage.

## Setup

Create a private bucket and credentials limited to object read/write access for that bucket.

Set:

```text
PI_BAK_S3_ENDPOINT=https://<account>.eu.r2.cloudflarestorage.com
PI_BAK_S3_ACCESS_KEY_ID=...
PI_BAK_S3_SECRET_ACCESS_KEY=...
```

Credentials stay env-only.

## Settings

| Key | Env | Default | Valid values |
| --- | --- | --- | --- |
| `bak.s3.endpoint` | `PI_BAK_S3_ENDPOINT` | none; bak stays disabled | non-empty string |
| `bak.s3.bucket` | `PI_BAK_S3_BUCKET` | `pi-bak` | non-empty string |
| `bak.s3.region` | `PI_BAK_S3_REGION` | `auto` | non-empty string |
| `bak.autoBackup` | `PI_BAK_AUTO_BACKUP` | `true` | boolean; env accepts `true`, `false`, `1`, `0` |

Settings live in `~/.pi/agent/settings.json` or `.pi/settings.json`:

```json
{ "bak": { "s3": { "bucket": "pi-bak", "region": "auto" }, "autoBackup": true } }
```

Precedence: env, trusted project settings, user settings, default.
Project settings apply only when Pi trusts the project; project and user `bak` objects deep-merge per key.
String values are trimmed.
An invalid value, including an empty or whitespace-only env var, shows one warning and uses the default without falling through to lower sources.
Settings resolve at each session start.
`bak.autoBackup: false` stops every automatic upload: after agent runs, on session info changes, and at session shutdown.
`/bak backup` still works, and a running `/bak backup` still gets the normal shutdown drain time.

Initialize each host once:

```text
/bak init <alias>
```

Host identity lives in platform-local state outside Pi configuration.
Catalog autocomplete uses a platform-local stale-while-refresh cache.
Bak performs no filesystem or network work during Pi session startup beyond reading settings; initialization starts lazily on first command or backup-triggering event.

## Commands

```text
/bak
/bak init <alias>
/bak backup
/bak restore <alias>/<session-id-prefix> [path]
/bak restore all [path]
/bak search <name or path>
/bak refresh
/bak status
```

`/bak backup` uploads all locally discoverable sessions.
Completed agent runs back up their current session asynchronously.
Restore defaults to the current configured session directory and never silently overwrites differing files.
Run `/bak search <name or path>` on the receiving host to find remote sessions by case-insensitive name or working-directory substring, then restore using a displayed `<alias>/<id-prefix>`.
Search reads only catalog metadata: it uses the local cache when available, refreshes once if absent, and displays at most 10 newest matches.
Use `/bak refresh` to update an existing cache before searching.

## Tests

`mise run //extensions/bak:test` covers the archive logic against an in-memory store.

`mise run //extensions/bak:e2e` drives the real bucket named by the `PI_BAK_S3_*` environment.
It skips itself when those variables are missing.
Every test host uses a throwaway `e2e-*` alias and deletes its objects and catalog entry afterwards.

## Debug

Opt in through [debug logging](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, and `operation.finish` with operation and outcome classifications.