7000pctAUTO/cli-spec-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Add README, LICENSE, package.json, and CHANGELOG

Browse Source
This commit is contained in:
7000pctAUTO
2026-01-30 07:06:06 +00:00
parent 70d45aa1fa
commit ec9caa6283
1 changed files with 338 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

340
README.md
View File

@@ -1,3 +1,339 @@
# cli-spec-generator # CLI Spec Generator
A CLI tool that generates consistent argument parsers, shell completions, and man pages from YAML/JSON specifications [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
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
```bash
npm install -g cli-spec-generator
```
### Using npx
```bash
npx cli-spec-generator <command>
```
### From Source
```bash
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:
```yaml
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:
```bash
cli-spec-gen all my-cli.yaml -o generated/
```
### 3. Generate Shell Completions
```bash
cli-spec-gen completion my-cli.yaml --all -o generated/
```
### 4. Generate Documentation
```bash
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
```yaml
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:
```yaml
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
```yaml
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
```yaml
arguments:
- name: input # Argument name (required)
description: Input file path
required: true # Default is true
variadic: false # Accept multiple values
```
### Examples
```yaml
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
```bash
cli-spec-gen generate my-cli.yaml -l python
```
### Generate All Shell Completions
```bash
cli-spec-gen completion my-cli.yaml --all
```
### Generate Specific Shell Completion
```bash
cli-spec-gen completion my-cli.yaml -s zsh
```
### Interactive Spec Creation
```bash
cli-spec-gen init -o my-cli.yaml
```
### Validate a Spec
```bash
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
```typescript
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
```bash
# 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
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Watch mode
npm run test:watch
```
## Versioning
This project uses [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](./CHANGELOG.md) for version history.
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
## Support
- Create an [issue](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/issues) for bugs
- Start a [discussion](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/discussions) for questions
- Read the [wiki](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/wiki) for documentation