Skip to content

Operations

Terminal window
# Sync repos and rebuild FTS index
rk sync --owners my-org --local /path/to/repos
# Rebuild full-text search if results seem stale
rk reindex
# Check database health
rk stats

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.

Terminal window
# Vacuumed snapshot under data/backups/
rk backup
# Or write the snapshot to an explicit path
rk backup --out /path/to/knowledge-backup.db

rk backup [--out <path>] uses SQLite VACUUM INTO to write a consistent single-file snapshot under data/backups/ (or --out).

Terminal window
# Schema-validated restore (confirm-gated; `--yes` skips the prompt)
rk restore data/backups/<timestamp>.db
rk restore data/backups/<timestamp>.db --yes

rk 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.

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:

Terminal window
# Delete the corrupt database
rm data/knowledge.db data/knowledge.db-wal data/knowledge.db-shm
# Re-initialize and seed controls
rk init
# Re-sync from GitHub and local repos
rk sync --owners my-org --local /path/to/repos

All 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.

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:

  1. Check the schema version: sqlite3 data/knowledge.db "SELECT * FROM meta WHERE key = 'schema_version';"
  2. Review migration SQL files in src/db/
  3. If unrecoverable, delete the database and re-sync
Error: gh auth status failed

Run gh auth login and follow the prompts. The gh CLI must be authenticated for GitHub sync.

Error: Could not locate the bindings file

better-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.

Error: SQLITE_BUSY: database is locked

Another 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.

If search results don’t match expected content:

Terminal window
rk reindex