PKM

zk — CLI Note Linking and Graph Traversal

2 min read

zk — CLI Note Linking and Graph Traversal

zk is a plain-text note-taking CLI that maintains a SQLite index of markdown files, enabling fast link/backlink queries, graph traversal, and RTM-style traceability queries across a notebook.

Why / When to Use

Use zk when your notes use [[wiki-links]] and you need:

  • Fast backlink lookup (zk list --linked-by note.md)
  • Graph traversal (“what notes link to this requirement?“)
  • Gap-analysis queries for V-model / RTM traceability
  • Claude Code to read related documents before editing

zk is not a replacement for nb — it’s narrowly focused on linking/querying. nb handles capture, encryption, and sync.

Core Concept / Commands

# Initialise a notebook (creates .zk/config.toml)
zk init ~/notes/
 
# Create a new note from a template
zk new --title "My Note"
 
# List all notes
zk list
 
# Find notes linked from a note
zk list --linked-by path/to/note.md
 
# Find notes that link TO a note (backlinks)
zk list --link-to path/to/note.md
 
# Full-text search
zk list --match "requirement traceability"
 
# Open related notes in editor
zk edit --linked-by BR-001.md

Two-Notebook Pattern (PKM + SDLC)

Run two separate zk notebooks on the same machine without cross-contamination:

~/notes/            ← personal PKM notebook (.zk/ here)
~/projects/
  my-app/
    .zk/            ← project SDLC notebook (separate from PKM)
    docs/
      BR-001.md
      FR-001.md

Claude Code can query either notebook by running zk in the correct directory. Set separate AGENTS.md context per folder to tell Claude which notebook to use.

RTM / V-model Queries via zk

# All requirements without a linked test case
zk list --match "type: requirement" --no-link-to "type: test-case"
 
# All test cases that verify a specific FR
zk list --link-to docs/FR-001.md

This turns the RTM and V-model into live views rather than documents you maintain manually.

Key Options / Variants

  • zk config — edit .zk/config.toml for templates, aliases, default editor
  • zk graph — generate a DOT-format graph of links (pipe to Graphviz)
  • Multiple notebooks: ZK_NOTEBOOK_DIR=~/notes zk list to target a specific notebook from anywhere

Gotchas

  • zk uses case-sensitive filename matching for [[wiki-links]] on Linux
  • Each notebook has its own .zk/ — don’t nest notebooks
  • The SQLite index (.zk/notebook.db) is auto-rebuilt on zk index — safe to delete and regenerate
  • zk does NOT sync notes; use Git or cloud sync separately

Source

Conversation “Note Taking - General” — 2026-05-13

Graph View