CLI reference

npx @inkeep/open-knowledge <command> [options]

Both open-knowledge and ok work — they're the same command.

Global options

Option	Description
`--cwd <path>`	Working directory used to resolve config
`--log-level <level>`	Log level (default: `info`)
`--no-color` / `--color`	Disable or force color output
`--version`	Print version

`start`

Run the collaborative editor server. Default command when no subcommand is specified.

ok start [options]
ok                     # equivalent

Flag	Description
`-p, --port <port>`	Server port (overrides config and the `PORT` env)
`-H, --host <host>`	Bind address (overrides config and the `HOST` env)
`--open`	Open the editor in your default browser
`--mode <browser\|app>`	Force dispatch mode. `app` hands off to the desktop bundle when installed

ok start operates against the current working directory and does not scaffold. If .ok/ is missing it exits with a clean error pointing you at init — init is the only command that writes project state.

The content directory comes from content.dir in .ok/config.yml (see Configuration).

`init`

Scaffold the .ok/ directory and register MCP server entries in every detected editor.

ok init [options]

Flag	Description
`--scope <user\|project\|both>`	Where to write MCP config (default: both)
`--no-mcp`	Skip writing editor MCP config

When invoked from a sub-folder of a git repo with no ancestor .ok/, init writes .ok/ at the git working-tree root and content.dir is scoped to the relative sub-path. One .ok/ per git repo.

See Integrations for the per-editor config paths init writes to. Safe to re-run.

`clone`

Clone a git repository, scaffold .ok/, and start the editor.

ok clone <url> [dir]

URL forms accepted: https://github.com/owner/repo, git@github.com:owner/repo.git, ssh://git@github.com/owner/repo, or the shorthand owner/repo.

Flag	Description
`--json`	Emit JSONL progress events for tooling

`mcp`

Run the MCP server. Editors invoke this command for you — you rarely run it yourself.

ok mcp [--port <port>]

If no server is running, ok mcp starts one automatically. Set OK_MCP_AUTOSTART=0 to opt out.

`install-skill`

Build the Open Knowledge skill bundle for the Claude Desktop App's Chat and Cowork modes.

ok install-skill [options]

Flag	Description
`--out <path>`	Custom output path (default: `~/Downloads/openknowledge.skill`)
`--no-open`	Build the file without launching Claude Desktop
`--force`	Rebuild even if the skill is already up to date

Full walkthrough: Claude Desktop.

`seed`

Scaffold a starter knowledge-base structure: three folders (external-sources/, research/, articles/) plus a log.md.

ok seed [path] [options]

[path] sets the project directory (defaults to the current directory).

Flag	Description
`-r, --root <path>`	Subfolder to scaffold into instead of the project root
`-y, --yes`	Skip the confirmation prompt
`--dry-run`	Print the plan and exit without writing

`ui`

Serve the editor. Started automatically when an agent writes — you rarely run it yourself.

ok ui [--port <port>] [--host <host>]

Lifecycle

ok status [--json]   # Show running server + editor (add --json for structured output)
ok ps [--all] [--json] # List running servers; --all also includes stale (dead-pid) entries
ok stop              # Stop the server and editor
ok clean             # Clean up after a crashed run

The server shuts itself down after 30 minutes idle, so you rarely need to stop it by hand.

`preview`

Print the file count and a sample of paths matched by your content scope, without starting the server.

ok preview

Useful after editing .okignore to confirm exclusions worked.

`config`

Inspect and maintain .ok/config.yml.

`config validate`

Check .ok/config.yml against the schema. Exits non-zero on errors with a file:line:col snippet.

ok config validate

`config migrate`

Strip fields that have been removed from the schema since your config was written.

ok config migrate                    # both scopes
ok config migrate --dry-run          # preview removals
ok config migrate --scope project    # one scope

Flag	Description
`--dry-run`	Preview removals without writing
`--scope <project\|user\|both>`	Which file to migrate (default: both)

`auth`

Manage GitHub authentication for GitHub sync.

ok auth login              # Sign in to GitHub
ok auth status             # Check sign-in status
ok auth repos              # List accessible repositories
ok auth signout            # Remove the stored token
ok auth pat                # Validate and store a Personal Access Token
ok auth git-credential     # Git credential helper (invoked by git)

Most subcommands accept --host <host> (default: github.com) and --json for structured output.

`sync` / `push` / `pull`

Sync changes with the remote git repository.

ok sync     # Commit local changes, pull, and push
ok push     # Push local commits
ok pull     # Pull from the remote

All three accept --json for structured progress events.

CLI reference

On this page