Koh — 45 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, or YYYY-MM-DDThh:mm.

Alias for koh log.

Filtered view of koh log showing only non-checkpoint saves (is_checkpoint = 0). Accepts the same flags as koh log.

Filtered view of koh log showing only checkpoint saves (is_checkpoint = 1). Useful for reviewing declared safety points or finding a checkpoint ID before koh load --checkpoint. Accepts the same flags as 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 versus the current HEAD, a specific save, or two explicit 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.

Apply one save's delta to the current HEAD as a new save. Koh performs a three-way merge against the source save's parent; clean applies modify, add, or remove exactly that delta, while conflicts abort. --dry-run previews without touching the working tree.

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. When the undo would cross a checkpoint, shows which checkpoints would be undone before confirming. --yes skips the prompt.

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. Warns on a vague message (containing words like "checkpoint", "wip", "before", or "save") or an immediate-repeat checkpoint; --yes bypasses both warnings.

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. When the database already holds saves, confirms before wiping and rebuilding — --yes skips that prompt for scripted use. With --verify, validates all manifest checksums and object integrity before rebuilding. Reports a "N saves · M checkpoints · K flags" summary after rebuild and suggests koh verify for a deeper integrity check. 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.

Permanently remove a file or directory from save history. Pass a file path or directory prefix and Koh rewrites every affected manifest to exclude it, then prunes any objects no longer referenced by any remaining manifest. Without --save, rewrites the entire history; with --save <id>, rewrites only that one save (prefix match accepted).

Before executing, Koh shows a summary of which saves are affected and which paths will be removed, then asks for confirmation. --yes skips the prompt for scripted use. Save IDs and parent chains are preserved — only the file list and content checksum change, so koh verify passes cleanly after stripping.

Mark a save as unsafe. Save-level flag metadata is written into the manifest and database. The reason is optional, but when present it is shown anywhere the save is surfaced.

Clear a save-level flag.

List all flagged saves in the current repository.

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

Dashboard view of Koh projects. By default it reads ~/.config/koh/projects, where repositories are auto-registered when commands run. With --path, scans a specific directory instead.

Check for or install the latest Koh release. --check reports availability without downloading.

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.

Delete a single face from the connected Kepr instance. Requires confirmation. The face is removed from Kepr — local saves and manifests are unaffected.

Show all configured remotes with live status — whether each remote is current, how many saves behind it is, and how many offers are pending.

Add a remote. Probes the instance for reachability. On public instances, offers to claim a handle via the existing SSH flow. Prompts for visibility if the flag is omitted.

Change which remote koh offer targets when no name is given.

Offer the current save to the default remote. If the default remote is private, offers silently with no confirmation. A live progress line shows the save currently uploading, so a slow or stalled transfer is visible rather than a frozen counter. When the target repo does not exist on the remote, Koh automatically runs the setup wizard to create it — no extra flags needed.

Initialize a local repository from a remote Kepr snapshot. Writes the source remote to .koh/remotes as origin. Prompts to add a private remote for backup. If the target save is flagged, shows the reason before any local files are written. --into <dir> clones into the given directory (created if absent) instead of the current directory — guards against cloning into an existing repo before any network call. On an unknown repo name, suggests close matches from the remote's public index. --key <path> specifies an SSH key for authenticated remotes.

Show offer status across all configured remotes, grouped per remote. Merges local .koh/offer_log receipts with live status from each Kepr instance. Status indicators: ✦ accepted, ◉ pending, ◯ queued (remote unreachable), ✗ rejected with reason.

Apply a save from a Kepr instance by ID, or restore from a local .face file.

Delete a face or entire repository from the connected Kepr instance. See §10 Meta for full description.

List open issues on the connected Kepr repo. --closed shows only closed issues. --all shows open and closed together. --repo targets a specific Kepr repo URL without requiring a local project.

Show full detail on issue #n in the interactive pager. Includes the description, any maintainer notes, and the resolution face if the issue was closed with one.

File an issue against the connected Kepr repo. With no arguments, runs interactively — prompts for title, description, and optional contact email. With <title>, prompts for description only. With both, sends immediately. --repo targets a specific repo URL from any directory.

Archive .koh/ as a deterministic tar+gzip .bundle with a Blake3 content 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.