# CLI reference

> All `ok` subcommands, global flags (`--cwd`, `--log-level`), server management (`start`, `stop`, `ps`, `status`, `clean`), and single-file dispatch behavior.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `packages/cli/src/cli.ts`
- `packages/cli/src/commands/start.ts`
- `packages/cli/src/commands/stop.ts`
- `packages/cli/src/commands/status.ts`
- `packages/cli/src/commands/ps.ts`
- `packages/cli/src/commands/config.ts`
- `docs/content/reference/cli.mdx`

---

---
title: "CLI reference"
description: "All `ok` subcommands, global flags (`--cwd`, `--log-level`), server management (`start`, `stop`, `ps`, `status`, `clean`), and single-file dispatch behavior."
---

The `@inkeep/open-knowledge` npm package installs two equivalent binaries — `ok` and `open-knowledge` — both backed by `packages/cli/src/cli.ts`. Every invocation runs through a Commander program with global flags, optional project-root anchoring, and a pre-parse single-file dispatch path that intercepts bare markdown paths before subcommand routing.

## Global flags

These flags apply before any subcommand runs.

<ParamField body="--cwd" type="string">
  Sets the working directory via `process.chdir()` before config load and command execution.
</ParamField>

<ParamField body="--log-level" type="string" default="info">
  Sets `LOG_LEVEL` and `OK_CONSOLE_LEVEL`. Accepted values: `silent`, `error`, `warn`, `info`, `debug`, `trace`.
</ParamField>

<ParamField body="--no-color" type="boolean">
  Disables color output by setting `NO_COLOR=1`.
</ParamField>

<ParamField body="--color" type="boolean">
  Forces color output by setting `FORCE_COLOR=1`.
</ParamField>

<ParamField body="--version / -V" type="boolean">
  Prints the version notice and exits.
</ParamField>

<ParamField body="--help / -h" type="boolean">
  Prints help and exits. Also suppresses single-file dispatch (see below).
</ParamField>

### Project anchoring

For subcommands `start`, `stop`, `status`, `clean`, `ui`, `mcp`, and `preview`, the CLI walks up from the current directory to find an enclosing Open Knowledge project root (a directory containing `.ok/`). When the invocation cwd is inside a project but not at its root, the CLI `chdir`s to the project root and prints:

```
[ok] Using Open Knowledge project at <root>
```

The original invocation cwd is preserved for path-relative operations such as `ok stop <directory>`.

## Default dispatch (`ok` with no subcommand)

When argv contains no recognized subcommand and single-file dispatch does not match, the default action is:

1. **Desktop available** (macOS with `Open Knowledge.app` installed): launch the desktop app.
2. **Otherwise**: run `ok start` for the current directory.

```bash
ok                  # desktop app or `ok start`
ok --cwd ~/my-wiki  # same, but from ~/my-wiki
```

`ok start --mode app` forces desktop launch without booting a server. `ok start --mode browser` forces the browser/server path even when the desktop app is installed.

## Single-file dispatch

Before Commander parses argv, the CLI scans tokens for a markdown file target. This runs only when `--help`, `-h`, `--version`, or `-V` are absent.

### Detection rules

A token is treated as a file target when either:

- It has a `.md` or `.mdx` extension, or
- It resolves to an existing path on disk (relative to `--cwd` or the current directory).

The first matching operand wins. Known subcommand names are excluded unless the `open` escape hatch applies.

| Invocation | Behavior |
| --- | --- |
| `ok notes.md` | Open `notes.md` |
| `ok ./specs/foo/SPEC.md` | Open that file |
| `ok open ./start.md` | Open `start.md` when `start` would otherwise match the subcommand |
| `ok start` | Runs the `start` subcommand (not single-file dispatch) |

### Open modes

`prepareSingleFileOpen()` classifies the target into two modes:

**Project mode** — the file sits inside an existing Open Knowledge project's content directory. The CLI delegates to `ok open <docName>` with the resolved project root. Opens via desktop deep link (`openknowledge://open?project=…&doc=…`) when the desktop app is installed; otherwise opens the running UI in the browser.

**Ephemeral mode** — the file is outside any project. The CLI:

1. Creates a throwaway temp project under `ok-ephemeral-*` in the system temp directory.
2. Boots a single-file server with `--single-file` (git and MCP disabled).
3. Opens the browser at `http://<host>:<port>/#/<docName>`.
4. Holds the session until Ctrl-C, then tears down the server and temp directory.

Ephemeral sessions lack version history, MCP tools, and "Open with AI" integrations.

<Warning>
  Ephemeral mode requires UI assets bundled with the npm package. If assets are missing, reinstall `@inkeep/open-knowledge` or build the app in a monorepo checkout.
</Warning>

## Server management

Each Open Knowledge project runs its own collaboration server and optional UI sibling. Lock files under `.ok/` track process state.

```mermaid
stateDiagram-v2
  [*] --> missing: no lock file
  missing --> alive: ok start
  alive --> dead-pid: process exits
  dead-pid --> missing: ok clean
  alive --> missing: ok stop
  corrupt --> missing: ok clean
  alive --> foreign-host: lock from another host
```

### `ok start`

Start the Hocuspocus/Yjs collaboration server for the current project. Requires `.ok/` unless `--single-file` is used (internal/desktop path).

| Flag | Description |
| --- | --- |
| `-p, --port <port>` | Collaboration server port |
| `--ui-port <port>` | Pin the UI sibling port; if a server already runs, connect to it instead of exiting |
| `-H, --host <host>` | Server bind host (default from `HOST` env or package default) |
| `--open` | Open the editor URL in the default browser after start |
| `--mode <browser\|app>` | Force browser server boot or desktop app launch |
| `--serve-content-assets` | Serve content assets from this server |
| `--react-shell-dist-dir <path>` | Serve React shell from path (suppresses UI sibling spawn) |
| `--single-file <path>` | Ephemeral single-file mode (git + MCP off) |
| `--project-dir <dir>` | Throwaway project root for `--single-file` |

On start, the CLI automatically runs repair sweeps for MCP configs, `launch.json`, and bundled editor skills (unless ephemeral). A UI sibling (`ok ui`) is auto-spawned when no live UI lock exists. Idle shutdown releases the server lock after 30 minutes with no UI activity.

Lock collision errors distinguish desktop (`interactive`), MCP-spawned (`mcp-spawned`), and generic server locks. Git availability errors exit with code `78`.

### `ok stop`

Stop server and UI processes for a target.

| Target | Behavior |
| --- | --- |
| *(no argument)* | Stop processes for the current project; if none found, fall back to `ok ps` output |
| `<port>` | Stop the project whose server or UI lock matches the port |
| `<pid>` | Stop the project whose server or UI lock matches the PID |
| `<directory>` | Stop processes for the project at that path (spaces allowed) |
| `all` | Stop every running server across all discovered lock directories |

Sends `SIGTERM` to alive or foreign-host processes. Exit code `1` if any kill fails.

### `ok status`

Show live state of server and UI lock files for the current project.

```
server  alive  pid=12345 port=3921 started=2026-06-25T10:00:00.000Z
ui      alive  pid=12346 port=3922 started=2026-06-25T10:00:01.000Z
```

| State | Meaning | Remediation |
| --- | --- | --- |
| `not running` | No lock file | Run `ok start` |
| `alive` | Process responding on this host | — |
| `stale (dead pid=…)` | Lock exists but PID is dead | Run `ok clean` |
| `lock file corrupt` | Unparseable lock JSON | Run `ok clean` |
| `foreign host (…)` | Lock owned by another machine | Inspect remotely or wait |

Pass `--json` for structured output.

### `ok ps`

List all running Open Knowledge servers on the machine.

| Flag / argument | Description |
| --- | --- |
| `all` (positional) | Include stale `dead-pid` entries |
| `--all` | Same as positional `all` |
| `--json` | Emit structured JSON (always includes all statuses) |

Default view shows `running`, `desktop`, `foreign`, and `ui-orphan` entries. Columns include directory, API/UI ports, CPU/memory usage, status, PID, start time, and binary path.

### `ok clean`

Prune stale or corrupt lock files for the current project. Never touches live locks (`alive` or `foreign-host`). Removes locks in `dead-pid` or `corrupt` state only.

## Project lifecycle

### `ok init`

Scaffold `.ok/` in the current directory, initialize git, install skills, and register MCP entries for detected editors.

| Flag | Description |
| --- | --- |
| `--mcp` / `--no-mcp` | Register MCP server for editors (default: on) |
| `--dev-mcp` | Register a local dev MCP entry (`node` + `packages/cli/dist/cli.mjs`) |
| `--scope <user\|project\|both>` | MCP config write scope |
| `--shared` | Commit OK config alongside content (default for fresh repos) |
| `--local-only` | Keep OK config out of git via `.git/info/exclude` |

### `ok seed`

Scaffold a starter pack into the project.

| Flag | Description |
| --- | --- |
| `[path]` | Project directory (default: cwd) |
| `-p, --pack <id>` | Starter pack ID (default: Karpathy three-layer pack) |
| `-r, --root <path>` | Subfolder to scaffold into |
| `--list-packs` | List available packs and exit |
| `-y, --yes` | Skip confirmation |
| `--dry-run` | Print plan without writing |

### `ok clone <url> [dir]`

Clone a git repository and open it. Accepts `owner/repo` shorthand or full GitHub URLs.

| Flag | Description |
| --- | --- |
| `-b, --branch <branch>` | Branch to check out (falls back to default if missing) |
| `--json` | JSONL progress events |

Non-JSON mode clones, `chdir`s to the target, and runs `ok start`.

### `ok preview`

Read-only report of what content the file watcher will track, based on `.okignore` and `content.dir`.

## Editor and UI

### `ok ui`

Serve the React editor UI as a standalone process.

| Flag | Description |
| --- | --- |
| `-p, --port <port>` | UI port (`$PORT` env or kernel-allocated fallback if busy) |
| `-H, --host <host>` | Bind host (default: dual loopback `[::1]` + `127.0.0.1`) |

### `ok open <doc>`

Open a document in the desktop app or browser.

| Flag | Description |
| --- | --- |
| `--folder` | Treat `<doc>` as a folder route (browser only; requires running UI) |
| `--project <dir>` | Project root (default: cwd) |

`<doc>` must be a relative path with no `..`, leading `/`, or backslashes.

## Agent integration

### `ok mcp`

Start the MCP stdio server for the project knowledge base. AI editors spawn this command to expose knowledge-base tools.

| Flag | Description |
| --- | --- |
| `-p, --port <port>` | Proxy stdio to an existing HTTP MCP port (skips bundle proxy) |
| `--no-bundle-proxy` | Run the npm MCP server in-process instead of proxying to the macOS desktop bundle |

### `ok repair-skills`

Force a refresh of bundled `SKILL.md` files for installed AI editors (project-local and user-global). Runs automatically during `ok start`.

### `ok install-skill`

Build `openknowledge.skill` for Claude Desktop upload. Not needed for Claude Code — `ok init` covers that.

| Flag | Description |
| --- | --- |
| `--out <path>` | Output path (default: `~/Downloads/openknowledge.skill`) |
| `--no-open` | Build without OS file-association handoff |
| `--force` | Bypass install-state gate |

## Git sync

| Command | Description |
| --- | --- |
| `ok sync` | Commit, pull, and push to the remote |
| `ok pull` | Pull changes from the remote |
| `ok push` | Push commits to the remote |

All three accept `--json` for JSONL progress events.

## GitHub authentication

Parent command: `ok auth`.

| Subcommand | Description |
| --- | --- |
| `login` | GitHub OAuth device flow (`--host`, `--json`) |
| `status` | Show authentication status |
| `repos` | List accessible repositories |
| `signout` | Remove stored credentials |
| `pat` | Store a Personal Access Token |
| `git-credential` | Git credential helper (lookup protocol) |

## Team sharing

### `ok share`

GitHub publish flow helpers (requires authentication).

| Subcommand | Description |
| --- | --- |
| `owners` | List GitHub owners eligible to host a new repository |
| `name-check` | Check if `owner/name` is available |
| `publish` | Publish a no-remote project to GitHub (`--owner`, `--name`, `--visibility`, `--project-dir`, `--host`, `--json`) |

### `ok config-sharing`

Manage whether `.ok/` artifacts are committed or kept local-only per clone.

| Subcommand | Description |
| --- | --- |
| `share` | Switch to shared mode (remove OK paths from `.git/info/exclude`) |
| `unshare` | Switch to local-only mode (add OK paths to `.git/info/exclude`) |
| `status` | Print current sharing mode and excluded paths |

All accept `--project <dir>` and `--json`.

## Semantic search

Parent command: `ok embeddings`.

| Subcommand | Description |
| --- | --- |
| `set-key` | Store OpenAI embeddings API key in `~/.ok/secrets.yml` |
| `clear-key` | Remove stored key |
| `enable` | Turn semantic search on for this project (project-local config) |
| `disable` | Turn semantic search off |
| `status` | Show key presence, enabled state, coverage, provider (`--cwd`, `--json`) |

## Configuration

Parent command: `ok config`.

| Subcommand | Description |
| --- | --- |
| `validate` | Validate merged config (defaults → user → project) |
| `migrate` | Remove deprecated fields (`--scope project\|user\|both`, `--dry-run`) |

## Diagnostics

### `ok diagnose`

| Subcommand | Description |
| --- | --- |
| `health` | Environment health checks: `git`, `bun`, `config-yaml`, `content-dir`, `server-lock`, `shadow-repo`, `shadow-health`, `macos-codesig` (`--json`, `--verbose`, `--check <name>`, `--quiet`) |
| `process <pid>` | Capture diagnostic bundle for a running process (`--cpu-profile`, `--output`, `--no-inspector`) |
| `bundle` | Support bundle zip (`--pid`, `--out`, `--yes`, `--redact`) |

### `ok bug-report`

Generate a diagnostic bundle for bug reporting. `--reveal` / `--no-reveal` control Finder reveal (default: reveal).

## Environment variables

| Variable | Effect |
| --- | --- |
| `HOST` | Default server bind host |
| `PORT` | Default collaboration server port |
| `LOG_LEVEL` / `OK_CONSOLE_LEVEL` | Console log verbosity |
| `OK_RECLAIM_DISABLE` | Disable repair sweeps during `ok start` |
| `OK_BUNDLE_PROXY` / `OK_MCP_SPAWN_TIMEOUT_MS` | MCP bundle proxy and spawn timeout |
| `OK_MCP_AUTOSTART` | MCP shim auto-start behavior |

## Exit codes

| Code | Cause |
| --- | --- |
| `0` | Success |
| `1` | General failure (missing file, lock collision, stop/clean partial failure) |
| `2` | Invalid CLI arguments (e.g. `--mode=app` with `--open`) |
| `78` | Git not available or too old during `ok start` |

## Common workflows

<Steps>
  <Step title="Initialize and start">
    Run `ok init` in your content directory, then `ok start --open` to boot the server and open the editor.
  </Step>
  <Step title="Check server state">
    Run `ok status` for the current project or `ok ps` to see all running instances.
  </Step>
  <Step title="Stop or recover">
    Run `ok stop` to shut down the current project server. If locks are stale after a crash, run `ok clean` then `ok start` again.
  </Step>
  <Step title="Open a loose markdown file">
    Run `ok path/to/notes.md` for an ephemeral browser session, or `ok open <doc>` inside an initialized project.
  </Step>
</Steps>

<RequestExample>

```bash
# Start with browser open
ok start --open

# List all servers
ok ps

# Stop by port
ok stop 3921

# Open a file outside any project
ok ~/drafts/ideas.md
```

</RequestExample>

<ResponseExample>

```text
DIRECTORY           PORTS (API/UI)  CPU/MEM (API | UI)  STATUS    PID     STARTED  BINARY
~/my-wiki           3921 / 3922     0.3% / 1.2% | …    running   12345   2m ago   /usr/local/bin/ok

To stop a server: ok stop <port|pid|directory|all>
```

</ResponseExample>

## Related pages

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Run `ok init`, `ok start --open`, and verify MCP tools respond from a connected agent.
  </Card>
  <Card title="Collaboration server" href="/collaboration-server">
    Hocuspocus/Yjs server lifecycle, per-project locks, and MCP routing boundaries.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    YAML config keys, precedence order, and environment-only variables.
  </Card>
  <Card title="MCP tools reference" href="/mcp-tools-reference">
    Seventeen MCP tools, input nesting, preview envelopes, and conflict guards.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Diagnose lock state, run health checks, and recover from crash leftovers with `ok clean`.
  </Card>
</CardGroup>