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:
/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
/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.
Safe events: session.start, session.shutdown, and operation.finish with operation and outcome classifications.
# 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.