Quickstart¶
This walkthrough exercises every core command against a scratch vault.
Point DOCBANK_HOME at a temporary directory so you can experiment
freely:
Import some documents¶
add copies files into the vault. Sources are never modified or deleted.
Directories import recursively: the directory's own name becomes a
folder under --dest, and the relative structure underneath is
preserved. Without --dest, files land in /inbox.
The daemon¶
That add just auto-started the docbank daemon in the background —
every data command does, if one isn't already running. You don't need
to think about it day to day; docbank daemon status shows it if you're
curious, and docbank daemon stop shuts it down (it also exits on its
own after a period of inactivity). See Daemon.
Re-running the same import is safe — already-imported files (matched by content, not name) are skipped:
Browse the tree¶
ID KIND SIZE MODIFIED NAME
14 dir 0 2026-07-06T21:14:03.2211Z 2024
102 dir 0 2026-07-06T21:14:05.9871Z 2025
231 file 48211 2026-07-06T21:14:08.1298Z checklist.pdf
tree prints the whole hierarchy with node IDs:
cat streams a file's bytes to stdout:
New version-command vocabulary
docbank version and the explicit docbank versions list|show|cat
commands are newer than v0.7.0. Build from source to use them until the
next release is published.
Every imported file also has a stable immutable content-version UUID:
docbank versions list /taxes/checklist.pdf
docbank versions show <version-id> --json
docbank versions cat <version-id> > /tmp/checklist-version.pdf
The version ID survives node renames and moves. Replace the current content without changing the stable file node:
docbank put ~/Documents/revised-checklist.pdf /taxes/checklist.pdf
docbank versions list /taxes/checklist.pdf
put hashes the source before contacting the daemon, then inspects the target
and uploads it, showing separate progress for both file passes. The upload
requires that freshly observed target revision, so a concurrent change fails
instead of being overwritten. The prior version remains available through
docbank versions cat <old-version-id>. Adopt it as current without
erasing the replacement:
Reversion creates another immutable head that records its source. It does not copy the source blob or rewind history, so both the replacement and the original remain addressable.
For text and other editor-friendly files, edit verifies a private copy, opens
the blocking command from VISUAL or EDITOR, and creates a replacement only
when the result changed. GUI editors need their wait flag, for example
VISUAL='code --wait'.
Organize independently with tags¶
Tags survive path changes because assignments use stable tag and node IDs:
The human CLI accepts the current tag name or UUID. Canonical UUID-shaped input
is always treated as an ID, so stable authority cannot later be captured by a
display name. docbank tag list shows revisions and assignment counts; tag
rename changes only the display name, and tag delete removes assignments
without deleting any document.
Reorganize¶
Moves and renames are metadata-only; the stored bytes never move.
# Rename in place (destination doesn't exist; its parent does)
docbank mv /taxes/checklist.pdf /taxes/filing-checklist.pdf
# Move into an existing directory, keeping the name
docbank mv /taxes/filing-checklist.pdf /taxes/2025
Search¶
Names are indexed with SQLite FTS5; every term is a prefix match:
Trash and recovery¶
rm is soft deletion — the node (and its subtree, for directories) moves
to the trash and its name becomes reusable:
docbank trash list # what's recoverable
docbank restore 15 # put it back where it was
docbank trash empty --older-than 30d # dry run: report old trash
docbank trash empty --older-than 30d --run # permanently delete old trash
Reclaim and verify¶
Emptying the trash deletes tree entries, but the underlying bytes remain
until you garbage-collect. gc is a dry run by default; it removes loose files
directly and marks unreachable packed payload as pending repack:
3 candidate blob(s), 0 untracked file(s), 1204882 loose byte(s) reclaimable
dry run — pass --run to delete
docbank gc --run
docbank storage status # shows dead packed payload, if any
docbank storage repack # compacts eligible sparse packs
docbank verify # re-hash every stored blob
Prove recovery¶
Backup repositories are separate from the live vault. Captures are incremental: unchanged content is reused across snapshots. This scratch loop creates a repository, captures the vault, verifies the repository, and restores the latest snapshot into a different vault:
export DOCBANK_BACKUP=$(mktemp -d)
export DOCBANK_RESTORE=$(mktemp -d)
docbank backup init --repo "$DOCBANK_BACKUP"
docbank backup create --repo "$DOCBANK_BACKUP"
docbank backup list --repo "$DOCBANK_BACKUP"
docbank backup verify --repo "$DOCBANK_BACKUP"
docbank backup restore --repo "$DOCBANK_BACKUP" --target "$DOCBANK_RESTORE"
DOCBANK_HOME="$DOCBANK_RESTORE" docbank tree /
DOCBANK_HOME="$DOCBANK_RESTORE" docbank verify
The restored target is independently usable; the running source vault is not replaced. See Backup & Restore for progress modes, snapshot selection, overwrite rules, and the exact proof returned by restore.
That is the core document workflow. Continue with Vault Lifecycle for maintenance and upgrades, explore Docbank for Agents for automation, or use the CLI Reference for exact command semantics.