Transform your Kubernetes CRD YAML files into beautiful, searchable API documentation in seconds.

# Generate docs for all your CRDs
karg --input "./crds/*.yaml" --output-directory ./docs

KARG (Kubernetes API Reference Generator) automatically generates comprehensive markdown documentation from your Custom Resource Definition (CRD) files. Perfect for:

• 📚 API Documentation - Keep your CRD docs always up-to-date
• 🤖 AI/LLM Integration - Generate docs optimized for AI assistants
• 👥 Team Collaboration - Share clear API references with your team
• 🔍 API Discovery - Understand CRD structures at a glance

Using Devbox:

devbox add github:appthrust/karg/v0.4.0#karg

Using Nix:

nix run github:appthrust/karg/v0.4.0#karg -- --help

We strongly recommend installing with a specific version tag (e.g., /v0.6.0) as shown above. This ensures:

• ✅ Reproducible installations
• ✅ Consistent behavior across environments
• ✅ Explicit version control

Note: devbox update does not work with GitHub Flake packages. This is due to the fundamental design of how Devbox integrates with Nix - GitHub Flakes are not registered in Nix profiles and thus cannot be updated via nix profile upgrade. This is a known limitation.

If you installed without a version tag:

# ❌ Not recommended - will pin to a specific commit
devbox add github:appthrust/karg#karg

To update, you must manually reinstall:

# Remove the old version
devbox rm github:appthrust/karg#karg
# Clean the cache
rm -rf .devbox
# Install the latest version with a tag
devbox add github:appthrust/karg/v0.7.0#karg
# Restart your shell
exit && devbox shell

# Multiple files - one doc per CRD
karg --input "./crds/*.yaml" --output-directory ./docs
# Single file - all CRDs combined
karg --input "./crds/*.yaml" --output-file ./api-reference.md
# With detailed logging
karg --input "./crds/*.yaml" --output-directory ./docs --verbose

KARG transforms this CRD:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
 name: books.library.example.com
spec:
 group: library.example.com
 versions:
 - name: v1
 schema:
 openAPIV3Schema:
 type: object
 properties:
 spec:
 type: object
 required: ["title", "author", "isbn"]
 properties:
 title:
 type: string
 description: Title of the book
 minLength: 1
 maxLength: 200

Into this beautiful documentation:

Book

Book represents a book in the library catalog

• API version: library.example.com/v1
• Scope: Namespaced
• Plural: books
• Singular: book

Quick Reference

Field path	Type	Required	Description
spec.title	string	✓	Title of the book
spec.author	string	✓	Author of the book
spec.isbn	string	✓	ISBN-13 of the book

Spec

spec.title

Title of the book

• Type: string
• Required
• Constraints
  • Min length: 1
  • Max length: 200

✨ Smart Documentation

• Automatically extracts descriptions, types, and constraints
• Supports nested objects and arrays
• Handles validation rules and default values

🎯 Developer Friendly

• Clean markdown output
• Consistent formatting
• Perfect for GitHub/GitLab wikis

🤖 AI/LLM Optimized

• Structured format for easy parsing
• Complete field information in context
• Copy-paste ready examples

Check out the examples/ directory to see KARG in action:

# Try it yourself
karg --input examples/input.yaml --output-file my-api-docs.md
# View pre-generated examples
ls examples/per-kind-output/

The examples showcase various CRD patterns:

• Simple resources with basic validation
• Complex nested structures
• Arrays and maps
• Custom validation rules
• Status subresources

karg [options]
Options:
 --input <pattern> Glob pattern for CRD YAML files (required)
 --output-directory <dir> Generate one file per CRD
 --output-file <file> Generate a single combined file
 --verbose Enable detailed logging
 --help Show help
 --version Show version
Examples:
 karg --input "./crds/*.yaml" --output-directory ./docs
 karg --input "./manifests/**/*.yaml" --output-file ./api.md
 karg --input config.yaml --output-directory ./output --verbose

🚀 Fast - Built with Bun for blazing fast performance

🔒 Safe - AST-based generation prevents injection attacks

📦 Zero Config - Works out of the box with standard CRDs

🎨 Beautiful Output - Clean, consistent markdown every time

Add to your project's documentation pipeline:

# Using Devbox (recommended to use version tags)
devbox add github:appthrust/karg/v0.6.0#karg
# Using Nix (recommended to use version tags) 
nix profile install github:appthrust/karg/v0.6.0#karg