CLI & web app

For the smoothest experience, use the desktop app — it ships for macOS, Windows, and Linux. Anywhere else (an Intel Mac, a server), or when you'd rather stay in the terminal, install the ok CLI from npm and run the same editor as a local web app in your browser.

node --version
git --version

Install

Install the OpenKnowledge CLI globally so you can run ok from anywhere:

npm install -g @inkeep/open-knowledge

Set 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 init

ok 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. ok init also installs the user-global open-knowledge-discovery skill, the same one the desktop's first launch sets up; --skills discovery,write-skill adds the authoring skill, and --no-skills installs none on that run. open-knowledge-write-skill is otherwise one click away in Settings → Skills Studio.

Once you have initialized your project, launch the app in your browser:

ok start

One 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 (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.

Open a doc, folder, or file

ok open takes a doc name, a folder, or a path to a Markdown file.

ok open <path-to-your-file.md>

The output names the absolute project root OpenKnowledge resolved for the argument you gave, so you can tell which project it acted on without running a second command. When the resolved root itself sits inside another project, the output names both, once.

To choose the project yourself, pass --project <dir>. It is honored wherever it appears: --project <dir> or --project=<dir>, before or after the target, and with or without the .md extension on the path. If it cannot be honored, the command exits non-zero with a message saying why instead of quietly resolving somewhere else.

If you don't have a project initialized, this still works. The file opens 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 login

If 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:

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:

ok clean retains a lock and exits 1 if it cannot read it, it records another machine, or it has no recorded owner and its PID is still alive locally. The error names the lock and explains what to check. For an unverified owner, inspect the named local PID and stop it if it is an OpenKnowledge server; do not delete the lock while that process is running.

ok status, ok ps, and the server-lock health check distinguish an unverified owner from a foreign host. ok status --json uses state: "unverified-owner" and includes the PID, with server liveness reported as unknown. ok ps --json uses the same status, displayStatus: "unverified", and null for unrecorded host, port, and start time. The directory is the project root for current .ok/local and legacy .ok locks; it is null when a custom lock location does not establish a project root. Such records are not signal authority for ok stop, including with --force.

Remote Control

Serve this project's web UI and /mcp endpoint to your other devices through any HTTPS tunnel, both on one URL. See the Remote Control overview for the full setup and access-control model. Use Connect remote agents to point agents at the URL.

More commands

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 [path] reverses ok init for one project (the current project when path is omitted): it removes the project's .ok/ directory, OpenKnowledge's editor MCP entries, its own git-exclude lines, and shadow repo, leaving your markdown untouched. Shared editor settings and their symlinks are preserved; ignore rules for shared config files stay while those files still exist.

ok uninstall removes the global footprint — running servers, credentials, the PATH shim, OpenKnowledge's editor MCP entries and bundled skills, app data, and ~/.ok (keeping authored skills in ~/.ok/skills unless you pass --purge-content). Your markdown and other skills in your editors' skill directories stay. An interactive run lets you select projects to deinitialize; --yes removes only the global footprint unless you also pass --all-projects, which covers current, recent, and discovered running projects. The CLI binary stays installed; the command ends by printing how to remove it (npm uninstall -g @inkeep/open-knowledge for the install above).

Both ok deinit and ok uninstall wait for servers to exit before deleting their state. If a server cannot be safely stopped or an integration cannot be cleaned up, the command reports the problem and retains state needed for repair and retry. Applied cleanup exits 1 when anything remains unresolved. With --yes --json, inspect failed[] for those items and their reasons; skipped[] covers intentionally preserved entries. Repair the reported problem and rerun the command.

On Windows, confirming that a running server really is the process the lock names uses OpenKnowledge's bundled native component. Removal refuses rather than signalling a process it has not identified, and the refusal names which of two things went wrong. If the component could not be loaded, reinstalling OpenKnowledge restores it — the same remedy as for its TOML writer. If the component loaded but Windows refused the query, reinstalling will not help: that is usually a permissions difference, so rerun from an account that can inspect the server process. Either way you can instead stop the server yourself and confirm it has exited, then rerun. The failure detail itself is recorded in ~/.ok/logs, not printed.

ok deinit needs the project's .ok/ directory; once that directory is gone, it reports nothing to remove. Remove any retained Pi trust entry manually using its reported exact key and file, as described in installation details.

Malformed filesystem residue does not by itself establish a running server. Cleanup can skip it after process and listener inspection succeeds and finds no associated live candidate. A read failure, incomplete inspection, or associated live server remains a blocker. Global-only uninstall can retain foreign-owned or ownership-unverified project state after the same local inspection; selecting project deinitialization keeps those ownership checks strict. Dead PID-only locks are recoverable. Human output lists root blockers once; JSON failed[] includes both direct failures and blocked dependent operations, with blocked[] providing the dependent subset.

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… lets you choose projects to deinitialize, confirm removal, and answer or skip the optional "why are you leaving?" screen. The progress window stays visible while the original app quits and cleanup runs, so shutdown cannot recreate its settings. The same window then reports the result: successful cleanup guides you through dragging the app to the Trash; incomplete cleanup points to a retained log so you can repair the problem and retry.

To remove the desktop app on the other platforms: on Windows, uninstall OpenKnowledge from Settings → Apps → Installed apps; on Linux, remove the package with your package manager (sudo apt remove openknowledge on Debian/Ubuntu, sudo dnf remove OpenKnowledge on Fedora/RHEL). Run ok uninstall first if you also want the rest of the footprint cleaned up — it works the same on every platform.