Koh — 34 commands.

Initialize a new repository. Creates .koh/, a fresh SQLite database, and a default .kohconfig. With --config, opens .kohconfig in $EDITOR (then $VISUAL, then vi) immediately after initialization.

Snapshot the working tree. The save is transactional — manifest written to .tmp.json, database INSERT and HEAD update in a single SQLite transaction, then atomically renamed. A failure at any stage leaves no partial state.

--agent records the AI model that initiated the save. --session groups saves under a named session for filtering and undo. --json suppresses interactive output and emits a single JSON object — designed for agent consumption.

Show save history. Opens in the interactive pager on a TTY; prints unfiltered to stdout when piped. --all interleaves both lanes by timestamp. --session filters to saves with the specified session name. --json outputs all matching saves as a JSON array with no pagination.

--since accepts: yesterday, today, last week, N days ago, last Monday, YYYY-MM-DD, YYYY-MM-DDThh:mm, or a tag name.

Alias for koh log.

Show working-tree changes versus the current HEAD. Lists new files (+), modified files (~), and deleted files (-). --json outputs a JSON object with lane, head_id, dirty, modified, added, and deleted fields — no ANSI codes, no pagination.

Produce a unified diff between two saves. Pipes colorized output through $PAGER on a TTY; prints directly when piped. --json outputs a JSON object with a files array and a diff field.

Without arguments, print the current lane. With main or dev, switch to that lane. Lane switching warns if there are unsaved changes but does not block — switching lanes carries no risk of data loss.

Promote dev HEAD to main. With <id>, promote a specific ancestor of dev HEAD rather than the tip — essential when your dev tip has work-in-progress above stable saves you want to ship. Validates that the target is within dev's ancestry chain and refuses orphaned saves. The output shows the undo hint: koh lane main && koh undo.

Restore a single file from a specific save into the working tree — not the whole snapshot. --dry-run previews exactly what would change without writing anything.

Show a diff of dev HEAD versus main HEAD — everything that has accumulated on dev. Output is piped through the pager.

Rewind the current lane by n saves (default 1). Stores the pre-undo HEAD in the database (_pre_undo_main or _pre_undo_dev) so the operation can be manually reversed. Skipped saves are not deleted — they remain in the object store.

Restore the working tree to any save on the current lane. Validates same-lane membership before any other checks. Requires confirmation.

Throw away all working-tree changes and restore to the current HEAD. Requires confirmation. No history is altered.

Non-destructively extract a save to .koh/peek-<id>/ for inspection. Nothing in the working tree is touched. Requires confirmation. The peek directory is temporary and cleaned up by subsequent operations.

Create a checkpoint save on the current lane. The message is required — checkpoints must be intentional and described. Follows the same atomicity pattern as koh save. Checkpoints appear in koh log with a filled ✦ marker in amber. Unlike koh save, this command does not refuse on a dirty working tree — the entire point is to snapshot exactly where you are, including in-progress changes.

Update the message on a save. The only command that mutates a manifest — specifically, only the message field via atomic re-serialization. Checksum and all other fields are unaffected.

Identify and delete orphaned saves — saves not reachable from either HEAD by following parent pointers. A recursive SQL CTE identifies the full reachable set; anything outside it is eligible for deletion. Requires confirmation.

Rebuild the SQLite database from manifest files. With --verify, validates all manifest checksums and object integrity before rebuilding. Run after any database corruption, accidental deletion, or schema mismatch.

Read-only integrity check. Recomputes the Blake3 checksum of every manifest and every stored object, reports any mismatch, and exits non-zero if anything is invalid. Opens results in the interactive pager.

Attach a named tag to a save (defaults to HEAD). Tags are stored in both the database and the manifest — tag state is fully recoverable from manifests after a complete database loss.

Remove a tag.

Mark a tag as problematic. Flagged tags trigger a warning when used as a target for koh steal, allowing others to cancel before local files are written. The reason is shown in the warning.

List all tags attached to a save (defaults to HEAD).

Bookmark a save for quick reference (defaults to HEAD). Bookmarks appear highlighted in the pager's green filter mode.

Remove a bookmark.

List all bookmarked saves in the interactive pager.

Show projects registered in ~/.config/koh/projects alongside their most recent save. Projects are auto-registered whenever any Koh command runs in a repository. Opens in the interactive pager. With --path, scans a specific directory instead.

Dashboard view of all tracked projects in the interactive pager.

Analyse save history and report behavioural signals. Six signals, all with configurable thresholds in .kohconfig:

Open .kohconfig in $EDITOR (then $VISUAL, then vi). Creates the file with defaults if it doesn't exist. Exits with an error if run outside a Koh repository.

Display the embedded man page in the interactive pager. Section headers are rendered in amber, command names highlighted. Tab and Shift+Tab navigate between section headers (not filter modes). The status bar shows the current section name.

Print the version string.

Print the usage summary.

Initialize a local repository from a remote Keeper snapshot. Stores the remote URL in .koh/keeper. If the target tag is flagged, the flag reason is shown and the user may cancel before any local files are written.

Generate a patch from the current save state. Without --local, uploads to the connected Keeper instance. With --local, writes a .koh.face file to disk.

List patches available from the connected Keeper instance in the interactive pager.

Apply a patch from a Keeper URL or a local .koh.face file.

Archive .koh/ as a deterministic tar+gzip bundle with a computed checksum, written to the current directory.

Merge objects and manifests from a bundle into the current repository. Existing objects are not overwritten. The database is updated to reflect the merged history.