dynamic-cli

A powerful Rust framework for creating configurable CLI and REPL applications via YAML/JSON files.

Define your command-line interface in a configuration file, not in code. ✨

English | Français

🎯 Features

📝 Configuration-Driven : Define commands, arguments and options in YAML/JSON
🔄 CLI, REPL & Batch Modes : Command-line, interactive, and scripted batch execution
✅ Automatic Validation : Built-in type checking and constraint validation
🎨 Rich Error Messages : Colorful and informative messages with suggestions
🔌 Plugin System : Granular static plugins (help, version, exit, sysinfo, env, config — compose only what you need) and sandboxed WASM plugins (loaded at runtime)
📚 Well Documented : Complete API documentation and examples
🧪 Thoroughly Tested : Extensive test coverage
⚡ Performance : Zero-cost abstractions with efficient parsing

🚀 Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
dynamic-cli = "0.7.0"

# Optional — sandboxed WASM plugins (see Plugin System below)
# dynamic-cli = { version = "0.7.0", features = ["wasm-plugins"] }

Basic Example

1. Create a configuration file (commands.yaml):

metadata:
  version: "1.0.0"
  prompt: "myapp"
  prompt_suffix: " > "

commands:
  - name: greet
    aliases: [hello, hi]
    description: "Greet someone"
    required: false
    arguments:
      - name: name
        arg_type: string
        required: true
        description: "Name to greet"
        validation: []
    options:
      - name: loud
        short: l
        long: loud
        option_type: bool
        required: false
        description: "Use uppercase"
        choices: []
    implementation: "greet_handler"

global_options: []

Note :

The proper syntax for the configuration file is available in the project repository.

2. Implement your command handlers:

use dynamic_cli::prelude::*;

// Define your application context
#[derive(Default)]
struct MyContext {
    // Your application state
}

impl ExecutionContext for MyContext {
    fn as_any(&self) -> &dyn std::any::Any { self }
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
}

// Implement the command handler
struct GreetCommand;

impl CommandHandler for GreetCommand {
    fn execute(
        &self,
        _context: &mut dyn ExecutionContext,
        args: &ParsedArgs,
    ) -> dynamic_cli::Result<()> {
        let name = args.get_scalar("name").unwrap();
        let loud = args.get_scalar("loud").map(|v| v == "true").unwrap_or(false);
        
        let greeting = format!("Hello, {}!", name);
        println!("{}", if loud { greeting.to_uppercase() } else { greeting });
        
        Ok(())
    }
}

fn main() -> dynamic_cli::Result<()> {
    CliBuilder::new()
        .config_file("commands.yaml")
        .context(Box::new(MyContext::default()))
        .register_sync_handler("greet_handler", Box::new(GreetCommand))
        .build()?
        .run()
}

3. Run your application:

# CLI mode
$ myapp greet Alice
Hello, Alice!

$ myapp greet Bob --loud
HELLO, BOB!

# REPL mode
$ myapp
myapp > greet Alice
Hello, Alice!
myapp > help
Available commands:
  greet [name] - Greet someone
myapp > exit

Batch mode — run a whole file of commands, one per line (blank lines and #-prefixed comments are skipped):

let outcome = app.run_script("commands.txt", ScriptErrorPolicy::Continue)?;
println!("{}/{} succeeded", outcome.lines_succeeded, outcome.lines_executed);

The same file can also be loaded from inside an already-running REPL session with :load commands.txt.

🔌 Plugin System

Extend an application with handlers that do not live in your own crate, without modifying dynamic-cli itself. Two mechanisms are available:

Mechanism	When to use it	Cost
Static plugins (`Plugin` trait)	Compiled into your binary	No `unsafe`, no extra dependency
WASM plugins (`WasmPlugin`)	Distributed and loaded independently, sandboxed	`wasmtime` dependency, opt-in via `features = ["wasm-plugins"]`

dynamic-cli ships SystemPlugin out of the box — help, version, and exit in one call:

use dynamic_cli::plugin::SystemPlugin;

CliBuilder::new()
    .config_file("commands.yaml")
    .context(Box::new(MyContext::default()))
    .register_plugin(Box::new(SystemPlugin::new()))
    .register_sync_handler("greet_handler", Box::new(GreetCommand))
    .build()?
    .run()

Each of help/version/exit is also available as its own independent plugin (HelpPlugin, VersionPlugin, ExitPlugin) — register only the one you need instead of the bundle. Three more, feature-gated, cover common introspection needs: SysInfoPlugin (sysinfo-plugin, OS/architecture/ parallelism), EnvPlugin (env-plugin, filtered environment variables — sensitive-looking ones hidden by default), and ConfigPlugin (config-plugin, show/re-validate the loaded YAML config without restarting):

use dynamic_cli::plugin::{ConfigPlugin, SysInfoPlugin};

CliBuilder::new()
    .config_file("commands.yaml")
    .context(Box::new(MyContext::default()))
    .register_plugin(Box::new(SysInfoPlugin::new()))
    .register_plugin(Box::new(ConfigPlugin::new().with_config(config)))
    .build()?
    .run()

WASM plugins run in a wasmtime sandbox, with no unsafe code on the host side:

CliBuilder::new()
    .config_file("commands.yaml")
    .context(Box::new(MyContext::default()))
    .register_wasm_plugin(
        Path::new("plugins/greet.wasm"),
        &[("greet_hello", "say_hello")],
    )?
    .build()?
    .run()

Static and WASM plugins, and directly-registered handlers, all coexist in the same application — the YAML configuration remains the single source of truth for command definitions either way.

Full Plugin Guide → (Français) — the complete WASM ABI contract for third-party plugin authors, a worked example, and the architecture decision behind it (DD-021).

📖 Documentation

API Reference - Complete API documentation
Examples - Working examples and code samples
Contributing Guide - How to contribute to the project

🎓 Examples

The examples directory contains complete examples:

simple_calculator.rs - Basic arithmetic calculator
rpn_calculator.rs - Reverse Polish Notation calculator
advanced_rpn_calculator.rs - HP-41CX-flavored RPN calculator with scientific functions, memory registers, SysInfoPlugin/ConfigPlugin, and batch/:load execution
file_manager.rs - File operations with validation
task_runner.rs - Task management application
async_token_demo.rs - Async command handler demo

Run any example:

cargo run --example simple_calculator

# advanced_rpn_calculator needs its two feature flags:
cargo run --example advanced_rpn_calculator --features sysinfo-plugin,config-plugin

🏗 Architecture

dynamic-cli is organized into focused modules:

config - Configuration loading and validation
context - Execution context trait
executor - Command execution engine
registry - Command and handler registry
parser - CLI and REPL argument parsing
validator - Argument validation
interface - CLI and REPL interfaces
error - Error types and display
builder - Fluent API for building applications
help - Dynamic --help generation
plugin - Granular static plugins (plugin::builtin: help, version, exit, sysinfo, env, config) and sandboxed WASM (wasm-plugins feature) extension mechanisms

🧪 Tests

# Run all tests (default features)
cargo test

# Run all tests, across every feature flag
cargo test --all-features

# Run with coverage
cargo llvm-cov --all-targets --all-features --workspace

# Check code quality
cargo clippy --all-features -- -D warnings

Current test statistics:

500+ unit tests ✅
230+ documentation tests
12 integration tests (static + WASM plugins, full public API chain)
80-90% code coverage (not re-measured for v0.7.0 — cargo-llvm-cov wasn't run this sprint)
Zero clippy warnings, confirmed across --all-features (wasm-plugins, sysinfo-plugin, env-plugin, config-plugin combined)

🤝 Contributing

We welcome contributions from everyone! Here's how you can help:

Ways to Contribute

🐛 Report bugs - Found a bug? Open an issue
💡 Suggest features - Have an idea? Start a discussion
📝 Improve documentation - Fix typos, clarify, add examples
🔧 Submit code - Fix bugs, implement features, improve performance
🧪 Add tests - Increase coverage, add edge cases

Getting Started

# Fork and clone
git clone https://github.com/biface/dcli.git
cd dynamic-cli

# Create a branch
git checkout -b feature/my-feature

# Make your changes and test
cargo test --all-features
cargo clippy --all-features

# Commit and push
git commit -am "Add awesome feature"
git push origin feature/my-feature

Development Guidelines

Before submitting a pull request:

Code follows Rust style guidelines (cargo fmt)
All tests pass (cargo test --all-features)
No clippy warnings (cargo clippy --all-features -- -D warnings)
Documentation is updated
New tests added for new features
Commit messages are clear and descriptive

Code of Conduct

This project follows a Code of Conduct to ensure a welcoming environment:

✅ Be respectful to others
✅ Welcome newcomers and help them learn
✅ Constructive criticism helps us move forward and improve—let's embrace it
✅ Focus on what's best for the community
❌ No harassment, trolling or personal attacks

Read the complete contributing guide →

📜 License

Licensed under your choice of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Contribution Licensing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

🙏 Acknowledgments

Rust Community - For the amazing tools and libraries developed
Contributors - Everyone who has contributed to this project
clap - Inspiration for CLI design
rustyline - REPL functionality
serde - Serialization support

📞 Support

Need help?

📖 Check the API documentation
💬 Open a discussion
🐛 Report an issue
📧 Contact the maintainers

Found a security vulnerability?
Please report it privately to the maintainers.

🌟 Show Your Support

If you find dynamic-cli useful, please:

⭐ Star the repository on GitHub
📢 Share it with others who might find it useful
📝 Write a blog post or tutorial!

Last updated: 2026-08-23

dynamic-cli 0.7.0