Concepts
This section explains the core concepts and design principles behind Clawless. Understanding these concepts will help you make the most of the framework and build CLIs that follow best practices.
Core concepts
Commands
Commands are the building blocks of your CLI. Learn how the #[command] macro
transforms regular Rust functions into CLI commands, how command functions are
structured, and what happens under the hood.
Arguments
Arguments define the inputs your commands accept. Discover how Clawless uses Clap's derive API for type-safe argument parsing, how to define flags and options, and how arguments integrate with commands.
Context
The Context system provides commands with access to framework features. Explore how Context gives you environment information, output control, cancellation, and more.
Output
Framework-controlled command output with verbosity and JSON support. Learn how
the Output type replaces direct println! calls, how --quiet, --verbose,
and --json flags work, and when to use message, detail, and artifact.
Rendering
Event-driven rendering for CLI and TUI applications. Learn how commands emit events, how the framework renders them through presenters and projections, and why the same command code works in both contexts.
Cancellation
Cooperative shutdown through cancellation tokens. Learn how Clawless handles Ctrl+C signals, how commands observe cancellation to shut down gracefully, and how parent-child tokens enable scoped cancellation.
External Programs
Running other programs from your commands. Learn how Clawless streams the output of a program through the event system while it runs, how cancellation kills it, and how to read what it produced afterwards.
Prompts
Asking the user a question from your commands. Learn the three kinds of prompt, what a prompt returns without a user, and how a test answers a prompt.
Exit Codes
Ending the process with a code that your command chooses. Learn how a command returns an exit code and its own text, and which exit codes Clawless uses itself.
Macros
Clawless uses four macros to wire up your CLI. Understand how main!,
commands!, #[command], and #[application] work together to generate the
glue code that makes convention-based development possible.
Project Structure
Your file structure becomes your command structure. Learn how Clawless maps module hierarchies to command hierarchies, where to place command files, and how to organize large CLIs.
Naming Conventions
Names matter in Clawless. See how file names, function names, and module names automatically become command names, subcommands, and help text.
Design principles
These are the principles that guided the design of Clawless:
Convention over configuration
Clawless makes decisions for you so you can focus on building features. By following conventions, the framework is able to provide sensible defaults and advanced features without requiring extensive configuration.
Batteries included
Common CLI needs like configuration management, structured output, and logging are built into the framework rather than requiring you to integrate separate libraries. This ensures consistency across projects and reduces the decision fatigue of choosing and configuring dependencies.
Rapid development
Clawless optimizes for speed of development. The scaffolding CLI
(cargo clawless new, cargo clawless generate command) gets you from idea to
working code quickly.
Progressive disclosure
Start simple and add complexity only when needed. A basic command is just a function with a macro. As your needs grow, you can add arguments, use context features, organize into nested hierarchies, and leverage advanced framework capabilities.
Learning path
If you're new to Clawless:
- Start with Commands and Arguments to understand the basics
- Learn about Context to access framework features
- Read Output to understand framework-controlled command output
- Read Rendering to understand how output reaches the terminal
- Read Cancellation to understand cooperative shutdown
- Read External Programs when your CLI needs to run other programs
- Read Prompts when your CLI needs an answer from its user
- Read Exit Codes when a script or a CI job reads the exit code of your CLI
- Explore Project Structure to understand how to organize your CLI
- Read Macros if you're curious about implementation details
- Reference Naming Conventions when you need to look up specific rules
For experienced developers, the Macros section provides insight into how Clawless generates code, which can help with debugging and understanding limitations.