CLI reference

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 both without 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/repo
git@github.com:owner/repo.git
ssh://git@github.com/owner/repo
owner/repo (expands to https://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:

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 get

Reads 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 preview

Prints the file count, applied include/exclude patterns, and a sample of matched paths.

CLI reference

On this page