yaml2cmd-build
A build-time code generator that transforms YAML CLI definitions into Rust source code for clap::Command. Unlike runtime parsing, this approach generates compile-time checked code with zero runtime overhead.
Features
- Compile-Time Generation — Generates Rust code during build, not runtime parsing.
- Type-Safe Value Parsers — Supports
value_parser!macro for compile-time type checking. - Nested Subcommands — Arbitrarily deep command hierarchies.
- Rich Argument Options — Short/long flags, required args, value ranges, actions, defaults, conflicts.
- Argument Groups — Enforce mutual exclusivity with
ArgGroup. - Hidden Commands — Hide commands from help output.
- Aliases — Multiple aliases per command.
- Automatic Sorting — Commands and subcommands sorted alphabetically.
- Debug-Only Commands — Exclude commands from release builds.
- Incremental Builds — Only rewrites generated file when content changes.
Installation
Add to your Cargo.toml:
[]
= { = "0.1", = "../yaml2cmd" }
[]
= "0.1"
Quick Start
1. Define your CLI in YAML
# commands.yaml
commands:
- name: create
about: "Create a new resource"
aliases:
args:
- name: name
short: n
long: name
help: "Name of the resource"
required: true
value_name: "NAME"
value_parser: "String"
- name: count
short: c
long: count
help: "Number of items"
value_parser: "u32"
default_value: "1"
- name: verbose
short: v
long: verbose
help: "Enable verbose output"
action: "set_true"
- name: tags
long: tags
help: "Add tags to the resource"
num_args: "1.."
action: "append"
subcommands:
- name: file
about: "Create a file resource"
args:
- name: path
long: path
help: "File path"
required: true
value_parser: "PathBuf"
- name: directory
about: "Create a directory resource"
- name: delete
about: "Delete a resource"
hidden: true
args:
- name: force
short: f
long: force
help: "Force deletion without confirmation"
action: "set_true"
- name: debug-info
about: "Print debug information"
debug_only: true
2. Create build script
// build.rs
3. Use in your main crate
// src/main.rs
use Command;
include!;
YAML Schema Reference
CommandDef
| Field | Type | Description |
|---|---|---|
name |
String |
Command name (required) |
about |
String |
Short description shown in help |
args |
Vec<ArgDef> |
List of arguments |
hidden |
bool |
Hide from help output |
subcommands |
Vec<CommandDef> |
Nested subcommands |
multiple_values |
bool |
Allow multiple values (creates ArgGroup) |
debug_only |
bool |
Only include in debug builds |
aliases |
Vec<String> |
Alternative names |
ArgDef
| Field | Type | Description |
|---|---|---|
name |
String |
Argument identifier (required) |
short |
char |
Short flag (e.g., -v) |
long |
String |
Long flag (e.g., --verbose) |
help |
String |
Help text |
value_name |
String |
Placeholder for the value |
required |
bool |
Mandatory argument |
num_args |
String |
Number of values accepted |
action |
String |
Action to perform |
default_value |
String |
Default value |
conflicts_with |
String |
Name of an incompatible argument |
value_parser |
String |
Rust type for value parsing (e.g., "u32", "String", "PathBuf") |
Supported num_args Values
| Value | Meaning |
|---|---|
"0.." |
Zero or more |
"1.." |
One or more |
"0..1" |
Zero or one |
"0..=" |
Zero to usize::MAX |
"N" |
Exactly N (e.g., "3") |
Supported action Values
| Value | Clap Action |
|---|---|
"set_true" |
ArgAction::SetTrue |
"set_false" |
ArgAction::SetFalse |
"append" |
ArgAction::Append |
"count" |
ArgAction::Count |
| (default) | ArgAction::Set |
How It Works
- Build Script —
build.rsreads the YAML file and callsbuild_with_yaml(). - Code Generation — Generates Rust source code into
$OUT_DIR/command.rs. - Compile-Time Check — The generated code is compiled with your crate, catching errors early.
- Incremental Builds — Only rewrites the file when content changes, avoiding unnecessary recompilation.
Generated Code Example
use ;
Safety & Linting
This crate:
- Forbids all unsafe code (
#![forbid(unsafe_code)]) - Passes Clippy with
allandpedanticwarnings enabled - Requires Rust 1.70 or later
License
MIT