Skip to main content

​
Overview

The kosh clean command removes generated files from your output directory. It supports version-aware cleaning to preserve frozen documentation versions and can optionally clear the build cache.

​
Usage

kosh clean [flags]

​
Flags

​
--cache
boolean
default:"false"
Also clean the .kosh-cache/ directory containing the build cache.Use this when you want to force a complete rebuild from scratch.
​
--all
boolean
default:"false"
Clean the entire output directory, including versioned folders.Warning: This removes all frozen documentation versions. Use with caution.

​
Cleaning Modes

​
Default: Root Files Only

By default, kosh clean removes only root-level files and directories while preserving version folders: 
kosh clean
Preserves:
  • Version folders configured in kosh.yaml (e.g., v1.0/, v2.0/)
Removes:
  • Root HTML files
  • tags/ directory
  • static/ directory
  • search.bin
  • All other non-version content

​
Clean All Versions

Removes the entire output directory: 
kosh clean --all
Removes:
  • Everything in the output directory, including all version folders

​
Clean with Cache

Cleans output and cache: 
kosh clean --cache
Removes:
  • Root-level output files (preserves versions)
  • .kosh-cache/ directory

​
Clean Everything

Nuclear option - removes all generated files: 
kosh clean --all --cache
Removes:
  • Entire output directory
  • .kosh-cache/ directory

​
Examples

# Remove root files, keep versions
kosh clean

# Rebuild
kosh build

​
Version-Aware Cleaning

Kosh reads kosh.yaml to identify version folders that should be preserved:
kosh.yaml
versions:
  - name: v3.0
    path: v3.0
    isLatest: true
  - name: v2.0
    path: v2.0
    isLatest: false
  - name: v1.0
    path: v1.0
    isLatest: false
With this config:
  • kosh clean preserves v3.0/, v2.0/, and v1.0/
  • kosh clean --all removes all three version folders

​
No Versions Configured

If no versions are in kosh.yaml, the standard clean removes the entire output directory: 
🧹 No versions configured, cleaning entire public/ directory

​
Output Directory Support

The clean command respects the outputDir setting in kosh.yaml:
kosh.yaml
outputDir: "../build"  # Relative path
# or
outputDir: "/var/www/site"  # Absolute path
Relative paths are resolved from the project root.

​
Async Deletion

Kosh uses an async deletion strategy for fast cleanup:
  1. Rename: Directory renamed to <name>_deleting_<timestamp>
  2. Background Delete: Deletion happens in the background
  3. Immediate Return: Command returns instantly
This allows you to start a rebuild immediately without waiting for deletion to complete.

​
Automatic Rebuild

After cleaning, Kosh automatically triggers a rebuild: 
$ kosh clean
🧹 Cleaning root files (42 items), preserving 3 version folders...
🧹 Clean initiated in 12ms (backgrounding deletion).

🔄 Rebuilding site...
📦 Building assets...

​
Terminal Output

$ kosh clean
🧹 Cleaning root files (42 items), preserving 3 version folders...
🧹 Clean initiated in 12ms (backgrounding deletion).

🔄 Rebuilding site...
📦 Building assets...
📝 Processing content...

​
Error Handling

​
Rename Failure

If async rename fails, falls back to synchronous deletion: 
⚠️ Rename failed (permission denied), deleting synchronously...

​
Config Load Failure

If kosh.yaml can’t be loaded: 
⚠️ Failed to load config, cleaning entire public/ directory

​
Use Cases

​
Template Changes

After major template updates, clean to ensure all pages are regenerated: 
kosh clean
kosh build

​
Debugging Cache Issues

If builds seem incorrect, clear cache: 
kosh clean --cache
kosh build

​
Deploy Preparation

Clean and rebuild for production: 
kosh clean --all --cache
kosh build -baseurl https://mysite.com

​
Version Migration

After removing old versions from config, clean them: 
# Edit kosh.yaml to remove old versions
kosh clean --all
kosh build

Build docs developers (and LLMs) love

Get started for freeTalk to us