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 gc	Lifecycle maintenance: decay scoring, archive stale notes, purge expired. Run daily.
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

$pk new note "Title"

$pk new decision "Title"

$pk new question "Title"

$pk new source "Title"

$pk new note "Title" --tags auth,security

Prints the absolute path of the created file. Frontmatter is generated automatically — do not edit id, type, or created after creation.

Flag	Description
--tags	Comma-separated tags
--expires	Expiry date (YYYY-MM-DD). Archived automatically by `pk gc`.

pk search

$pk search "database schema"

$pk search "api" --type question --status open

$pk search "deploy" --tag infra --limit 5

$pk search "slow queries" --semantic

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 gc

$pk gc

$pk gc --dry-run

$pk gc --compress

$pk gc --pretty

Runs lifecycle maintenance on the knowledge store. Designed to be run daily via cron or manually.

Flag	Description
--dry-run	Preview what would happen without making changes.
--compress	Find similar notes for interactive merge. Run weekly.
--pretty	Human-readable output.

Decay scoring uses exponential decay with a 30-day half-life (configurable via PK_DECAY_HALF_LIFE env var). Notes not accessed for extended periods fade and are archived when their score drops below 0.1. Notes with an expires frontmatter date are archived when that date passes.

pk init

$pk init --harness opencode

$pk init my-project --harness opencode --global

$pk init my-project --harness opencode,pi --global

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

$pk use my-project

$pk use journal --pretty

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

$pk projects

$pk projects --pretty

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.

json output

$pk search "pricing" --json

$pk prime --json

$pk history --json