versioningcpp/CLI.md

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

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

Untrack a root. History and blobs stay. ./build/versiond-cli remove ~/docs Output: removed <dir>.

ingest

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

Same as ingest but reason snapshot. Use for explicit checkpoints. ./build/versiond-cli snapshot ./nota.txt Output: id=<rowid>.

history

List all versions for exact path, ordered by id. ./build/versiond-cli history ./nota.txt Output per line: <id> <digest> <mtime> <reason>.

show

Print raw blob content to stdout. ./build/versiond-cli show <sha256>

diff

Unified diff of two blobs. Empty output means identical. ./build/versiond-cli diff <a> <b>

restore

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.