CLI
All commands and flags.
Commands
| Command | Description |
|---|---|
| pk init | Create a knowledge project (local by default, --global for ~/.pk/). Harness installs globally. |
| pk prime | Print session-start context for an agent. |
| pk search | Find notes by keyword or meaning. |
| pk new | Create a note, decision, question, or source. |
| pk read | Print the full contents of a note. |
| pk write | Update a note and commit the change. |
| pk delete | Delete a note and commit. |
| pk lint | Validate note shape, required sections, and duplicate ids. |
| pk index | Rebuild the search index and embedding vectors. |
| pk history | Show episodic store activity from commits and git notes. |
| pk vocab | List tags by frequency across all notes. |
| pk config | Show or update global configuration. |
| pk use | Set the current global project. Writes currentProject to ~/.pk/config.json. |
| pk projects | List all global projects under ~/.pk/. Shows which is current. |
pk new
Prints the absolute path of the created file. Frontmatter is generated automatically — do not
edit id, type, or created after creation.
pk search
| Flag | Description |
|---|---|
| --type | Filter by note type: note, decision, question, source |
| --status | Filter by status: open, accepted, superseded… |
| --tag | Filter by tag |
| --limit | Maximum results (default 10) |
When embeddings are configured, search uses hybrid mode (BM25 + vector) automatically.
pk init
Available harnesses: opencode, pi. Without
flags, pk runs interactively.
Harness configs are installed globally — not in the project directory: ~/.config/opencode/plugins/, ~/.pi/agent/extensions/, ~/.agents/skills/pk/.
The plugin calls pk prime, which resolves context from CWD,
so one install works everywhere.
Default: knowledge store in .pk/ (local). Use --global to store in ~/.pk/<name>/ instead. Local mode writes .pk/config.json to the project root
and adds .pk/ to .gitignore. Global mode sets currentProject in ~/.pk/config.json.
Harness configs are installed globally once — they work from every directory.
pk use
Sets the current global project. Writes currentProject to ~/.pk/config.json. Used by requireKnowledgeDir() as a fallback
when no project-local config is found. Validates that the project exists.
pk projects
Lists all global projects under ~/.pk/. Indicates which is current.
Machine output
Every command accepts --json for structured output. Use --pretty for
human-readable formatting.