CLI reference

Four binaries expose a command line: knomit (server + admin), knomit-bridge (MCP proxy + Claude integration), knomit-okf (OKF export), and knomit-desktop (the app). All four print the same build string, but the accepted spelling differs: knomit and knomit-bridge take only the bare version subcommand — --version is an unknown flag on both. knomit-okf and knomit-desktop accept version, --version and -version.

knomit — server & admin

knomit serve — start the HTTP server

Boots the app, opens all repos, and listens on {host}:{port} (or a Unix socket). Serves REST /api/v1, the MCP endpoint, the web UI, and — if enabled — git smart-HTTP. Graceful shutdown on SIGTERM.

Flag	Type	Default	Meaning
--port	string	19278 (config)	Listen port
--host	string	localhost (config)	Listen host
--log-file	string	—	File for JSON-structured logs (in addition to stderr)
--log-max-size	int	10	Max log file size (MB) before rotation
--log-max-backups	int	3	Rotated log files to keep
--log-max-age	int	7	Max age (days) for rotated logs

Log level and format (console/json) are set through config, not flags — KNOMIT_LOG_LEVEL / KNOMIT_LOG_FORMAT (or the [log] TOML section). The --log-* flags above override only the rotating file sink.

Set KNOMIT_RUNTIME_ADDR (e.g. localhost:6060) to enable the gated runtime diagnostics port — pprof, Prometheus /metrics, expvar, and live process controls. See Observability.

knomit verify — integrity check

Walks the git object chain, SQLite tables, and search index, reporting structural issues. Exit codes: 0 clean (warnings do not fail the run), 1 integrity errors found, 2 verify itself could not run — bad flags, unknown repo, boot failure. The difference between 1 and 2 is the contract: a script that reads “the tool could not run” as “the repo is damaged” pages someone at 3am over a typo in a flag.

Flag	Type	Default	Meaning
--repo	string	—	Repo to verify. Required unless --all — there is no default repo to fall back to
--all	bool	false	Verify all active repos. An archived repo is not opened and cannot be verified; the run names any it skipped
--deep	bool	false	Parse every fact (slower, stricter)
--json	bool	false	Emit the report(s) as JSON instead of text
--max-issues	int	100	Cap issues printed per repo in text output (0 = all). The per-category summary is always complete, and --json is never truncated — a truncated machine-readable report would look complete and not be. Ordering puts errors ahead of warnings, so truncation can only drop the least severe
--all-branches	bool	false	Parity-check every refs/heads/* ref, not just the branches the index maintains
--prune-generated-refs	bool	false	Writes. Deletes the generated okf/* refs left by the removed server-side export, and their markers — nothing else. Verify is otherwise strictly read-only

Verify blocks every writer for its whole run

It is read-only, but it is also a snapshot: it takes the read lock on every branch it checks up front and holds all of them until it finishes. That is what makes the report internally consistent, and it means the run blocks every writer on those branches for its whole duration. Budget for it, or stop the agent — this is not a cheap probe to fire at a busy one.

Only branches the index maintains are parity-checked. Other refs under refs/heads/* — another machine’s agent branch arriving by fetch, or refs left behind by a removed feature — have no SQLite rows by design. They are named as “not indexed” in the report header rather than reported as thousands of errors; --all-branches opts back in.

knomit migrate-registry — deprecated

Converts a home shape that only exists on installations predating the control.db repo registry. A home created by a current build never needs it, and a converted one never needs it again.

Migrate now if you still have an unconverted home

This command will be removed. Once it is gone, the only supported path off the legacy shape is to re-clone each knowledge base from its remote — and a repo whose remote was never recorded anywhere else cannot be recovered that way.

A legacy home makes the server refuse to boot, and the refusal names this command, which is why it stays listed in knomit --help rather than being hidden. A banner prints before the plan on every run, --dry-run included.

knomit warm-models — pre-download the embedding model

Fetches model + tokenizer files into KNOMIT_HOME/models/<id>/ without booting the server or initializing ONNX. Used at Docker build time.

Flag	Type	Default	Meaning
--model	string	configured embed model	Embedding model id to fetch

knomit version

Prints the full version string (<semver>.<sha>).

knomit-bridge — MCP proxy & Claude integration

Three modes: the default (no subcommand) stdio MCP proxy, the claude subcommands, and version.

Default mode — stdio ↔ HTTP MCP proxy

Reads JSON-RPC from stdin, POSTs to the server’s MCP endpoint, writes responses to stdout. This is what an MCP client launches. In repo mode it discovers the agent branch via GET /api/v1/repos/{repo}, then targets {base-url}/api/v1/repos/{repo}/branches/{branch}/mcp (the branch / is URL-encoded as :). In lens mode it skips branch discovery entirely and targets {base-url}/api/v1/lenses/{lens}/mcp — a lens resolves each mount’s branch server-side. It maintains the Mcp-Session-Id header and handles SSE responses.

Flag / arg	Default	Meaning
--repo	—	Repository name. Exactly one of --repo or --lens is required — knomit has no default repo to fall back to
--lens	—	Lens name; connects to the lens MCP endpoint. Mutually exclusive with --repo — passing both is a fatal error
[base-url] (positional)	http://localhost:19278	Server base URL
--log	/tmp/knomit-bridge.log	Bridge log file (4 MB rotation, 3 backups, 7 days)

The base URL resolves in this order: the positional argument, then the server.json lockfile, then http://localhost:19278. KNOMIT_BASE_URL does not apply here — it is read only by the claude subcommands. Pass the base URL positionally to override discovery. KNOMIT_MCP_DEBUG=1 raises the log level to debug.

Caution

--source and --profile were removed. A .mcp.json that still passes them fails with flag provided but not defined: -source. Delete both arguments. The MCP profile is now a per-repo server setting, not a client flag.

knomit-bridge claude init — scaffold Claude Code integration

Renders embedded templates into the current directory. See Claude Code integration for the full file list.

Flag	Default	Meaning
--repo	cwd basename	knomit repo name
--lens	—	Lens name; writes a lens-scoped .mcp.json. Mutually exclusive with --repo

Whichever name is used is validated against the server’s grammar ([a-z0-9_-]+) before any file is written, so an invalid value is rejected rather than baked into a broken .mcp.json. It is also capped at 27 characters — the mcpServers key is derived from it as knomit-repo-<repo> or knomit-lens-<lens>, and Claude Code builds tool names as mcp__<key>__<tool> against a 64-character API limit. A name that would overflow is rejected here rather than producing an entry whose tools silently cannot be called.

The generated file contains "args": ["--repo", "<name>"], or "args": ["--lens", "<name>"] in lens mode, under that derived key. See the .mcp.json key for why it is no longer the constant knomit, and why a project should carry only one knomit scope.

knomit-bridge claude hook <event> — run an editor hook

Invoked by Claude Code’s hook config; reads stdin, writes guidance to stdout. Valid events: session-start, post-edit, post-ask, pre-compact.

knomit-okf — OKF export

Publishes a knomit knowledge base as a portable Open Knowledge Format repository. Pure Go — no CGO, no native libraries — and built by the top-level make build alongside the others.

knomit-okf clone    [-b <branch>] [--publish-source] [auth] <kb-url> <dir>
knomit-okf sync     [-b <branch>] [--source <url>] [--publish-source] [auth]
knomit-okf branches [--source <url>] [--no-fetch] [auth]
knomit-okf version

sync and branches run inside an export directory; clone creates one. The tool commits but never pushes — you run git push yourself.

Flags come before positional arguments

Go’s flag package stops parsing at the first non-flag argument, so clone <url> <dir> -b main fails with a usage error. Write clone -b main <url> <dir>.

knomit-okf clone — create an export directory

Flag	Type	Default	Meaning
-b	string	source’s advertised HEAD	Source branch to export. A knomit server’s HEAD is usually the agent branch — pass -b main for consensus.
--publish-source	bool	false	Record the KB URL in .knomit-okf.yaml so a stranger who clones the published repo can sync it

knomit-okf sync — re-export and commit

Flag	Type	Default	Meaning
-b	string	the branch in .knomit-okf.yaml	Source branch to export
--source	string	the knomit-source remote	Override the KB URL for this run only — it does not repoint the stored remote
--publish-source	bool	false	Record the KB URL in .knomit-okf.yaml

knomit-okf branches — survey what’s exported

Flag	Type	Default	Meaning
--source	string	the knomit-source remote	Override the KB URL for this run
--no-fetch	bool	false	List from already-fetched refs without contacting the remote; the output says the counts may be stale

Authentication flags

Accepted by all three commands. A knomit server’s git endpoint is unauthenticated and needs none. A flag that does not match the URL’s transport is rejected outright rather than ignored.

Flag	Env fallback	Transport	Meaning
--token	KNOMIT_OKF_TOKEN	HTTPS	Access token, sent as the basic-auth password (never a Bearer header)
--token-file	—	HTTPS	Read the token from a file instead of argv; mutually exclusive with --token
--username	—	HTTPS	Basic-auth username, default git. Bitbucket requires x-token-auth; rejected without a token.
--ssh-key	KNOMIT_OKF_SSH_KEY	SSH	Explicit private key. Failing to load it is a hard error, never a silent fallback.
—	KNOMIT_OKF_SSH_PASSPHRASE	SSH	Passphrase for an encrypted key. No flag exists, because a passphrase on argv is visible via ps.

knomit-okf version

Prints knomit-okf <semver>.<sha>. Accepts version, --version, or -version.

knomit-desktop — tray/desktop app

No arguments boots the app (picks a free loopback port, defaulting to 19278, boots the server in-process, opens the webview, writes server.json). The system tray is created on every platform, Linux included. version is the only argument the binary inspects; anything else is ignored and the app boots normally.

Arg	Meaning
(none)	Boot the app
version / --version / -version	Print version

Logs go to stderr and a rotating file under the platform logs dir (~/Library/Logs/knomit on macOS, $XDG_STATE_HOME/knomit — default ~/.local/state/knomit — on Linux). See Desktop app for how it differs from a bare knomit serve.