CLI & web app
Install the ok CLI and run the OpenKnowledge web app in your browser — on Linux, Windows, or an Intel Mac.
On macOS, use the desktop app for the smoothest experience. On Linux, Windows, or an Intel Mac, install the ok CLI from npm and run the same editor as a local web app in your browser.
Prerequisites
- Node.js 24+. OpenKnowledge requires Node.js 24 or higher.
git. OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). On macOS it comes with the Xcode Command Line Tools (xcode-select --install); on Linux or Windows, install it from git-scm.com or your package manager.
Install
Install the OpenKnowledge CLI globally so you can run ok from anywhere:
npm install -g @inkeep/open-knowledgeSet up a project
Run ok init in any folder to turn it into an OpenKnowledge project. It scaffolds a .ok/ directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw, Pi, Antigravity, LM Studio, Hermes). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.
cd my-project
ok initok init asks two questions: where to register the MCP server (user-level, project-level, or both) and whether to share the OpenKnowledge config files with your team (committed alongside your content) or keep them local to this machine.
In a sub-folder of a git repo, ok init sets the project up at the git root — one .ok/ per repo — and the whole repo becomes the content scope. Pass --content-dir <dir> to limit content to one folder (ok init --content-dir . scopes it to the folder you run in); the choice is saved as content.dir in .ok/config.yml. For scripts, --json prints a structured JSON summary.
If an editor shows “left unchanged”
When an editor's config can't be parsed safely — it's not valid JSON/TOML, has two MCP server blocks, or is unusually large — OpenKnowledge leaves the file byte-for-byte untouched and prints left unchanged (<reason>) instead of registering. It never rewrites or resets a config it can't fully understand. Fix the underlying config (the editor itself usually reports the parse error) and re-run ok init.
Once you have initialized your project, launch the app in your browser:
ok start --openok start also takes -p/--port and -H/--host to pick the address, and --mode app to hand off to the desktop app instead of running a server in the terminal (macOS with the desktop app installed; can't be combined with --open).
For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see What OpenKnowledge writes to your system.
Editing a single file
If you don't have a project initialized, you can still open a file directly in the editor.
ok open <path-to-your-file.md>This opens your file directly in the WYSIWYG/source editor without any of the version history or open with AI frills.
Clone from GitHub
You can pull repositories directly from GitHub and open them with OpenKnowledge:
ok clone <owner/repo>ok clone accepts a full https://github.com/... URL or the owner/repo shorthand. It clones the repository, initializes OpenKnowledge if it isn't already, and starts the local server — open the printed Editor URL in your browser.
Pin a branch with -b <branch>:
ok clone <owner/repo> -b <branch>If the branch no longer exists, ok clone falls back to the repository's default branch.
A public repo clones without authentication. For a private repo, sign in first:
ok auth loginIf you're already logged in with the gh CLI, you can skip this step.
ok auth also provides status (show who's logged in), repos (list repositories you can access), signout (remove stored credentials), and pat (store a Personal Access Token). Every subcommand takes --host <hostname> for GitHub Enterprise.
Sync with GitHub
Sync a project with its remote from the terminal:
| Command | What it does |
|---|---|
ok sync | Commit, pull, and push to the remote |
ok pull | Pull changes from the remote |
ok push | Push commits to the remote |
Each command goes through the running server when one is up and falls back to plain git otherwise; pass --json for JSONL progress events when scripting. See GitHub sync for how syncing works.
Manage local servers
Each project runs its own local server. These commands let you see and stop them:
| Command | What it does |
|---|---|
ok status | Show whether a server and UI are running for the current project |
ok ps | List every running OpenKnowledge server on your machine |
ok stop | Stop the server for the current directory — or pass a port, path, or PID to stop a specific server, or all to stop every server |
ok clean | Remove stale lock files left behind by a crash (never touches live servers) |
More commands
| Command | What it does |
|---|---|
ok seed | Scaffold a starter pack into the project (--list-packs to browse, --pack <id> to choose, --root <dir> to nest in a subfolder, --dry-run to preview) |
ok preview | Show what content the watcher will track (read-only) — the quick check after a content.dir or .okignore change |
ok migrate notion <dir> | Clean up a Notion export in place, dry-run unless --apply (see migrating from Notion) |
ok config validate | Validate the merged config (defaults → user → project) |
ok config migrate | Remove deprecated keys from config.yml (--dry-run to preview; --scope project, user, or both) |
ok skills manage | Control whether OpenKnowledge adopts your editor skills into this project (--on, --off, --status; default off) |
ok bug-report | Package a support bundle — recent app logs, the project's server logs and lock diagnostics, and system info — as an auto-redacted zip under ~/.ok/bug-reports/, revealed in Finder when it's done (--no-reveal to skip). Collects the same standard set as the desktop app's Help → Report a bug…; ok diagnose bundle produces the full superset (telemetry spans, live server state) into the project's .ok/local/diagnostics/ |
Global flags
Every command takes --cwd <path> to run from another directory, --log-level <level> (silent, error, warn, info, debug, or trace), and --no-color to disable color output. ok start runs quiet by default; --log-level debug turns everything on.
Commands that run for you
The rest of the CLI exists mostly for tooling and automation. Your AI editor spawns ok mcp to talk to the knowledge base; ok repair-skills refreshes bundled editor skills automatically during ok start; and ok diagnose / ok bug-report produce support bundles when something goes wrong. Run ok --help if you want to see an overview of all commands.
Remove OpenKnowledge
ok deinit reverses ok init for one project: it removes the project's .ok/ directory, its editor MCP entries, git-exclude lines, and shadow repo, leaving your markdown untouched.
ok uninstall removes OpenKnowledge from the whole machine — running servers, credentials, the PATH shim, its own editor MCP entries, skill bundles, app data, and ~/.ok. Your markdown content stays, and skills you authored under ~/.ok/skills are kept unless you pass --purge-content. It never deletes the CLI binary itself; it ends by printing the removal command (npm uninstall -g @inkeep/open-knowledge for the install above).
Both commands print their plan and ask before acting; --dry-run previews without changing anything. Once ok uninstall has finished successfully, an interactive run also asks one optional question about why you're leaving — you can skip it, and --yes, --json, and non-interactive runs never ask. Anything you do answer is sent to us.
On the macOS desktop app, App menu → Uninstall OpenKnowledge… covers both steps from one flow: it optionally deinitializes your projects, removes the global footprint, shows the same optional "why are you leaving?" screen once removal succeeds, and then guides you through dragging the app to the Trash.