yaml2cmd 0.1.2

A crate to build a `clap::Command` from yaml string at runtime.
Documentation

yaml2cmd

Crates.io Docs.rs License: MIT

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_only flag.
  • Runtime YAML — Parse YAML from any source (file, string, network) at runtime.

Installation

Add to your Cargo.toml:

[dependencies]
yaml2cmd = "0.1"
clap = { version = "4", features = ["derive"] }

Quick Start

1. Define your CLI in YAML

# cli.yaml
commands:
  - name: create
    about: "Create a new resource"
    aliases: [new, make]
    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 clap::Command;
use yaml2cmd::add_commands_from_yaml;

fn main() {
    // Load YAML from file, string, or any source
    let yaml_content = std::fs::read_to_string("cli.yaml")
        .expect("Failed to read cli.yaml");

    // Define the head command (root of your CLI)
    let head = Command::new("my-cli")
        .version("1.0.0")
        .about("My awesome CLI tool");

    // Build the full command tree
    let cmd = add_commands_from_yaml(&yaml_content, &head);

    // Parse and execute
    let matches = cmd.get_matches();
    // ... handle the matches
}

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 all warnings enabled
  • Requires Rust 1.70 or later

Notes

  • String Leaking: The implementation intentionally leaks strings to &'static str to 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: true to include commands only in debug builds (they are stripped from release builds via #[cfg(not(debug_assertions))]).

License

MIT