Static build: fully static versiond-cli + docs

2026-10-18 14:03:59 +00:00
parent 8a507bfc11
commit f37e13af3d
79 changed files with 7309 additions and 0 deletions
@@ -0,0 +1,109 @@
+# CLI guide (versiond-cli)
+
+Full operator manual. See README.md (overview), INSTALL.md (build), PLAN.md (module map), REGISTRY.md (provenance), AGENTS.md (rules), skills/versiond-admin/SKILL.md (agent playbook).
+
+Binary: `build/versiond-cli`. Home: `$VERSIOND_HOME` else `/tmp/versiond`. Config: `config/config.toml`. Index: `data/index.sqlite`. Spool: content-addressed store.
+
+## serve
+
+Start HTTP API on host:port (default 127.0.0.1:9922, loopback only).
+`./build/versiond-cli serve`
+Routes: `/`, `/dashboard`, `/api/health` (`{"ok":true}`), `/api/stats`, `/api/versions`, `/api/blobs`. See README.md.
+
+## add <dir>
+
+Track a root, store it in `roots` table, ingest everything below now.
+`./build/versiond-cli add ~/docs`
+Output: `added <dir>`.
+
+## roots
+
+List tracked roots.
+`./build/versiond-cli roots`
+Output per line: `<path> mode=<mode>`.
+
+## remove <dir>
+
+Untrack a root. History and blobs stay.
+`./build/versiond-cli remove ~/docs`
+Output: `removed <dir>`.
+
+## ingest <path>
+
+Version one file, reason `manual`. Skips missing files and files over `max_file_bytes` (default 10 MiB, see INSTALL.md).
+`./build/versiond-cli ingest ./nota.txt`
+Output: `id=<rowid>`. Exit 1 on skip/fail.
+
+## snapshot <path>
+
+Same as ingest but reason `snapshot`. Use for explicit checkpoints.
+`./build/versiond-cli snapshot ./nota.txt`
+Output: `id=<rowid>`.
+
+## history <path>
+
+List all versions for exact path, ordered by id.
+`./build/versiond-cli history ./nota.txt`
+Output per line: `<id> <digest> <mtime> <reason>`.
+
+## show <digest>
+
+Print raw blob content to stdout.
+`./build/versiond-cli show <sha256>`
+
+## diff <digestA> <digestB>
+
+Unified diff of two blobs. Empty output means identical.
+`./build/versiond-cli diff <a> <b>`
+
+## restore <digest> <dst>
+
+Write blob to file, creating parent dirs.
+`./build/versiond-cli restore <sha256> ./terug.txt`
+Output: `ok` or `err=<msg>`.
+
+## stats / status
+
+Same counters: `versions` and `blobs` rows.
+`./build/versiond-cli stats`
+`./build/versiond-cli status`
+
+## gc
+
+Delete blob rows with no version ref, remove files from spool.
+`./build/versiond-cli gc`
+Output: `gc=N`.
+
+## purge
+
+Delete old versions per `keep_days` (default 5). Current impl deletes rows with mtime < 0.
+`./build/versiond-cli purge`
+Output: `purge=N`.
+
+## sync
+
+Push to remote via `[remote]` config (SFTP stub). See REGISTRY.md.
+`./build/versiond-cli sync`
+Output: `sync=N`.
+
+## token
+
+No token flow in this port. Prints `see config_dir credentials`.
+`./build/versiond-cli token`
+
+## Typical flow
+
+```
+./build/versiond-cli add ~/docs
+./build/versiond-cli ingest ~/docs/plan.txt
+./build/versiond-cli history ~/docs/plan.txt
+./build/versiond-cli show <digest>
+./build/versiond-cli diff <a> <b>
+./build/versiond-cli restore <digest> /tmp/terug.txt
+./build/versiond-cli stats
+./build/versiond-cli gc
+./build/versiond-cli purge
+./build/versiond-cli sync
+```
+
+See also: README.md, INSTALL.md, PLAN.md, REGISTRY.md, AGENTS.md, skills/versiond-admin/SKILL.md.