yaml2cmd
A crate to build a clap::Command from YAML string at runtime. Define your entire CLI structure declaratively — no repetitive Rust boilerplate required.
Features
- Declarative Configuration — Define your whole CLI in one YAML string.
- Nested Subcommands — Arbitrarily deep command hierarchies.
- Rich Argument Options — Short/long flags, required args, value ranges, actions, defaults, conflicts.
- Hidden Commands — Hide commands from help output.
- Aliases — Multiple aliases per command.
- Automatic Sorting — Commands and subcommands sorted alphabetically for consistent help output.
- Debug-Only Commands — Exclude commands from release builds via
debug_onlyflag. - Runtime YAML — Parse YAML from any source (file, string, network) at runtime.
Installation
Add to your Cargo.toml:
[]
= "0.1"
= { = "4", = ["derive"] }
Quick Start
1. Define your CLI in YAML
# cli.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"
- 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
- 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. Build your CLI in Rust
use Command;
use add_commands_from_yaml;
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 |
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 |
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 |
Safety & Linting
This crate:
- Forbids all unsafe code (
#![forbid(unsafe_code)]) - Passes Clippy with
allwarnings enabled - Requires Rust 1.70 or later
Notes
- String Leaking: The implementation intentionally leaks strings to
&'static strto satisfy clap's lifetime requirements. This is acceptable for CLI tools that run once and exit. - Command Sorting: Commands and subcommands are sorted alphabetically for consistent help output.
- Debug-Only Commands: Use
debug_only: trueto include commands only in debug builds (they are stripped from release builds via#[cfg(not(debug_assertions))]).
License
MIT