Skip to main content

Crate clap_noun_verb

Crate clap_noun_verb 

Source
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 framework
  • clap-noun-verb-macros - Our proc macros
  • linkme - Auto-discovery
  • serde, serde_json - JSON output
  • thiserror, anyhow - Error handling
  • once_cell, lazy_static, atty - Utilities

All advanced features are opt-in via cargo features:

  • full - Enable all features
  • autonomic - Agent introspection & telemetry spans
  • async - Async handlers (tokio, futures)
  • io - Advanced I/O (clio)
  • crypto - Cryptographic hashing (sha2, sha3, blake3)
  • agent2028 - Trillion-agent ecosystems
  • rdf - RDF/Ontology with MCP
  • kernel - Deterministic execution

§Version 5.3.0 Architecture

  • Attribute Macros (clap-noun-verb-macros) - #[verb] for declarative command registration
  • Auto-Discovery - Commands automatically discovered using linkme distributed slices
  • Type Inference - Arguments automatically inferred from function signatures
  • JSON Output - All output automatically serialized to JSON

§Key Principles

  1. Zero Boilerplate - Just add #[verb] attributes to functions
  2. Auto-Discovery - Commands automatically discovered at compile time
  3. Type Inference - Arguments inferred from function signatures
  4. JSON by Default - Perfect for agents, MCP, and modern tooling
  5. Minimal Dependencies - Core CLI needs only 9 crates

§API Stability

This crate follows Semantic Versioning. Version 5.3.0 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::NounVerbError;
pub use error::Result;
pub use noun::CompoundNounCommand;
pub use noun::NounCommand;
pub use noun::NounContext;
pub use registry::CommandRegistry;
pub use router::CommandRouter;
pub use tree::CommandTree;
pub use tree::CommandTreeBuilder;
pub use verb::VerbArgs;
pub use verb::VerbCommand;
pub use verb::VerbContext;
pub use context::AppContext;
pub use deprecation::Deprecation;
pub use deprecation::DeprecationType;
pub use format::format_output;
pub use format::OutputFormat;
pub use async_verb::create_runtime;
pub use async_verb::run_async;
pub use completion::generate_completion;
pub use completion::print_completion;
pub use completion::Shell;
pub use builder::CliBuilder as Cli;
pub use registry::CommandRegistry as Registry;
pub use tree::CommandTree as Tree;

Modules§

agent2028
agent_cli
Agent-optimized CLI builder for dynamic command composition
agents
Semantic Agent Coordinator
async_verb
Async handler support for verbs
autonomic
Autonomic CLI Layer - Machine-grade interface for clap-noun-verb
builder
Builder pattern API for composable CLI applications
clap_ext
Advanced clap integration (Phase 7 - v4.3)
cli
CLI layer - argument validation and routing only
completion
Shell completion generation
config
Configuration file support
context
Global application context and state management
deprecation
Deprecation tracking and migration helpers
error
Error types for clap-noun-verb
format
Output formatting system
frontier
Frontier - Advanced Agent-Grade Packages
integration
Integration Layer - Wiring middleware, custom implementations, and configuration
io
I/O Integration for clap-noun-verb
kernel
Kernel module - Core system functionality
logic
Business logic layer - reusable functions independent of CLI
macros
Convenience macros for composable CLI patterns
macros_discovery_engine
Capability Discovery Engine - Type-First Implementation
mangen
Man page generation for CLI applications
middleware
Command Middleware/Interceptors System (Feature 4 - v4.3)
noun
Noun command trait and types for composable CLI patterns
plugin
Plugin/Extension System (Feature 1 - v4.3)
plugins
10 Production Plugins with Chicago-TDD Testing
rdf
RDF/Turtle ontology control layer for CNV v5
registry
Command registry for composable CLI patterns
router
Command routing logic for noun-verb CLI
runtime
Runtime layer - execution infrastructure
semantic
Semantic CLI Composition - Runtime Support
shell
Shell environment detection and utilities
telemetry
Telemetry & Observability System (Feature 5 - v4.3)
tree
Command tree for hierarchical CLI composition
validators
Common value validators for CLI arguments
verb
Verb command trait and types for composable CLI patterns
wizard
Wizard - AI integration layer for clap-noun-verb

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
define_contract
Macro to define contracts at compile time
discoverable
Declarative macro for marking capabilities as discoverable
fitness_function
Declarative macro for defining fitness functions
noun
Helper macro to create a noun command
profile
Macro for profiling a block of code
verb
Helper macro to create a verb command
verify_bounds
Verification contract: Ensures a value is within bounds
verify_contract
Verification contract: Ensures a condition holds at runtime and compile-time

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