π Documentation-driven CLI generator for Cobra based Go applications
Adder generates type-safe CLI commands from markdown documentation, providing a clean separation between command structure and business logic.
- π Documentation-First - Commands defined in readable markdown
- π Type-Safe - Compile-time validation and structured requests
- ποΈ Clean Architecture - Separation of CLI structure and business logic
- β‘ Performance - No runtime parsing overhead
- π― Handler Interfaces - Easy testing and dependency injection
- π Organized Output - Preserves directory structure to avoid naming conflicts
- β Enhanced Validation - Markdown linter with strict type checking and enum validation
- π Request Interface - All generated requests implement
adder.Requestfor consistency - π‘οΈ Centralized Enum Validation - Clean
adder.ValidateEnum()function for runtime validation - π§ͺ Comprehensive Testing - Unit, integration, golden file, and example tests
- π Production Ready - Full CI/CD pipeline with automated releases
- π§ Self-Dogfooding - Adder generates its own CLI commands
Via Go Install:
go install github.com/jrschumacher/adder/cmd/adder@latestVia GitHub Releases:
# Download binary for your platform from:
# https://github.com/jrschumacher/adder/releasesCreate .adder.yaml:
binary_name: myapp # Required: name of your CLI binary
input: docs/commands # Default: docs/commands
output: generated # Default: generated
package: generated # Default: generated
suffix: _generated.go # Default: _generated.go
package_strategy: directory # Default: directory
index_format: directory # Default: directoryCreate docs/commands/hello.md:
---
title: Say hello to someone
command:
name: hello [name]
arguments:
- name: name
description: Name of the person to greet
required: true
type: string
flags:
- name: capitalize
description: Capitalize the greeting
type: bool
---
# Say hello to someone
Greet someone with a friendly hello message.adder generate
# Or with flags: adder generate -i docs/commands -o generated -p generatedfunc (h *HelloHandler) HandleHello(cmd *cobra.Command, req *generated.HelloRequest) error {
greeting := fmt.Sprintf("Hello, %s!", req.Arguments.Name)
if req.Flags.Capitalize {
greeting = strings.ToUpper(greeting)
}
fmt.Println(greeting)
return nil
}handler := &HelloHandler{}
helloCmd := generated.NewHelloCommand(handler)
rootCmd.AddCommand(helloCmd)Adder creates clean, type-safe structures:
// Separate arguments from flags for clarity
type HelloRequestArguments struct {
Name string `json:"name" validate:"required"`
}
type HelloRequestFlags struct {
Capitalize bool `json:"capitalize"`
Style string `json:"style" validate:"oneof=normal bold italic"`
}
// All requests implement adder.Request interface
type HelloRequest struct {
Arguments HelloRequestArguments `json:"arguments"`
Flags HelloRequestFlags `json:"flags"`
RawArguments []string `json:"raw_arguments"`
}
// GetRawArguments implements adder.Request interface
func (r *HelloRequest) GetRawArguments() []string {
return r.RawArguments
}
// Handler receives full command access
type HelloHandler func(cmd *cobra.Command, req *HelloRequest) error
// Clean enum validation in generated code
if err := adder.ValidateEnum("style", style, []string{"normal", "bold", "italic"}); err != nil {
return err
}Adder preserves your documentation structure:
docs/man/ generated/
βββ auth/ βββ auth/
β βββ login.md β β βββ login_generated.go
βββ policy/ βββ policy/
βββ create.md β βββ create_generated.go
This prevents naming conflicts between commands like auth create and policy create.
Create .adder.yaml in your project root:
# Required: Name of your CLI binary (used to detect root command)
binary_name: myapp
# Optional: Input/output directories (can be overridden with flags)
input: docs/commands
output: generated
package: generated
suffix: _generated.go
# Optional: Package naming strategy
package_strategy: directory # single, directory, path
# Optional: Index file format for subcommands
index_format: directory # directory, index, _index, hugoRoot Command Detection:
- The parser looks for
{binary_name}.mdin the input directory - This file becomes your CLI's root command
- Example:
binary_name: myappβ looks formyapp.md
Adder acts as a comprehensive markdown linter, catching configuration errors early:
# β This will fail validation
flags:
- name: count
type: int
default: "not-a-number" # Error: must be integer for type 'int'
# β
This is correct
flags:
- name: count
type: int
default: 42# β This will fail validation
flags:
- name: level
type: int # Error: enum only supported on string type
enum: ["debug", "info"]
# β This will also fail
flags:
- name: level
type: string
enum: ["debug", "info"]
default: "invalid" # Error: default must be in enum values
# β
This is correct
flags:
- name: level
type: string
enum: ["debug", "info", "warn"]
default: "info"# Validate without generating
adder generate --validate
# Example validation errors
β Validation failed: flag count: default value must be an integer for type 'int', got 'not-a-number'
β Validation failed: flag level: enum validation only supported on string type, got 'int'
β Validation failed: flag level: default value 'invalid' must be one of: [debug info warn]| Feature | Benefit |
|---|---|
| Type Safety | Compile-time validation prevents runtime errors |
| Documentation-First | Single source of truth in readable format |
| Performance | No runtime parsing of embedded docs |
| Clean Architecture | Handler interfaces promote testability |
| Organized Output | Directory structure prevents naming conflicts |
| Command Access | Full *cobra.Command capabilities available |
Adder is built with production use in mind:
- 19 Active Linters - golangci-lint with comprehensive checks
- 4 Test Categories - Unit, integration, golden file, and example tests
- 90%+ Test Coverage - Comprehensive test suite
- Automated Quality Gates - CI/CD pipeline enforces standards
- Multi-Platform Support - Linux, macOS, Windows (AMD64 + ARM64)
- Semantic Versioning - Automated releases with conventional commits
- Backward Compatibility - Careful API evolution
- Self-Dogfooding - Tool generates its own CLI commands
- Comprehensive Documentation - Examples, guides, and API reference
- Local Development Tools - Makefile with all common tasks
- IDE Integration - Works with any Go-compatible editor
Adder includes comprehensive testing:
# Run all tests
make test
# Run with coverage
make test-coverage
# Run linting
make lint
# Run all CI checks locally
make ci-testTest Categories:
- Unit Tests - Core parser and generator logic
- Integration Tests - CLI command testing
- Golden File Tests - Generated code validation
- Example Tests - Handler testing patterns
- Complete Example - Working hello world demo
- Testing Guide - Comprehensive testing patterns
- GitHub Workflows - CI/CD pipeline documentation
- API Reference - Full documentation
Local Development:
# Build the CLI
make build
# Build for all platforms (uses GitHub Actions)
make build-all
# Generate example commands
make generate-example
# Self-generate CLI commands (dogfooding)
make generate-self$ hello-example hello "Adder" --capitalize
HELLO, ADDER!
$ adder generate --input docs/man --output generated --package generated
π Generating CLI commands from docs/man to generated...
π Validating documentation...
β
Code generation completed!
π Generated 3 commands with 5 flags and 2 argumentsAdder uses automated releases with release-please and GoReleaser:
- Merge to main triggers release PR creation
- Merge release PR creates GitHub release
- GoReleaser automatically builds and publishes multi-platform binaries
Use conventional commits for automatic versioning:
feat:β minor version bumpfix:β patch version bumpBREAKING CHANGE:β major version bump
We welcome contributions!
Getting Started:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run
make ci-testto validate - Submit a pull request
Code Quality:
- All tests must pass
- golangci-lint must pass
- Include tests for new features
- Update documentation as needed
MIT License - see LICENSE file for details.