CLI Commands

Kosh provides a unified command-line interface for building, serving, and managing your static site. All operations are handled through the kosh command.

Core Commands

init

Initialize a new Kosh site with the default directory structure.

kosh init [name]

Arguments:

name (optional) - Name of the directory to create. Defaults to current directory.

Example:

kosh init my-blog
cd my-blog

Created Structure:

my-blog/
├── content/           # Markdown files
├── static/            # Static assets (images, etc.)
├── kosh.yaml          # Site configuration
└── .gitignore

new

Create a new blog post with pre-filled frontmatter.

kosh new <title>

Arguments:

title (required) - Title of the new post. Quotes optional for multi-word titles.

Example:

kosh new "Getting Started with Kosh"

Output:

✅ Created: content/getting-started-with-kosh.md
🔄 Building site with new post...

The command automatically:

Creates a slugified filename from the title
Adds frontmatter with current date
Triggers a build to verify the new post

build

Build the static site with full optimization.

kosh build [flags]

Flags:

--watch

flag

Watch for file changes and rebuild automatically. Keeps the process running and monitors content/, theme files, and configuration for changes.

kosh build --watch

--cpuprofile

string

Write CPU profile to the specified file for performance analysis.

kosh build --cpuprofile cpu.prof

--memprofile

string

Write memory profile to the specified file for performance analysis.

kosh build --memprofile mem.prof

-baseurl

string

Override the base URL from configuration. Useful for deployment to different environments.

kosh build -baseurl https://example.com

-drafts

flag

Include posts marked as draft: true in the build output.

kosh build -drafts

-theme

string

Override the theme specified in configuration.

kosh build -theme docs

Example Usage:

# Production build
kosh build -baseurl https://myblog.com

# Development build with drafts
kosh build -drafts

# Watch mode for local development
kosh build --watch

# Profile a build
kosh build --cpuprofile cpu.prof --memprofile mem.prof

Build Process:

Loads configuration from kosh.yaml
Parses markdown files with frontmatter
Renders HTML using templates
Minifies CSS, JS, and HTML
Compresses images to WebP (if enabled)
Generates sitemap, RSS, search index
Creates PWA manifest and service worker
Outputs to configured outputDir (default: public/)

serve

Start a local preview server.

kosh serve [flags]

Flags:

--dev

flag

Enable development mode with live reload. This mode:

Builds the site before serving
Watches for file changes and rebuilds automatically
Skips PWA generation for faster builds
Auto-detects baseURL as http://localhost:2604 if empty
Enables browser live reload on changes

kosh serve --dev

--host

string

default:"localhost"

Host or IP address to bind the server to.

kosh serve --host 0.0.0.0

--port

string

default:"2604"

Port number to listen on.

kosh serve --port 8080

-drafts

flag

Include draft posts when serving in development mode.

kosh serve --dev -drafts

-baseurl

string

Override base URL from configuration.

kosh serve -baseurl http://192.168.1.100:2604

Example Usage:

# Recommended: Development mode with live reload
kosh serve --dev

# Serve on all interfaces
kosh serve --dev --host 0.0.0.0

# Custom port
kosh serve --dev --port 3000

# Preview with drafts
kosh serve --dev -drafts

# Serve pre-built site (no rebuild or watch)
kosh serve --port 8080

Development Mode Features:

Incremental Builds: Only changed files are rebuilt (typically <100ms)
Live Reload: Browser automatically refreshes on changes
Watched Paths: content/, themes/, static/, kosh.yaml
Fast Iteration: PWA generation skipped for speed

clean

Clean build output and optionally cache.

kosh clean [flags]

Flags:

--cache

flag

Also clean the .kosh-cache/ directory, forcing a full rebuild on next build.

kosh clean --cache

--all

flag

Clean all versions including versioned folders (for documentation sites).

kosh clean --all

Behavior:

Command	Removes	Preserves
`kosh clean`	Root files in `outputDir`	Version folders (v1.0, v2.0, etc.)
`kosh clean --all`	Entire `outputDir`	Nothing
`kosh clean --cache`	Root files + `.kosh-cache/`	Version folders
`kosh clean --all --cache`	Everything	Nothing

Example Usage:

# Clean output, keep cache
kosh clean

# Force full rebuild
kosh clean --cache

# Clean everything including all versions
kosh clean --all --cache

Note: After cleaning, the build will automatically run to regenerate the site.

cache

Manage the BoltDB cache for incremental builds.

kosh cache <subcommand> [flags]

Subcommands:

cache stats

Show cache statistics and performance metrics.

kosh cache stats

Output Example:

Cache Statistics:
  Total Posts: 142
  Cache Size: 8.4 MB
  Hit Rate: 94.2%
  Cache Version: 5

cache gc

Run garbage collection to remove orphaned cache entries.

kosh cache gc [flags]

--dry-run

flag

Show what would be deleted without actually deleting.

kosh cache gc --dry-run

-n

flag

Alias for --dry-run.

Example:

# Preview what would be cleaned
kosh cache gc --dry-run

# Actually clean orphaned entries
kosh cache gc

cache verify

Check cache integrity and detect corruption.

kosh cache verify

Output:

Lists any corrupted or missing cache entries
Reports hash mismatches
Suggests cleanup actions

cache rebuild

Clear the cache and trigger a full rebuild.

kosh cache rebuild

Equivalent to:

kosh clean --cache

cache clear

Delete all cache data without rebuilding.

kosh cache clear

Warning: This requires manual rebuild afterward:

kosh cache clear
kosh build

cache inspect

Show detailed cache entry for a specific file.

kosh cache inspect <path>

Example:

kosh cache inspect content/my-post.md

Output:

{
  "path": "content/my-post.md",
  "hash": "blake3:a1b2c3...",
  "cached_at": "2026-03-01T10:23:45Z",
  "size": 4821,
  "html_inline": true
}

version

Manage documentation versions and show build information.

kosh version [subcommand]

Subcommands:

version (no args)

Show current documentation version info from kosh.yaml.

kosh version

Output:

Current Version: v4.0 (latest)
All Versions:
  - v4.0 (latest)
  - v3.0
  - v2.0
  - v1.0

version <name>

Freeze the current latest version and start a new version.

kosh version <vX.X>

Example:

kosh version v5.0

Actions:

Creates snapshot of current content in content/v4.0/
Updates kosh.yaml with new version entry
Marks v5.0 as isLatest: true
Rebuilds site with new version structure

version —info

Show Kosh build information and optimizations.

kosh version --info

Output:

Kosh Static Site Generator
Version: v1.2.1
Go Version: go1.23.5
Build Date: 2026-02-16

Optimized with:
  - BLAKE3 hashing (replaced MD5)
  - Object pooling for memory management
  - Pre-computed search indexes
  - Generic cache operations

Global Flags

These flags work with the build and serve commands:

Flag	Type	Description
`-baseurl <url>`	string	Override base URL from config
`-drafts`	flag	Include draft posts
`-theme <name>`	string	Override theme from config

Graceful Shutdown

All long-running commands (serve --dev, build --watch) support graceful shutdown:

Press Ctrl+C to trigger shutdown
The process waits up to 5 seconds for cleanup
Cache is safely closed
Temporary files are removed

Exit Codes

Code	Meaning
0	Success
1	Build error, invalid command, or missing arguments

Common Usage Patterns

Local Development Workflow

# Start development server
kosh serve --dev

# In another terminal, create new posts
kosh new "My New Post"

Production Build for GitHub Pages

kosh build -baseurl https://username.github.io/repo

Debugging Build Issues

# Force full rebuild
kosh clean --cache

# Check cache integrity
kosh cache verify

# Profile a slow build
kosh build --cpuprofile cpu.prof
go tool pprof cpu.prof

Working with Versioned Docs

# Create new major version
kosh version v5.0

# Clean only latest, preserve old versions
kosh clean

# Clean everything including all versions
kosh clean --all

Command Aliases

Alias	Command
`kosh help`	Show usage information
`kosh --help`	Show usage information
`kosh -help`	Show usage information
`kosh --version`	Show build info (same as `version --info`)
`kosh -version`	Show build info (same as `version --info`)

Get Started

Core Concepts

Usage

Features

Development

CLI Commands

CLI Commands

Core Commands

init

new

build

serve

clean

cache

cache stats

cache gc

cache verify

cache rebuild

cache clear

cache inspect

version

version (no args)

version <name>

version —info

Global Flags

Graceful Shutdown

Exit Codes

Local Development Workflow

Production Build for GitHub Pages

Debugging Build Issues

Working with Versioned Docs

Command Aliases

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage

Features

Development

​CLI Commands

​Core Commands

​init

​new

​build

​serve

​clean

​cache

​cache stats

​cache gc

​cache verify

​cache rebuild

​cache clear

​cache inspect

​version

​version (no args)

​version <name>

​version —info

​Global Flags

​Graceful Shutdown

​Exit Codes

​Local Development Workflow

​Production Build for GitHub Pages

​Debugging Build Issues

​Working with Versioned Docs

​Command Aliases

Build docs developers (and LLMs) love

CLI Commands

Core Commands

init

new

build

serve

clean

cache

cache stats

cache gc

cache verify

cache rebuild

cache clear

cache inspect

version

version (no args)

version <name>

version —info

Global Flags

Graceful Shutdown

Exit Codes

Local Development Workflow

Production Build for GitHub Pages

Debugging Build Issues

Working with Versioned Docs

Command Aliases