Operations
Daily operations
Section titled “Daily operations”# Sync repos and rebuild FTS indexrk sync --owners my-org --local /path/to/repos
# Rebuild full-text search if results seem stalerk reindex
# Check database healthrk statsDatabase backup
Section titled “Database backup”The knowledge database is a local SQLite file (default: data/knowledge.db). Snapshot and restore it with the first-class CLI — rk backup writes a vacuumed copy; do not treat a live-file cp as the primary path.
# Vacuumed snapshot under data/backups/rk backup
# Or write the snapshot to an explicit pathrk backup --out /path/to/knowledge-backup.dbrk backup [--out <path>] uses SQLite VACUUM INTO to write a consistent single-file snapshot under data/backups/ (or --out).
# Schema-validated restore (confirm-gated; `--yes` skips the prompt)rk restore data/backups/<timestamp>.dbrk restore data/backups/<timestamp>.db --yesrk restore <path> [--yes] schema-validates the snapshot, is confirm-gated, swaps the live database atomically (temp-then-rename), and clears WAL sidecars so a stale WAL cannot replay over the restored file. It refuses a backup whose schema_version is newer than this rk build.
Recovery
Section titled “Recovery”If you have a snapshot, restore it with rk restore <path> (see above). If the database becomes corrupt and you have no snapshot, or you need a fresh start:
# Delete the corrupt databaserm data/knowledge.db data/knowledge.db-wal data/knowledge.db-shm
# Re-initialize and seed controlsrk init
# Re-sync from GitHub and local reposrk sync --owners my-org --local /path/to/reposAll data is reconstructable from GitHub metadata and local repo scans. Manually-added notes and relationships will need to be re-entered unless you have a backup.
Migrations
Section titled “Migrations”Schema migrations run automatically when any CLI command or MCP server starts. The current version is tracked in the meta table.
If a migration fails:
- Check the schema version:
sqlite3 data/knowledge.db "SELECT * FROM meta WHERE key = 'schema_version';" - Review migration SQL files in
src/db/ - If unrecoverable, delete the database and re-sync
Troubleshooting
Section titled “Troubleshooting”gh not authenticated
Section titled “gh not authenticated”Error: gh auth status failedRun gh auth login and follow the prompts. The gh CLI must be authenticated for GitHub sync.
better-sqlite3 build fails
Section titled “better-sqlite3 build fails”Error: Could not locate the bindings filebetter-sqlite3 installs via the vendor dual path prebuild-install || node-gyp rebuild --release: use a matching prebuild when one is available, otherwise compile from source. A prebuild miss (unsupported Node ABI, arch, or runtime) is expected to fall through to node-gyp. That is not a claim that prebuilds cover every platform.
This package’s engines.node is >=20. The addon’s own engines list (see the locked better-sqlite3 package) is vendor majors, not a coverage table. Do not treat those majors as a prebuild matrix.
Install C/C++ build tools when the compile path runs:
- Ubuntu:
sudo apt install build-essential - macOS:
xcode-select --install - Windows: Install Visual Studio Build Tools
See the better-sqlite3 troubleshooting guide.
Database locked
Section titled “Database locked”Error: SQLITE_BUSY: database is lockedAnother process has the database open. Close other rk CLI sessions or MCP server instances. If the lock persists, delete the -wal and -shm files and retry.
FTS index out of date
Section titled “FTS index out of date”If search results don’t match expected content:
rk reindex