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 startOne server on one port serves everything — the editor, the API, the MCP endpoint, and real-time collaboration — and the editor opens in your browser automatically (pass --no-open-browser to skip that). Running ok start again while a server is already up prints the running server's URL and exits.
ok start also takes -p/--port and --bind to pick the address, --idle-shutdown (off or a duration like 30m) to control when an unused server exits, --only server to run without the editor UI, and --mode app to hand off to the desktop app instead of running a server in the terminal (macOS with the desktop app installed).
Idle shutdown is on by default at 30 minutes — a server with no connected clients exits so it doesn't linger. If you keep a session open for a long time without interacting, pass --idle-shutdown off (or a longer duration) to keep it running.
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) |
Remote access
Serve this project's web UI and /mcp endpoint to your other devices through any HTTPS tunnel, both on one URL. Full setup (and the access-control model) in Remote access; point agents at the URL with Connecting agents.
| Command | What it does |
|---|---|
ok start --remote [url] | Start the server admitting requests from the tunnel URL (no server-side auth; restrict reach at the tunnel). Bare --remote uses remote.url from .ok/config.yml |
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 keys the schema no longer reads from your config files (--dry-run to preview; --scope to narrow — defaults to every layer) |
ok skills installed | List every skill installed across your agents (read-only, cross-harness) |
ok skills import <source> | Import a skill as versioned content from skills.sh, a GitHub owner/repo, a git URL, or a local path |
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 your global skills in your editors' skill dirs (~/.agents/skills, ~/.claude/skills, and the like) are never touched. 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.