# 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.