Expand description
clap-noun-verb - A framework for building composable CLI patterns
This crate provides a high-level, ergonomic API for building noun-verb CLI patterns on top of clap, similar to how Python’s Typer provides a simpler interface over Click.
§Minimal Dependencies
By default, clap-noun-verb compiles with only 10 core dependencies for basic CLI:
clap- CLI frameworkclap-noun-verb-macros- Our proc macroslinkme- Auto-discoveryserde,serde_json- JSON outputthiserror,anyhow- Error handlingonce_cell,lazy_static,atty- Utilities
All advanced features are opt-in via cargo features:
process-data- Data processing operatorsautonomic- Agent introspection & telemetry spans (impliesprocess-data)contrib- Community-contributed verbs (impliesprocess-data)repl- Interactive REPL mode (rustyline)federated-network- Federated node discovery
§Version 26.6.13 Architecture
- Attribute Macros (
clap-noun-verb-macros) -#[verb]for declarative command registration - Auto-Discovery - Commands automatically discovered using
linkmedistributed slices - Type Inference - Arguments automatically inferred from function signatures
- JSON Output - All output automatically serialized to JSON
§Key Principles
- Zero Boilerplate - Just add
#[verb]attributes to functions - Auto-Discovery - Commands automatically discovered at compile time
- Type Inference - Arguments inferred from function signatures
- JSON by Default - Perfect for agents, MCP, and modern tooling
- Minimal Dependencies - Core CLI needs only 9 crates
§API Stability
This crate follows Semantic Versioning. Version 26.6.13 provides:
- Public APIs are stable within the same major version
- Breaking changes only in major version bumps
- Feature flags are stable - won’t be removed without deprecation
Re-exports§
pub use cli::run;pub use builder::build_cli;pub use builder::run_cli;pub use builder::run_cli_with_args;pub use builder::CliBuilder;pub use error::ActionTemplate;pub use error::ErrorKind;pub use error::NounVerbError;pub use error::Result;pub use error::Severity;pub use error::StructuredError;pub use noun::CompoundNounCommand;pub use noun::NounCommand;pub use noun::NounContext;pub use registry::CommandRegistry;pub use tree::CommandTree;pub use tree::CommandTreeBuilder;pub use verb::VerbArgs;pub use verb::VerbCommand;pub use verb::VerbContext;pub use policies::GitPhaseDirtyPolicy;pub use policies::PolicyEvent;pub use policies::PolicyMode;pub use policies::PolicySet;pub use policies::PolicyVerdict;pub use policies::TargetPressurePolicy;pub use policies::ToolchainMismatchPolicy;pub use policies::TrybuildChangedPolicy;pub use context::AppContext;pub use deprecation::Deprecation;pub use deprecation::DeprecationType;pub use format::clear_output_validation_hooks;pub use format::format_output;pub use format::register_output_validation_hook;pub use format::OutputFormat;pub use format::OutputValidationHook;pub use validators::validate_email;pub use validators::validate_ipv4;pub use validators::validate_ipv6;pub use validators::validate_length;pub use validators::validate_not_empty;pub use validators::validate_path_creatable;pub use validators::validate_path_exists;pub use validators::validate_port;pub use validators::validate_regex;pub use validators::validate_url;pub use graph::Graph;pub use graph::GraphLoadedOutput;pub use graph::QueryResultOutput;pub use graph::Triple;pub use graph::ValidationResultOutput;pub use capability::CapabilityPackage;pub use capability::CapabilityRegistry;pub use capability::PackAddedOutput;pub use capability::PackRemovedOutput;pub use diagnostics::DoctorOutput;pub use diagnostics::HealthIssue;pub use repl::Repl;pub use builder::CliBuilder as Cli;pub use registry::CommandRegistry as Registry;pub use tree::CommandTree as Tree;
Modules§
- async_
verb - Async handler support for verbs
- builder
- Builder pattern API for composable CLI applications
- capability
- Capability Management module - Registry and packing operations
- clap_
ext - Advanced clap integration (Phase 7 - v4.3)
- cli
- CLI layer - argument validation and routing only
- context
- Global application context and state management
- deprecation
- Deprecation tracking and migration helpers
- diagnostics
- Diagnostics module - System health checks and doctor mode
- error
- Error types for clap-noun-verb
- format
- Output formatting system
- ggen_
to_ rdf - ggen → RDF generator: converts Rust #[verb] source code to RDF/N-Triples ontology
- graph
- RDF Graph module - Load, query, and validate RDF data
- logic
- Business logic layer - reusable functions independent of CLI
- macros
- Convenience macros for composable CLI patterns
- noun
- Noun command trait and types for composable CLI patterns
- ontology_
sync - Bidirectional sync between Rust ggen code and RDF ontology
- policies
- Autonomic CI/CD Policies with suggest-mode recommendations
- rdf_
to_ ggen - RDF → ggen generator: converts RDF verb definitions to compilable Rust #[verb] code
- registry
- Command registry for composable CLI patterns
- repl
- Interactive REPL shell execution loop with autocomplete and history parsing
Gated behind the
replfeature. - shell
- Shell environment detection and utilities
- telemetry
- Chicago TDD Telemetry and Observability System
- tree
- Command tree for hierarchical CLI composition
- validators
- Common value validators for CLI arguments
- verb
- Verb command trait and types for composable CLI patterns
Macros§
- app
- Helper macro for building CLI applications with a declarative syntax
- cli_
builder - Macro for quickly building CLI applications
- command_
group - Helper macro to create a command group (noun with multiple verbs)
- command_
tree - Helper macro to create a command tree for hierarchical composition
- noun
- Helper macro to create a noun command
- verb
- Helper macro to create a verb command
Structs§
- Arg
- The abstract representation of a command line argument. Used to set all the options and relationships that define a valid argument for the program.
- ArgMatches
- Container for parse results.
- Command
- Build a command-line interface.
Enums§
- ArgAction
- Behavior of arguments when they are encountered while parsing