cli-spec-generator/README.md

CLI Spec Generator

A powerful CLI tool that generates consistent argument parsers, shell completions, and man pages from a simple YAML/JSON specification file. Define your CLI interface once in a declarative format, and automatically generate code for multiple languages.

Features

• Multi-Language Code Generation: Python argparse, Go flag, Rust clap, Node.js commander/yargs
• Shell Completions: Auto-generate completions for Bash, Zsh, and Fish
• Documentation: Generate man pages and README documentation
• Interactive Wizard: Create specs interactively with the built-in wizard
• Validation: Catch errors early with built-in spec validation
• Type Safety: Written in TypeScript with full type definitions

Installation

Global Installation

npm install -g cli-spec-generator

Using npx

npx cli-spec-generator <command>

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator.git
cd cli-spec-generator
npm install
npm run build
npm link

Quick Start

1. Create a Specification File

Create a file named my-cli.yaml with your CLI definition:

name: my-cli
version: 1.0.0
description: My awesome CLI tool
author: John Doe
bin: my-cli

globalOptions:
  - name: verbose
    short: v
    description: Enable verbose output
    type: boolean
    default: false

commands:
  - name: start
    description: Start the service
    options:
      - name: port
        short: p
        description: Port number
        type: number
        default: 8080
    arguments:
      - name: service
        description: Service name
        required: true

2. Generate Code

Generate code for all supported languages:

cli-spec-gen all my-cli.yaml -o generated/

3. Generate Shell Completions

cli-spec-gen completion my-cli.yaml --all -o generated/

4. Generate Documentation

cli-spec-gen docs my-cli.yaml -o generated/

Command Reference

Command	Alias	Description
generate <file>	gen	Generate code from a spec
completion <file>	comp	Generate shell completions
docs <file>	-	Generate man page and README
init	new	Interactive spec wizard
validate <file>	check	Validate a spec file
all <file>	-	Generate everything

Global Options

Option	Description
-l, --language	Target language for code generation
-o, --output	Output directory
-s, --shell	Target shell for completions
--all	Generate for all languages/shells
--help	Show help
--version	Show version

Specification Format

Basic Structure

name: cli-name           # CLI name (kebab-case, required)
version: 1.0.0           # Semantic version (required)
description: Description # Brief description (required)
author: Name             # Optional author name
license: MIT             # Optional license identifier
bin: cli-name           # Binary name (defaults to name)

Global Options

Options available to all commands:

globalOptions:
  - name: verbose        # Long flag name (required)
    short: v            # Optional short flag
    description: Enable verbose output
    type: string        # string, number, boolean, array
    required: false     # Whether option is required
    default: value      # Default value
    choices: [a, b, c]  # Allowed values

Commands

commands:
  - name: start          # Command name (required)
    description: Start the service
    options:             # Command-specific options
      - name: port
        type: number
    arguments:           # Positional arguments
      - name: service
        required: true
    subcommands:         # Nested subcommands
      - name: child
        description: Child command

Arguments

arguments:
  - name: input          # Argument name (required)
    description: Input file path
    required: true       # Default is true
    variadic: false      # Accept multiple values

Examples

examples:
  - description: Start the server
    command: my-cli start api-server
    output: "Server started on port 8080"

Supported Languages

Language	Library	Extension
Python	argparse	.py
Go	flag	.go
Rust	clap	.rs
Node.js	commander	.js
Node.js	yargs	.js

Shell Completions

Shell	File	Install
Bash	_cli-name.bash	source _cli-name.bash
Zsh	_cli-name.zsh	~/.zsh/completion/
Fish	_cli-name.fish	~/.config/fish/completions/

Examples

Generate Python Code Only

cli-spec-gen generate my-cli.yaml -l python

Generate All Shell Completions

cli-spec-gen completion my-cli.yaml --all

Generate Specific Shell Completion

cli-spec-gen completion my-cli.yaml -s zsh

Interactive Spec Creation

cli-spec-gen init -o my-cli.yaml

Validate a Spec

cli-spec-gen validate my-cli.yaml

Generated Output Structure

output/
├── python/
│   └── my-cli.py
├── go/
│   └── my-cli.go
├── rust/
│   └── my-cli.rs
├── node-commander/
│   └── my-cli.js
├── node-yargs/
│   └── my-cli.js
├── completions/
│   ├── _my-cli.bash
│   ├── _my-cli.zsh
│   └── _my-cli.fish
└── docs/
    ├── my-cli.1
    └── CLI_DOCS.md

API Usage

Programmatic Usage

import { generateAll } from 'cli-spec-generator';

const spec = await parseSpec('my-cli.yaml');
await generateAll(spec, { output: './generated' });

Available Functions

• parseSpec(filePath): Parse a YAML/JSON spec file
• generateCode(spec, language): Generate code for a specific language
• generateCompletions(spec, shell): Generate completions for a shell
• generateDocs(spec): Generate documentation
• validateSpec(spec): Validate a spec file
• runWizard(): Run interactive spec wizard

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -am 'Add my feature'
4. Push to branch: git push origin feature/my-feature
5. Submit a Pull Request

Development Setup

# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator.git
cd cli-spec-generator

# Install dependencies
npm install

# Run development build
npm run dev

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

Adding New Templates

1. Create a Handlebars template in src/templates/
2. Add the template to the appropriate generator
3. Update the language/shell mappings
4. Add tests

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Versioning

This project uses Semantic Versioning. See CHANGELOG.md for version history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Create an issue for bugs
• Start a discussion for questions
• Read the wiki for documentation