# CLI & web app (https://openknowledge.ai/docs/reference/cli) Install the ok CLI and run the OpenKnowledge web app in your browser — on any platform, including Intel Macs and servers. For the smoothest experience, use the [desktop app](https://openknowledge.ai/docs/get-started/quickstart) — 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. > **Prerequisites — Verify Node and Git are installed** > > Open a terminal and run: > > ``` > node --version > git --version > ``` > > - **Node.js 24+.** OpenKnowledge requires Node.js 24 or higher. Download from [nodejs.org](https://nodejs.org/en/download/). > - **`git`.** OpenKnowledge uses Git for timeline and recovery. Install it from [git-scm.com](https://git-scm.com/install/). ## Install Install the OpenKnowledge CLI globally so you can run `ok` from anywhere: ```bash 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. ```bash 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 ` 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**. > **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 ()` 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: ```bash 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](https://openknowledge.ai/docs/reference/what-open-knowledge-writes). ## Open a doc, folder, or file `ok open` takes a doc name, a folder, or a path to a Markdown file. ```bash ok open ``` 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 `. It is honored wherever it appears: `--project ` or `--project=`, 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: ```bash ok clone ``` `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 `: ```bash ok clone -b ``` 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: ```bash 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 ` 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](https://openknowledge.ai/docs/features/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. Declines when something is still connected to the target, naming how many clients are attached; pass `--force` to stop it anyway. A server it cannot reach is stopped without the check | | `ok clean` | Remove a stale lock file left behind by a crash (never touches live servers) | ## 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](https://openknowledge.ai/docs/remote-control/overview) for the full setup and access-control model. Use [Connect remote agents](https://openknowledge.ai/docs/remote-control/connecting-agents) to point agents at the URL. | Command | What it does | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ok start --external-url ` | Declare the canonical external origin clients dial (sets `server.externalUrl` for this run) — its host joins the Host/Origin allowlists and issued URLs. External exposure additionally requires consent (`OK_ALLOW_EXTERNAL=1` or `server.allowExternal`). For remote MCP use also set `OK_IDLE_SHUTDOWN=off` — the idle timer only counts editor (WS) connections and would stop the server under a live remote agent. Add `--bind
` to serve a non-loopback listen address. | ## More commands | Command | What it does | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ok seed` | Scaffold a starter pack into the project (`--list-packs` to browse, `--pack ` to choose, `--root ` 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 ` | Clean up a Notion export in place, dry-run unless `--apply` (see [migrating from Notion](https://openknowledge.ai/docs/migrate/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 ` | 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 your file manager 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 ` to run from another directory, `--log-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](https://openknowledge.ai/docs/reference/what-open-knowledge-writes#what-leaves-your-machine). 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. 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.