storage-zk

パーソナル Wiki：wiki CLI の使用方法

クイックスタート：wiki CLI

wiki CLI はノートブックのパスを賢く検出します。

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

検出されたノートブックを使用（パスは内部で自動検出）

wiki CLI を使った一般的なワークフロー

1 件のノート：作成 → リンク → 検索 → エクスポート

# 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 current project with notebook (for context matching)
wiki project add

プロジェクトのすべてのノートをエクスポート

# 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"

使用する場面

次のような場合に使用します：

• さまざまな形式でノートをエクスポートする必要がある
• プロジェクトとノートブックの対応付けを自動化したい
• 複数のプロジェクトやノートブックを扱っている 次のような場合は使用しません：
• ノートブックの設定を編集する場合（config.toml については zk のドキュメントを参照してください）
• 高度なテンプレートを使用する場合（テンプレートは Handlebars です。zk のドキュメントを参照してください）
• LSP をセットアップする場合（言語サーバーの統合には個別の設定が必要です）

wiki と直接 zk コマンドを使い分ける

場面	使用するもの	例
ノートブックの自動検出	wiki CLI	wiki new --title "Note"（自動検出）
ノートブックを明示的に指定	直接 zk	zk list -W /path --match="x"（明示的に指定）
プロジェクトのコンテキストを登録	wiki project add	今後、このプロジェクトの検出に役立ちます

クイックリファレンス：wiki CLI コマンド

タスク	コマンド	備考
ノートを作成	wiki new --title "Title" --print-path	ノートブックを自動検出し、パスを返します
すべてのノートを一覧表示	wiki list	デフォルトはテーブル形式です
パターンを検索	wiki list --match="pattern"	正規表現またはプレーンテキスト
JSON をエクスポート	wiki list --format=json > file.json	出力にはリダイレクトを使用します
CSV をエクスポート	wiki list --format=csv > file.csv	RFC 4180 に準拠。CSV パーサーを使用してください
1 行形式でエクスポート	wiki list --format=oneline > file.txt	最小限の形式で、解析が簡単です
バックリンクを検索	wiki list --linked-by=<note-id>	対象にリンクしているノートを表示します
ノートの詳細を表示	wiki list --match=<note-id> --format=long	メタデータとプレビューを含みます

クイックリファレンス：直接 zk コマンドを使う（明示的な指定が必要な場合）

タスク	コマンド	備考
ノートを作成	zk new -W <dir> --title "Title" --print-path	ノートブックのパスを明示的に指定する必要があります
すべてのノートを一覧表示	zk list -W <dir>	必ず -W フラグを含めてください
パターンを検索	zk list -W <dir> --match="pattern"	正規表現またはプレーンテキスト
JSON をエクスポート	zk list -W <dir> --format=json > file.json	出力にはリダイレクトを使用します
CSV をエクスポート	zk list -W <dir> --format=csv > file.csv	RFC 4180 に準拠。CSV パーサーを使用してください
バックリンクを検索	zk list -W <dir> --linked-by=<note-id>	対象にリンクしているノートを表示します

絞り込みオプション

フィルター	構文	例	注記
タイトル／本文	--match="pattern"	zk list -W /nb --match="daily"	正規表現またはプレーンテキストで検索します
リンク元	--linked-by=<id>	zk list -W /nb --linked-by=abc123	abc123 にリンクしているノートを表示します
その他のフィルター	zk list --help を確認	zk list --help | grep -i filter	ZK には、ここに記載されていない追加のフィルターがある場合があります
重要： ここに記載されていない絞り込みを使う場合は、構文を推測せず、必ず zk list --help で確認してください。ZK の新しいバージョンでは、フィルターが追加されている場合があります。

ノートブックの検出について

wiki CLI は、スマート検索アルゴリズムを使ってノートブックの検出を自動的に処理します。-W フラグを手動で指定する必要はありません。

wiki がノートブックを検出する方法

wiki コマンドを実行すると、次の順序で検索します：

1. 環境変数 NOTEBOOK_PATH（明示的に設定されている場合）
2. 親ディレクトリにある .zk/config.toml（プロジェクトローカルのノートブックを検出します）
3. ~/Notes/ のコンテキストレジストリ（プロジェクトのパスと登録済みのノートブックを照合します）
4. グローバルなフォールバック ~/.config/zk/config.toml（notebook.dir が定義されている場合） 利点： パスを間違える心配はありません。wiki コマンドを実行するだけです。

直接 zk コマンド：明示的な -W フラグが必須

wiki を使わずに zk を直接使う場合は、必ず -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"

~/projects/project-a/notes/ にいるときに -W を指定せずに zk list を実行すると、代わりに ~/projects/.zk が見つかることがあります。

トラブルシューティング：アクティブなノートブックを確認する

# 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

リンク作成のパターン

ZK には zk link コマンドはありません。リンクは Markdown ファイルを直接編集して作成します：

Wiki 形式のリンク（最も一般的）

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

ZK はこれらを、一致するノート ID に自動的に解決します。ID には、拡張子を除いたファイル名、またはノートのフロントマターに明示された ID フィールドを使用できます。

Markdown リンク（こちらも有効）

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

ZK は両方の形式に対応しています。相互参照には Wiki 形式の [[]] が推奨されます。

バックリンクの検索

特定のノートにリンクしているすべてのノートを検索します：

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

エクスポートのワークフロー

パターン： --format フラグを指定した zk list と出力のリダイレクトを使用します

一括エクスポートの前に：安全チェックリスト

一括エクスポート（ノート 100 件以上）は、検証していないと危険な場合があります：

• ノートブックのバックアップはありますか？（cp -r /notebook /notebook.backup）
• 最初にテストデータへエクスポートしていますか？（形式を検証するため、まずは --match="test" を指定します）
• エクスポートする内容を理解していますか？（リンクを参照として含めるのか、本文全体なのか、メタデータなのか）
• 出力形式は有効ですか？（head -5 export.json | jq . でテストします） 例：安全な一括エクスポート

# 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 エクスポート（プログラムでの処理）

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

出力には、ID、タイトル、パス、本文、タグ、関連情報が含まれます

CSV エクスポート（スプレッドシートへのインポート）

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

出力列：タイトル、パス、更新日。awk ではなく CSV リーダーで解析してください。

1 行形式のエクスポート（grep 可能）

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

出力：ノートごとに 1 行で id - title - path

よくある間違い

間違い	問題	修正方法
-W フラグなしで zk を使う	どのノートブックが使われるか曖昧	wiki CLI（自動検出）または明示的な -W /path を使用する
zk export	エクスポートコマンドが存在しない	wiki list --format=X > file（または zk list -W <dir>...）を使用する
zk link note1 note2	リンクコマンドがない	Markdown ファイルを編集し、[[note-id]] を手動で追加する
wiki list --match="x" が失敗する	ノートブックが検出されていない	wiki project discover を実行してパスを確認する
--format json（リダイレクトなし）	出力はファイルではなく stdout に表示される	> file.json を使って出力を取得する
[[id]] ではなく [[filepath]] を使用する	Wiki リンクではパスではなく ID を使う	ノート ID または拡張子を除いたファイル名を使う
リンクは CLI 側で作成されると思い込む	リンクは手動で編集する	ノートファイルを直接編集して、必ずリンクを追加する
スクリプトにノートブックのパスをハードコードする	プロジェクトを移動すると動作しなくなる	代わりに wiki CLI または wiki project discover を使用する

参照：出力形式

テーブル（デフォルト）

id | title | path

詳細（メタデータを含む）

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

JSON（プログラムでの解析）

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

CSV（スプレッドシートへのインポート）— RFC 4180 準拠

形式： 引用符で囲まれたフィールドをカンマで区切り、ヘッダー行を含みます

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

重要： タイトルにカンマが含まれる場合があるため、awk -F',' ではなく、適切な CSV パーサーで CSV を解析してください。Python を使った例：

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

1 行形式（grep 可能）

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

ワークフローの例

単一ノート：作成 → リンク → 検索 → エクスポート（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

利点： ノートブックのパスを手動で見つける必要はありません。wiki が処理します。

単一ノート：直接 zk を使用する場合（明示的な制御が必要なとき）

# 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

注： 手順 2 では、ファイルを手動で編集する必要があります。リンクを作成する CLI コマンドはありません。Markdown の内容にリンクを追加してください。

一括：複数のノートを作成してマスターノートにリンクする（wiki を使用）

マスターノートにリンクするノートを 10 件以上作成する場合：

#!/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

利点： ノートブックのパスを見つけたり、渡したりする必要はありません。wiki が自動的に処理します。

一括：直接 zk を使用する場合（ノートブックのパスを明示）

ノートブックを明示的に制御する場合：

#!/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

制約： ZK には一括リンクコマンドがありません。スクリプトを使った手動編集が標準的な方法です。

大規模なノートブックを安全にエクスポートする（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

利点： パスを手動で見つける必要はありません。

大きなノートブックを安全にエクスポートする（パスを明示した直接の zk）

#!/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

実際の効果

このスキルがない場合： エージェントは存在しないコマンド（zk export、zk link）を推測して時間を浪費し、-W フラグに戸惑い、フォーマットのオプションに苦労します。 このスキルがある場合： エージェントは存在するコマンドを正確に把握し、作業ディレクトリの動作を理解し、エクスポートのパターンを習得して、存在しないコマンドを試す無駄を避けられます。