---
title: CLI & web app
icon: LuTerminal
description: Install the ok CLI and run the OpenKnowledge web app in your browser — on Linux or an Intel Mac.
---
On macOS, use the [desktop app](/docs/get-started/quickstart) for the smoothest experience. On **Linux** or an **Intel Mac**, install the `ok` CLI from npm and run the **same editor as a local web app** in your browser.

<Callout type="info" title="Prerequisites">
  - **Node.js 24+.** OpenKnowledge requires [Node.js](https://nodejs.org) 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, install it from [git-scm.com](https://git-scm.com) or your package manager.
</Callout>


## Install

Install the OpenKnowledge CLI globally to put `ok` on your `PATH`:

```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, Cursor, Codex, OpenCode). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.

```bash
cd my-project
ok init
```

<Callout type="info" title="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`.
</Callout>

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

```bash
ok start --open
```

## Editing a single file

If you don't have a project initialized, you can still open a file directly in the editor.

```bash
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:

```bash
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 opens the editor.

Pin a branch with `-b <branch>`:

```bash
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:

```bash
ok auth login
```

If you're already logged in with the `gh` CLI, you can skip this step.

## 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, a path, pid or `all` to stop all servers). |
| `ok clean` | Remove stale lock files left behind by a crash (never touches live servers) |

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