storage-zk（存储 zk）

Personal Wiki: Using the wiki CLI

Quick Start: wiki CLI

The wiki CLI intelligently discovers your notebook patih.

wiki new --title "My Note"
wiki list --match="pattern"
wiki list --format=json | jq .

Use discovered notebook (auto-discovers path internally)

Common Workflows with wiki CLI

Single Note: Create → Link → Search → Export

# 1. Create new note (auto-discovers notebook)
NOTE_PATH=$(wiki new --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [existing-note-id](Existing Note Title)" >> "$NOTE_PATH"
# 3. Search for related notes
wiki list --match="Research" --format=long
# 4. Export results
wiki list --match="Research" --format=json | jq .

Register Project with Notebook

# Register current project with notebook (for context matching)
wiki project add

Export All Notes from Project

# Get notebook, then export
NOTEBOOK=$(wiki project discover)
wiki list --format=json > all-notes.json
# Validate export
jq . < all-notes.json > /dev/null && echo "Valid JSON"

When to Use

Symptoms:

• Need to export notes in various formats
• Want automatic project-to-notebook mapping
• Working with multiple projects and notebooks When NOT to use:
• Editing notebook configuration (see zk documentation for config.toml)
• Advanced templating (templates are Handlebars, see zk docs)
• LSP setup (language server integration, separate config)

wiki vs. Direct zk Commands

Quick Reference: wiki CLI Commands

Quick Reference: Direct zk Commands (When You Need Explicit Control)

Filtering Options

Understanding Notebook Discovery

The wiki CLI automatically handles notebook discovery using a smart search algorithm. No need to manually specify -W flags.

How wiki Discovers Your Notebook

When you run any wiki command, it searches in this order:

1. Environment variable NOTEBOOK_PATH (if explicitly set)
2. Ancestor directories for .zk/config.toml (finds project-local notebooks)
3. Context registry in ~/Notes/ (matches your project path to a registered notebook)
4. Global fallback ~/.config/zk/config.toml (if it defines a notebook.dir) Advantage: You don't need to worry about getting the path wrong. Just run wiki commands.

Direct zk Commands: Explicit -W Flag Required

If you bypass wiki and use zk directly, you must always include -W:

# ❌ DON'T - unsafe, ambiguous which notebook is used
zk list --match="search"
# ✅ DO - explicit notebook path
zk list -W /path/to/notebook --match="search"

If you're in ~/projects/project-a/notes/ and run zk list without -W, it might find ~/projects/.zk instead.

Troubleshooting: Verify Which Notebook Is Active

# Using wiki (recommended)
wiki project discover
# Returns: /path/to/notebook
# Using direct zk with explicit path
zk info -W /path/to/notebook
# Shows: notebook path, config, note count

Link Creation Patterns

ZK does not have a zk link command. Links are created by editing markdown files directly:

Wiki-style Links (Most Common)

This note connects to [[other-note-id]] and [[another-one]].

ZK automatically resolves these to matching note IDs. The ID can be filename without extension or explicit ID field in note frontmatter.

Markdown Links (Also Valid)

See [related note](/path/to/note.md) for details.

ZK understands both formats. Wiki-style [[]] is preferred for cross-referencing.

Backlink Discovery

Find all notes linking to a specific note:

zk list -W /notebook --linked-by=target-note-id

Export Workflows

Pattern: Use zk list with --format flag + output redirection

Before Any Bulk Export: Safety Checklist

Bulk exports (100+ notes) can be dangerous if not validated:

• Do you have a backup of the notebook? (cp -r /notebook /notebook.backup)
• Are you exporting to test data first? (Start with --match="test" to validate format)
• Do you understand what you're exporting? (Links as refs? Full body? Metadata?)
• Is the output format valid? (Test with head -5 export.json | jq.) Example: Safe bulk export

# 1. Validate on one note
zk list -W /notebook --match="note-id" --format=json | jq .
# 2. Check structure is what you expect
# (inspect the JSON output)
# 3. Export to temp file first
zk list -W /notebook --format=json > /tmp/export.json
# 4. Validate output is valid JSON
jq . < /tmp/export.json > /dev/null && echo "Valid JSON"
# 5. Move to final location
mv /tmp/export.json ~/exports/notes.json

JSON Export (Programmatic)

zk list -W /notebook --match="tag:project" --format=json > export.json

Output includes: id, title, path, body, tags, relationships

CSV Export (Spreadsheet Import)

zk list -W /notebook --format=csv > notes.csv

Output columns: title, path, modified date. Parse with CSV reader, not awk.

Oneline Export (Grep-able)

zk list -W /notebook --format=oneline > index.txt

Output: id - title - path on single line per note

Common Mistakes

Reference: Output Formats

Table (Default)

id | title | path

Long (Includes Metadata)

id: xxx
title: My Note
path: /notebook/notes/xxx.md
links: [[id1]], [[id2]]

JSON (Programmatic Parsing)

[{"id":"xxx","title":"My Note","tags":["tag1"],"path":"/notebook/notes/xxx.md"}]

CSV (Spreadsheet Import) — RFC 4180 Compliant

Format: Quoted fields, comma-separated, includes header row

title,path,modified
"My Note",/notebook/notes/xxx.md,2025-01-15
"Note with, comma",/notebook/notes/yyy.md,2025-01-14

Important: Parse CSV with a proper CSV parser, not awk -F',', because titles can contain commas. Example with Python:

import csv
with open('notes.csv') as f:
    for row in csv.DictReader(f):
        print(row['title'], row['path'])

Oneline (Grep-able)

xxx - My Note - /notebook/notes/xxx.md

Workflow Examples

Single Note: Create → Link → Search → Export (Using wiki CLI)

# 1. Create new note (notebook auto-discovered)
NOTE_PATH=$(wiki new --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [[existing-note-id]]" >> "$NOTE_PATH"
# 3. Search for related notes
wiki list --match="Research" --format=long
# 4. Export results
wiki list --match="Research" --linked-by="research-topic-id" --format=json > related-notes.json

Advantage: No need to discover notebook path manually. wiki handles it.

Single Note: Using Direct zk (When You Need Explicit Control)

# 1. Create new note with explicit notebook path
NOTEBOOK="/path/to/notebook"
NOTE_PATH=$(zk new -W "$NOTEBOOK" --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [[existing-note-id]]" >> "$NOTE_PATH"
# 3. Search for related notes
zk list -W "$NOTEBOOK" --match="Research" --format=long
# 4. Export results
zk list -W "$NOTEBOOK" --match="Research" --linked-by="research-topic-id" --format=json > related-notes.json

Note: Step 2 requires manual file editing. No CLI command creates links; you add them to markdown content.

Bulk: Create Multiple Notes & Link to Master (Using wiki)

For creating 10+ notes that all link to a master note:

#!/bin/bash
MASTER_ID="master-index"
# Create notes in a loop (notebook auto-discovered)
for i in {1..10}; do
  NOTE_PATH=$(wiki new \
    --title "Topic $i" \
    --print-path)

  # Add link to master note
  echo "" >> "$NOTE_PATH"
  echo "See master: [[${MASTER_ID}]]" >> "$NOTE_PATH"
done
# Verify all notes link to master
wiki list --linked-by="$MASTER_ID" --format=long

Advantage: No need to discover or pass notebook path. wiki handles it automatically.

Bulk: Using Direct zk (Explicit Notebook Path)

For explicit control over notebook:

#!/bin/bash
NOTEBOOK="/path/to/notebook"
MASTER_ID="master-index"
# Create notes in a loop
for i in {1..10}; do
  NOTE_PATH=$(zk new -W "$NOTEBOOK" \
    --title "Topic $i" \
    --print-path)

  # Add link to master note
  echo "" >> "$NOTE_PATH"
  echo "See master: [[${MASTER_ID}]]" >> "$NOTE_PATH"
done
# Verify all notes link to master
zk list -W "$NOTEBOOK" --linked-by="$MASTER_ID" --format=long

Constraint: ZK doesn't have a bulk-link command. Manual editing via script is the standard approach.

Export Large Notebook Safely (Using wiki)

#!/bin/bash
EXPORT_DIR="$HOME/exports"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Create export directory with timestamp
mkdir -p "$EXPORT_DIR"
# Test export format on small sample (notebook auto-discovered)
echo "=== Testing format on 1 note ==="
wiki list -l 1 --format=json | jq . > /dev/null
if [ $? -ne 0 ]; then
  echo "ERROR: JSON validation failed"
  exit 1
fi
# Full export
echo "=== Exporting all notes ==="
wiki list --format=json > "$EXPORT_DIR/export_${TIMESTAMP}.json"
# Validate output
jq . < "$EXPORT_DIR/export_${TIMESTAMP}.json" > /dev/null
if [ $? -eq 0 ]; then
  echo "✓ Export successful: $EXPORT_DIR/export_${TIMESTAMP}.json"
else
  echo "✗ Export failed: JSON is invalid"
  exit 1
fi

Advantage: No manual path discovery needed.

Export Large Notebook Safely (Direct zk with Explicit Path)

#!/bin/bash
NOTEBOOK="/path/to/notebook"
EXPORT_DIR="$HOME/exports"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Create export directory with timestamp
mkdir -p "$EXPORT_DIR"
# Test export format on small sample
echo "=== Testing format on 1 note ==="
zk list -W "$NOTEBOOK" -l 1 --format=json | jq . > /dev/null
if [ $? -ne 0 ]; then
  echo "ERROR: JSON validation failed"
  exit 1
fi
# Full export
echo "=== Exporting all notes ==="
zk list -W "$NOTEBOOK" --format=json > "$EXPORT_DIR/export_${TIMESTAMP}.json"
# Validate output
jq . < "$EXPORT_DIR/export_${TIMESTAMP}.json" > /dev/null
if [ $? -eq 0 ]; then
  echo "✓ Export successful: $EXPORT_DIR/export_${TIMESTAMP}.json"
else
  echo "✗ Export failed: JSON is invalid"
  exit 1
fi

Real-World Impact

Without this skill: Agents waste time guessing at nonexistent commands (zk export, zk link), get confused by -W flag, and struggle with format options. With this skill: Agents know exactly which commands exist, understand working directory behavior, master export patterns, and avoid wasted attempts at missing commands.