Skip to main content

​
Overview

The kosh cache commands provide tools to inspect, maintain, and troubleshoot Kosh’s BLAKE3-based build cache. The cache stores rendered posts, search indexes, and SSR artifacts to enable fast incremental builds.

​
Usage

kosh cache <subcommand> [flags]

​
Subcommands

​
stats

Display cache statistics and performance metrics. 
kosh cache stats

$ kosh cache stats
📊 Cache Statistics
════════════════════════════════════════
Schema Version:  2
Total Posts:     42
Total SSR:       128 artifacts
Store Size:      12.45 MB
Build Count:     87
Last GC:         2026-03-03T10:30:00Z

📦 Storage Metrics
────────────────────────────────────────
Inline Posts:    38 (90.5%)
Hashed Posts:    4 (9.5%)
Metrics Explained:
  • Schema Version: Cache format version (current: 2)
  • Total Posts: Number of cached post metadata entries
  • Total SSR: Count of server-side rendered artifacts (D2 diagrams, LaTeX math)
  • Store Size: Total size of content-addressed blob storage
  • Build Count: Number of builds performed
  • Last GC: Timestamp of last garbage collection
  • Inline Posts: Posts with HTML stored inline (< 32KB)
  • Hashed Posts: Posts with HTML in content-addressed storage (≥ 32KB)

​
gc

Run garbage collection to remove orphaned cache entries. 
kosh cache gc [flags]
​
--dry-run
boolean
default:"false"
Show what would be deleted without actually deleting. Also accepts -n.
$ kosh cache gc
🗑️  Running garbage collection...
════════════════════════════════════════
Scanned:    156 blobs
Live:       142 blobs
Deleted:    14 blobs (2.34 MB)
Duration:   234ms

✅ GC complete
When to Run GC:
  • After deleting many posts
  • After changing post content significantly (orphans old HTML blobs)
  • Store size grows much larger than content size
  • Periodically (monthly) for maintenance

​
verify

Check cache integrity and detect corruption. 
kosh cache verify

$ kosh cache verify
🔍 Verifying cache integrity...
✅ Cache is healthy - no issues found
Common Issues:
  • Orphaned blobs: Old content not yet GC’d (run kosh cache gc)
  • Missing blobs: Corruption or manual deletion (run kosh cache rebuild)
  • Hash mismatches: Cache corruption (run kosh cache rebuild)

​
rebuild

Clear the cache to force a full rebuild on next build. 
kosh cache rebuild

$ kosh cache rebuild
🔄 Clearing cache for rebuild...
✅ Cache cleared. Run 'kosh build' to rebuild.
Use When:
  • Cache verification shows errors
  • Upgrading Kosh to a new version
  • Debugging unexpected build behavior
  • Template changes not triggering rebuilds
Note: This preserves the cache database but clears all cached data. Next build will be slower but will repopulate the cache.

​
clear

Delete all cache data including the database file. 
kosh cache clear

$ kosh cache clear
🗑️  Clearing all cache data...
✅ Cache cleared
Warning: This is more aggressive than rebuild. Use when:
  • Cache database is corrupted
  • Migrating to a new cache directory
  • Troubleshooting cache-related crashes

​
inspect

Show detailed information about a specific cached file. 
kosh cache inspect <path>

$ kosh cache inspect content/my-post.md
📄 Cache Entry
════════════════════════════════════════
PostID:       550e8400-e29b-41d4-a716-446655440000
Path:         content/my-post.md
Title:        Understanding Go Context
ModTime:      2026-03-03T14:22:00Z
ContentHash:  a1b2c3d4...f9e8d7c6
HTMLHash:     1a2b3c4d...9f8e7d6c
Date:         2026-03-01
Tags:         [go concurrency]
WordCount:    1847
ReadingTime:  9 min
Draft:        false
Pinned:       false
Version:      v2.0
SSR Hashes:   3 artifacts
Hash Display:
  • Full BLAKE3 hashes are truncated to first 8 and last 8 characters
  • ContentHash: Hash of frontmatter + body content
  • HTMLHash: Hash of rendered HTML output
  • SSR Hashes: Hashes of D2 diagrams and LaTeX math inputs

​
Cache Architecture

​
Storage Strategy

Kosh uses a hybrid storage approach: Inline Storage (posts < 32KB):
  • HTML stored directly in metadata
  • Faster access (single database read)
  • Used for ~90% of typical posts
Content-Addressed Storage (posts ≥ 32KB):
  • HTML stored in blob storage by BLAKE3 hash
  • Deduplicates identical content
  • Reduces database size

​
Cache Keys

Post Metadata:
  • Primary key: PostID (UUID v5 from path)
  • Indexed by: Path, ContentHash
Search Indexes:
  • Stored per-post with BM25 word frequencies
  • Includes normalized title and content
SSR Artifacts:
  • D2 diagrams and LaTeX math cached by input hash
  • Prevents re-rendering unchanged diagrams

​
Invalidation

Cache entries are invalidated when:
  1. Content changes: Frontmatter or body modified (detected via body hash)
  2. Template changes: Affecting templates trigger post re-render
  3. Dependency changes: Global CSS, config, etc.
  4. Manual clear: kosh cache rebuild or kosh cache clear

​
Performance Impact

Typical build performance with cache:
ScenarioBuild TimeCache Hit Rate
Full rebuild (cold cache)10.2s0%
No changes0.8s100%
Single post edit1.2s98%
Template change3.4s0% (rehydrate)
Config change9.8s0%
Cache Rehydration: When only templates change, the cache rehydrates metadata without re-parsing Markdown (3-5x faster than cold rebuild).

​
Cache Location

Default cache directory: .kosh-cache/ in project root. Override in kosh.yaml: 
cacheDir: ".build-cache"  # Custom location

​
Cache Modes

Production Mode (default):
  • Full durability with fsync
  • Safer but slightly slower
  • Used by kosh build and cache commands
Development Mode:
  • Less durable, faster writes
  • Used by kosh serve --dev
  • Acceptable risk for local development

​
Troubleshooting

​
Cache Not Working

  1. Check stats: kosh cache stats - verify cache has entries
  2. Verify integrity: kosh cache verify
  3. Rebuild cache: kosh cache rebuild

​
Cache Too Large

  1. Run GC: kosh cache gc - remove orphaned blobs
  2. Check SSR artifacts: Many diagrams? Consider optimization
  3. Inspect large posts: kosh cache inspect <path>

​
Stale Content

If builds show old content:
  1. Force rebuild: kosh clean --cache && kosh build
  2. Check mod times: File system times correct?
  3. Verify hashes: kosh cache inspect <path> - ContentHash should change

Build docs developers (and LLMs) love

Get started for freeTalk to us