Open KnowledgeCLI reference
Complete reference for the open-knowledge command-line interface.
The @inkeep/open-knowledge CLI is the primary interface for managing projects, authentication, and sync.
npx @inkeep/open-knowledge <command> [options]macOS desktop app
If you installed from the DMG, the CLI ships inside the app bundle and can be placed on your PATH via File → Install Command-Line Tools… (creates /usr/local/bin/ok + /usr/local/bin/open-knowledge symlinks after an admin prompt). No separate Node install required — the wrapper runs the bundled CLI via Electron's embedded Node. See Desktop app (first-launch consent) for how MCP wiring differs from the CLI's init flow.
Global options available on all commands:
| Option | Description |
|---|---|
--cwd <path> | Working directory |
--log-level <level> | Log level (default: info) |
--no-color | Disable color output |
--color | Force color output |
--version | Print version |
start
Start the collaborative editor server. This is the default command when no subcommand is specified.
npx @inkeep/open-knowledge start [options]
npx @inkeep/open-knowledge # equivalent| Option | Description |
|---|---|
--port <port> | Server port (overrides config) |
--host <host> | Bind address (overrides config) |
--open | Open the editor in your default browser |
--content-dir <path> | Content directory to serve |
--no-init | Skip .open-knowledge/ scaffolding and parent-repo git init |
The server binds to localhost:3000 by default. Only one server can run per content directory -- a second attempt fails with a lock collision error.
If the content directory has no .git/, start runs git init --initial-branch=main before the attribution journal is created. The CLI's first-run preview block discloses the auto-init with the line Initialized git repo at <cwd>/.git/ (default branch: main). If git is not on PATH, start exits non-zero with a clear install-or-init-yourself message.
To opt out of both .open-knowledge/ scaffolding and the parent-repo auto-git init, pass --no-init. The flag is a single opt-out for both scaffolding behaviors — start will boot against whatever state the directory is in, and the attribution journal still initializes if a .git/ exists. Useful for non-interactive smoke tests and for operators who prefer to manage git init themselves.
init
Scaffold the .open-knowledge/ directory and register the MCP server in editor config files.
npx @inkeep/open-knowledge init [options]| Option | Description |
|---|---|
--editor <names> | Target specific editors instead of all detected editors |
--scope <user|project|both> | Where to write MCP config (see below) |
--force | Overwrite existing Open Knowledge MCP and preview-launcher entries |
--no-mcp | Skip writing editor MCP config |
--dev-mcp | Point MCP config and Claude Code preview launchers at the local packages/cli/dist/cli.mjs build |
Scope selection. init writes MCP config to the user level (~/.claude.json, ~/.cursor/mcp.json, etc.), the project level (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml in the working directory), or both:
- Interactive (TTY): a checkbox prompt appears with both scopes pre-selected. Deselect either to write only the other.
- Non-interactive (piped, scripted, CI): defaults to
bothwithout prompting. --scope <user|project|both>: bypasses the prompt and writes exactly the specified scope.
Project-level configs are useful for teams who want all contributors to pick up the same MCP wiring without each person running ok init individually — commit .mcp.json (and equivalent files for other editors) to the repository. Note: Windsurf and Claude Desktop do not have a standardized project-local config format and are skipped for project-scope writes.
The command is idempotent -- safe to run again without side effects. If the project has no .git/, init runs git init --initial-branch=main first and prints the same disclosure line as start.
Desktop app users may already have MCP wired — the first-launch consent dialog writes user-level MCP entries without any of the project-scoped scaffolding (.open-knowledge/, AGENTS.md, launch.json) that ok init performs. Run init when you want that project-scoped scaffolding; the dialog and the CLI can coexist. See MCP integration.
clone
Clone a git repository, scaffold .open-knowledge/, and start the editor.
npx @inkeep/open-knowledge clone <url> [dir] [options]| Argument | Description |
|---|---|
url | Repository URL or owner/repo shorthand |
dir | Target directory (default: ./<repo-name>) |
| Option | Description |
|---|---|
--json | Output JSONL progress events (for editor subprocess relay) |
Accepted URL formats:
https://github.com/owner/repogit@github.com:owner/repo.gitssh://git@github.com/owner/repoowner/repo(expands tohttps://github.com/owner/repo)
In terminal mode, clone chains into start after completion. In --json mode, it emits JSONL and exits (the editor spawns the server separately).
auth
Manage GitHub authentication. Six subcommands:
auth login
Sign in via GitHub's Device Flow (OAuth).
npx @inkeep/open-knowledge auth login [options]| Option | Description |
|---|---|
--host <host> | GitHub hostname (default: github.com) |
--json | Output JSON events |
auth status
Check authentication status for a host.
npx @inkeep/open-knowledge auth status [options]| Option | Description |
|---|---|
--host <host> | GitHub hostname (default: github.com) |
--json | Output JSON |
Exits with code 1 if not authenticated.
auth repos
List repositories accessible with the current token.
npx @inkeep/open-knowledge auth repos [options]| Option | Description |
|---|---|
--host <host> | GitHub hostname (default: github.com) |
--json | Output JSON |
auth signout
Remove the stored token for a host.
npx @inkeep/open-knowledge auth signout [options]| Option | Description |
|---|---|
--host <host> | GitHub hostname (default: github.com) |
auth pat
Validate and store a Personal Access Token.
npx @inkeep/open-knowledge auth pat [options]| Option | Description |
|---|---|
--host <host> | GitHub hostname (default: github.com) |
--json | Output JSON |
The token is read interactively from stdin.
auth git-credential
Git credential helper that reads stored tokens. Not intended for direct use -- invoked by git via the -c credential.helper flag.
npx @inkeep/open-knowledge auth git-credential getReads the git credential-helper protocol from stdin and outputs stored credentials for the requested host.
sync
Commit local changes, pull from remote, and push to remote.
npx @inkeep/open-knowledge sync [options]| Option | Description |
|---|---|
--json | Output JSONL progress events |
Discovers a running server via server.lock and delegates to its sync engine. Falls back to direct simple-git operations when no server is running.
push
Push local commits to the remote.
npx @inkeep/open-knowledge push [options]| Option | Description |
|---|---|
--json | Output JSONL progress events |
pull
Pull changes from the remote.
npx @inkeep/open-knowledge pull [options]| Option | Description |
|---|---|
--json | Output JSONL progress events |
mcp
Start the MCP stdio server for AI agent integration.
npx @inkeep/open-knowledge mcp [options]The MCP server auto-discovers a running editor via server.lock. When no editor is running, it operates in disk-only mode. See MCP integration for details.
preview
Show which files the content filter will track, without starting the server.
npx @inkeep/open-knowledge previewPrints the file count, applied include/exclude patterns, and a sample of matched paths.
publish
Export the configured markdown scope to static HTML for hosting (GitHub Pages, Netlify, any static file host).
publish build
npx @inkeep/open-knowledge publish build [options]Reads content.dir, content.include, and content.exclude from .open-knowledge/config.yml (same scope as the collab server). Optional settings live in .open-knowledge/publish.yml:
| Key | Description |
|---|---|
siteTitle | Site name shown in the header and <title> suffix |
basePath | URL prefix when the site is not served at the domain root (e.g. /docs) |
outputDir | Directory under the project root to write (default: .open-knowledge/site) |
exclude | Additional glob patterns (picomatch) to omit from the export |
CLI overrides (highest precedence): --output-dir, --site-title, --base-path. Pass --no-clean to merge into an existing output directory instead of deleting it first. --json prints the build result as JSON (pages, assets, warnings).
The build warns on broken internal links and missing targets excluded from the export, but still writes pages unless configuration is invalid.