@semiont/cli 0.2.46 → 0.3.1

package/README.md

@@ -309,7 +309,12 @@ For detailed instructions on adding new commands, see the [Adding Commands Guide
 - `backup` - Create service backups
 - `restore` - Restore from backups
 
-**Development & Deployment**  
+**Knowledge Base Backup/Restore**
+- `backup` - Create a lossless backup of the knowledge base
+- `restore` - Restore a knowledge base from a backup archive
+- `verify` - Verify a backup archive's integrity without restoring
+
+**Development & Deployment**
 - `publish` - Build and publish artifacts (creates new versions, does not deploy)
 - `update` - Deploy new versions to running services (deploys what publish created)
 - `test` - Run test suites
@@ -346,6 +351,53 @@ semiont update --service frontend --environment production
 
 For services using immutable tags (e.g., git hashes), `update` will only deploy if a newer version exists. For mutable tags (e.g., `:latest`), `update` can force a redeployment even without version changes.
 
+### Knowledge Base Backup, Restore, and Verify
+
+The `backup`, `restore`, and `verify` commands provide lossless whole-KB backup and restore:
+
+- Streams a tar.gz archive containing `.semiont/manifest.jsonl`, per-resource event streams (`.semiont/events/*.jsonl`), and content blobs at the archive root (`{checksum}.{ext}`)
+- Preserves full event history, hash chains, and all metadata
+- On restore, events replay through the EventBus and Stower actor so materialized views and graph rebuild naturally
+
+#### Backup
+
+```bash
+semiont backup --environment production --out backup.tar.gz
+```
+
+Options:
+- `--out <path>`, `-o <path>` — Output file path (required)
+
+#### Restore
+
+```bash
+semiont restore --environment production --file backup.tar.gz
+```
+
+Options:
+- `--file <path>`, `-f <path>` — Input file path (required)
+
+Restore bootstraps a full EventBus + Stower pipeline so events flow through the normal actor system. Materialized views and graph rebuild naturally from the replayed events.
+
+#### Verify
+
+```bash
+# Verify a backup archive without importing
+semiont verify --file backup.tar.gz
+```
+
+Options:
+- `--file <path>`, `-f <path>` — Backup file to verify (required)
+
+Verify checks:
+- Manifest format and version
+- Hash chain integrity per event stream
+- First/last checksum match against stream summaries
+- Event count match per stream
+- Content blob count match
+
+Does not require an environment — reads the archive standalone.
+
 ## MCP (Model Context Protocol) Server
 
 The Semiont CLI includes built-in support for MCP, allowing AI assistants to interact with Semiont APIs.