Tusks
Tusks allows you to define CLIs easily and idiomatically through a Rust module and function structure.
If You just want a quick example head over to the Comprehensive Example section.
Table of Contents
Motivation
Creating complex CLI applications with nested commands and shared parameters can quickly become unwieldy. Tusks solves this problem by providing a declarative syntax for CLI structures that:
- Naturally maps hierarchical command structures
- Automatically manages parameter chaining across multiple levels
- Uses Clap under the hood but eliminates boilerplate code
- Supports modular organization through external modules
- Guarantees type safety through Rust/Clap's type system
Instead of manually managing Clap subcommands and creating match statements, you simply define modules and functions – Tusks takes care of the rest.
Want to see it in action? Check out the comprehensive example at the end of this document.
Installation
[dependencies]
tusks = "0.1"
clap = { version = "4.0", features = ["derive"] }
Core Concepts
Tusks is based on four main concepts:
- Modules as Commands/Subcommands: Rust modules automatically become CLI commands. Modules serve to hierarchically group functions as subcommands.
- Functions as Commands/Subcommands: Public functions in modules become executable CLI commands/subcommands. Function arguments are automatically translated into CLI parameters.
- Parameters Struct for Command Arguments: The
Parameters struct defines arguments at the module level that apply to the respective command/subcommand. These arguments are automatically available to all underlying subcommands.
- External Modules: External modules, i.e., modules in other files, can be easily integrated into the current CLI structure, even recursively!
The CLI is started with cli::exec_cli(), which parses the command line arguments and executes the corresponding commands. The function always returns Option<u8>, which can be used as an exit code.
Relationship with Clap
Tusks is a high-level wrapper around Clap, the popular CLI parsing framework for Rust. Many of Clap's features are retained.
#[arg()] attributes for argument configuration#[command()] attributes for subcommand descriptions- Data types are parsed as in Clap
- Automatic help generation
- Type-safe parsing
Tusks generates Clap code internally.
Features and Examples
1. Simple Root Module Definition
The #[tusks(root)] attribute marks a module as the CLI entry point. The CLI is started with cli::exec_cli().
use tusks::tusks;
#[tusks(root)]
#[command(
about = "My CLI tool",
version = "1.0.0"
)]
pub mod cli {
pub fn hello(name: String) {
println!("Hello, {}!", name);
}
}
fn main() -> std::process::ExitCode {
std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
Usage:
$ my-cli hello Alice
Hello, Alice!
Visibility and #[skip]
Only public (pub) modules and functions are used for CLI construction. Private functions are automatically ignored:
#[tusks(root)]
pub mod cli {
pub fn public_command() {
println!("This is a CLI command");
}
fn private_helper() {
println!("This is not a CLI command");
}
}
With the #[skip] attribute, you can also exclude public functions from CLI parsing:
#[tusks(root)]
pub mod cli {
pub fn deploy(target: String) {
let config = load_config();
}
#[skip]
pub fn load_config() -> Config {
Config::from_file("config.toml")
}
}
The #[skip] attribute also works for modules:
#[tusks(root)]
pub mod cli {
pub mod deploy { }
#[skip]
pub mod internal_utils { }
}
2. Nested Modules (Subcommands)
Modules automatically become subcommands and serve to hierarchically group functions.
#[tusks(root)]
pub mod cli {
#[command(about = "Database operations")]
pub mod database {
pub fn migrate(version: String) {
println!("Migrating database to version {}", version);
}
pub fn backup(path: String) {
println!("Backing up database to {}", path);
}
}
#[command(about = "Deployment operations")]
pub mod deploy {
pub fn staging() {
println!("Deploying to staging environment");
}
pub fn production() {
println!("Deploying to production environment");
}
}
}
Usage:
$ my-cli database migrate v2.0
Migrating database to version v2.0
$ my-cli deploy production
Deploying to production environment
$ my-cli --help
My CLI tool
Usage: my-cli <COMMAND>
Commands:
database Database operations
deploy Deployment operations
help Print this message or the help of the given subcommand(s)
Modules can be nested arbitrarily deep:
#[tusks(root)]
pub mod cli {
pub mod cloud {
pub mod aws {
pub mod s3 {
pub fn upload(file: String, bucket: String) {
println!("Uploading {} to bucket {}", file, bucket);
}
}
}
}
}
Usage:
$ my-cli cloud aws s3 upload file.txt my-bucket
Uploading file.txt to bucket my-bucket
With a Parameters struct, you can define common parameters that are available to all commands.
#[tusks(root)]
pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
#[arg(long)]
pub config: &'a Option<String>,
}
pub fn deploy(params: &Parameters, target: String) {
if *params.verbose {
println!("Deploying to {} with config {:?}",
target, params.config);
}
}
}
Usage:
$ my-cli --verbose --config prod.toml deploy production
Deploying to production with config Some("prod.toml")
Important Notes on Parameters
-
Optional: The Parameters struct is completely optional. You only need it if you want to define parameters at the current module level or access parent parameters.
-
Lifetime required: If you define a Parameters struct, it must always have the lifetime <'a>:
pub struct Parameters<'a> { #[arg(long)]
pub my_param: &'a String,
}
-
Automatic super_ field: Tusks automatically adds a super_ field that references the parent Parameters struct. You must not define this field yourself:
pub struct Parameters<'a> {
#[arg(long)]
pub my_param: &'a String,
}
-
Implicit Parameters structs: Even if you don't define a Parameters struct at a level, it exists in the background. This means that super_.super_ always works to access parameters two levels up:
pub mod level1 {
pub mod level2 {
pub struct Parameters<'a> {
#[arg(long)]
pub level2_param: &'a String,
}
pub fn command(params: &Parameters) {
println!("{}", params.super_.super_.root_param);
}
}
}
-
Parameters as function argument: The Parameters struct may only be specified as the first argument of a function and is optional. If you don't need it, you can omit it:
pub fn command1(params: &Parameters, name: String) { }
pub fn command2(name: String, age: u32) { }
pub fn command3(name: String, params: &Parameters) { }
3. Root Parameters with Parameters Struct
With a Parameters struct, you can define common parameters that are available to all commands.
#[tusks(root)]
pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
#[arg(long)]
pub config: &'a Option<String>,
}
pub fn deploy(params: &Parameters, target: String) {
if *params.verbose {
println!("Deploying to {} with config {:?}",
target, params.config);
}
}
}
Usage:
$ my-cli --verbose --config prod.toml deploy production
Deploying to production with config Some("prod.toml")
Modules automatically become subcommands with their own parameters.
#[tusks(root)]
pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
}
#[command(about = "Database operations")]
pub mod database {
pub struct Parameters<'a> {
#[arg(long)]
pub connection: &'a String,
}
pub fn migrate(params: &Parameters) {
println!("Migrating database: {}", params.connection);
if *params.super_.verbose {
println!("Verbose mode enabled");
}
}
}
}
Usage:
$ my-cli --verbose database --connection "localhost:5432" migrate
Migrating database: localhost:5432
Verbose mode enabled
4. Module-Level Parameters
Each module can define its own Parameters struct to define specific arguments for the respective subcommand. These parameters are automatically available to all underlying subcommands.
#[tusks(root)]
pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
}
#[command(about = "Database operations")]
pub mod database {
pub struct Parameters<'a> {
#[arg(long)]
pub connection: &'a String,
}
pub fn migrate(params: &Parameters) {
println!("Migrating database: {}", params.connection);
if *params.super_.verbose {
println!("Verbose mode enabled");
}
}
}
}
Usage:
$ my-cli --verbose database --connection "localhost:5432" migrate
Migrating database: localhost:5432
Verbose mode enabled
Parameters can be passed through an arbitrary number of levels.
#[tusks(root)]
pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub env: &'a String,
}
pub mod services {
pub struct Parameters<'a> {
#[arg(long)]
pub region: &'a String,
}
pub mod kubernetes {
pub struct Parameters<'a> {
#[arg(long)]
pub namespace: &'a String,
}
pub fn deploy(params: &Parameters, image: String) {
println!("Environment: {}", params.super_.super_.env);
println!("Region: {}", params.super_.region);
println!("Namespace: {}", params.namespace);
println!("Image: {}", image);
}
}
}
}
Usage:
$ my-cli --env production services --region eu-west-1 kubernetes --namespace default deploy my-app:v1.0
Environment: production
Region: eu-west-1
Namespace: default
Image: my-app:v1.0
5. External Modules
External modules allow distributing CLI structures across multiple files. This is particularly useful for organizing large CLIs and promoting code reusability.
An external module differs from the root module in that it does not have the root flag in the #[tusks()] attribute. Instead, it must include a parent_ reference to its parent module to enable parameter chaining.
src/main.rs:
#[tusks(root)] pub mod cli {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
}
#[command(about = "Git commands")]
pub use crate::git::cli as git;
}
src/git.rs:
use tusks::tusks;
#[tusks()] pub mod cli {
pub use crate::cli as parent_;
pub struct Parameters<'a> {
#[arg(long)]
pub branch: &'a String,
}
pub fn commit(params: &Parameters, message: String) {
println!("Committing on branch {}: {}",
params.branch, message);
if *params.super_.verbose {
println!("Verbose output enabled");
}
}
}
Usage:
$ my-cli --verbose git --branch main commit "Fix bug"
Committing on branch main: Fix bug
Verbose output enabled
Important Notes on External Modules
-
Parent reference required: External modules must always contain a parent_ reference to their parent module. The alias parent_ must be used.
pub use crate::cli as parent_;
This reference also enables parameter chaining via super_.
-
No root flag: External modules use #[tusks()] without the root flag. Only the main module (the entry point for the CLI) uses #[tusks(root)].
-
Customize subcommand names: The name of the subcommand is determined by the name used during import:
pub use crate::git::cli;
pub use crate::git::cli as git;
pub use crate::git::cli as vcs;
#[command(name = "version-control")]
pub use crate::git::cli as git;
-
Arbitrary nesting: External modules can themselves include external modules:
src/git.rs:
#[tusks()]
pub mod cli {
pub use crate::cli as parent_;
#[command(about = "Advanced git operations")]
pub use crate::git_advanced::cli as advanced;
}
src/git_advanced.rs:
#[tusks()]
pub mod cli {
pub use crate::git::cli as parent_;
pub fn rebase() { }
}
Invocation:
$ my-cli git advanced rebase
6. Return Values and Exit Codes
Commands can return values that are used as exit codes. Allowed return types are (), u8, and Option<u8>. The return value is always returned by cli::exec_cli() as Option<u8>.
#[tusks(root)]
pub mod cli {
pub fn success() {
println!("Operation completed successfully");
}
pub fn check_health() -> u8 {
println!("Running health checks...");
if all_systems_ok() {
println!("✓ All systems operational");
0 } else {
println!("✗ System degraded");
1 }
}
pub fn validate(file: String) -> Option<u8> {
println!("Validating {}...", file);
match check_file(&file) {
Ok(_) => {
println!("✓ Valid");
Some(0) }
Err(e) if e.is_warning() => {
println!("⚠ Warnings found");
Some(2) }
Err(_) => {
println!("✗ Invalid");
None
}
}
}
}
fn main() -> std::process::ExitCode {
std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
Usage:
$ my-cli check-health
Running health checks...
✗ System degraded
$ echo $?
1
$ my-cli validate config.toml
Validating config.toml...
✓ Valid
$ echo $?
0
7. Various Argument Types
Tusks supports all Clap argument types.
#[tusks(root)]
pub mod cli {
pub fn build(
#[arg(short, long)]
target: String,
#[arg(long)]
features: Vec<String>,
#[arg(long)]
release: bool,
#[arg(long)]
jobs: Option<u32>,
) {
println!("Building target: {}", target);
println!("Features: {:?}", features);
println!("Release mode: {}", release);
println!("Jobs: {:?}", jobs.unwrap_or(4));
}
}
Usage:
$ my-cli build --target x86_64-linux --features async --features logging --release --jobs 8
Building target: x86_64-linux
Features: ["async", "logging"]
Release mode: true
Jobs: 8
8. Custom Value Parsers
Clap's value parsers can be used to add custom validation.
#[tusks(root)]
pub mod cli {
#[skip] pub fn parse_port(s: &str) -> Result<u16, String> {
s.parse::<u16>()
.map_err(|_| "Port must be between 0 and 65535".into())
}
pub fn serve(
#[arg(value_parser = crate::cli::parse_port)]
port: u16
) {
println!("Starting server on port {}", port);
}
}
Usage:
$ my-cli serve 8080
Starting server on port 8080
$ my-cli serve invalid
error: invalid value 'invalid' for '<PORT>': Port must be between 0 and 65535
9. Tasks Mode (Ruby Rake-Style)
Tasks mode provides a simplified, flat CLI syntax in the style of Ruby Rake. Instead of nested subcommands, tasks can be invoked with a separator (default .).
Activation
Tasks mode is simply activated through the tasks attribute:
#[tusks(root, tasks)]
#[command(about = "Task management tool")]
pub mod tasks {
#[command(about = "Git operations")]
pub mod git {
pub fn clone(url: String, path: Option<String>) {
println!("Cloning {} to {:?}", url, path);
}
pub fn commit(message: String) {
println!("Committing: {}", message);
}
}
#[command(about = "Docker operations")]
pub mod docker {
pub fn build(context: String, tag: Option<String>) {
println!("Building from {} with tag {:?}", context, tag);
}
}
}
Display Task List
Without arguments, the CLI automatically shows all available tasks in a grouped overview:
$ tasks
Task management tool
git
git.clone Clone a repository
git.commit Commit changes
docker
docker.build Build Docker image
Flat Task Syntax
Tasks can be invoked directly via their full path:
$ tasks git.clone https://github.com/user/repo
$ tasks git clone https://github.com/user/repo
Both variants are fully interchangeable. The subcommand structure is preserved, so you can still use module-specific parameters:
$ tasks --root-param value git --git-option xyz clone https://...
Help for Tasks
Help can be accessed in multiple ways:
$ tasks h git.clone
$ tasks git.clone -h
$ tasks git clone --help
All three variants display the same help:
Clone a repository
Usage: tasks git clone <URL> [PATH]
Arguments:
<URL> Repository URL
[PATH] Target path
Options:
-h, --help Print help
Configuring Task Grouping
The task overview display can be configured:
#[tusks(root, tasks(max_groupsize=5, max_depth=20, separator="."))]
pub mod tasks {
}
Parameters:
-
separator (default: ".") - Separator between module and task
$ tasks git.clone url
$ tasks git:clone url
-
max_groupsize (default: 5) - Maximum number of tasks per group before further subdivision
This parameter only affects the task overview output.
The grouping heuristic divides tasks hierarchically:
- First level: Grouping by top-level modules (e.g.,
git, docker)
- If a group contains more than
max_groupsize tasks, it is further subdivided
- Groups with only one element are merged with their parent group
Example with max_groupsize=3:
git
git.clone
git.commit
docker.image
docker.image.build
docker.image.push
docker.container
docker.container.run
docker.container.stop
-
max_depth (default: 20) - Maximum nesting depth for grouping
This parameter only affects the task overview output.
Prevents overly deep nesting in the output:
- Depth 0: Root level (no grouping)
- Depth 1: Grouping by top-level modules
- Depth 2: Grouping by submodules
When max_depth is reached, no further subdivisions are made, even if max_groupsize is exceeded.
Note: Currently there are still bugs regarding the max_groupsize and max_depth parameters. The behavior is not exactly as described above and will likely change in the future.
Complete Example
use tusks::tusks;
#[tusks(root, tasks(separator=".", max_groupsize=5, max_depth=10))]
#[command(
about = "DevOps toolkit",
version = "1.0.0"
)]
pub mod tasks {
pub mod deploy {
pub fn staging(version: String) {
println!("Deploying {} to staging", version);
}
pub fn production(version: String) {
println!("Deploying {} to production", version);
}
}
pub mod test {
pub fn unit() {
println!("Running unit tests");
}
pub fn integration() {
println!("Running integration tests");
}
}
}
fn main() -> std::process::ExitCode {
std::process::ExitCode::from(tasks::exec_cli().unwrap_or(0) as u8)
}
Usage:
$ tasks
DevOps toolkit
deploy
deploy.staging Deploy to staging
deploy.production Deploy to production
test
test.unit Run unit tests
test.integration Run integration tests
$ tasks deploy.staging v1.2.3
$ tasks deploy staging v1.2.3
$ tasks h deploy.production
$ tasks deploy.production -h
10. Command Attributes for Documentation
Use #[command()] attributes to define CLI documentation. This is a standard Clap feature and is mentioned here only as a common use case.
#[tusks(root)]
#[command(
about = "Project management CLI",
long_about = "A comprehensive tool for managing development projects",
version = "2.0.0",
author = "Your Team <team@example.com>"
)]
pub mod cli {
#[command(
about = "Create a new project",
long_about = "Initialize a new project with default structure and configuration"
)]
pub fn init(
#[arg(help = "Project name")]
name: String,
#[arg(long, help = "Project template to use")]
template: Option<String>,
) {
println!("Initializing project: {}", name);
}
}
Usage:
$ my-cli --help
Project management CLI
A comprehensive tool for managing development projects
Usage: my-cli [OPTIONS] <COMMAND>
Commands:
init Create a new project
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
11. Default Functions for Modules
With the #[default] attribute, you can define a function that is executed when a module is invoked without a specific subcommand.
#[tusks(root)]
pub mod cli {
#[command(about = "Git operations")]
pub mod git {
pub struct Parameters<'a> {
#[arg(long)]
pub repository: &'a Option<String>,
}
#[default]
pub fn status(params: &Parameters) {
println!("Git status for {:?}", params.repository);
}
pub fn push(branch: String) {
println!("Pushing to {}", branch);
}
pub fn pull(branch: String) {
println!("Pulling from {}", branch);
}
}
}
Usage:
$ my-cli git --repository myrepo
Git status for Some("myrepo")
$ my-cli git status --repository myrepo
Restrictions for Default Functions
-
Only Parameters allowed: Default functions may have at most the Parameters struct of the current level as an argument. Additional parameters are not permitted:
#[default]
pub fn default_action(params: &Parameters) { }
#[default]
pub fn default_action() { }
#[default]
pub fn default_action(params: &Parameters, name: String) { }
-
Exception: Allow External Subcommands: If allow_external_subcommands = true is set for the module, the default function may additionally receive a Vec<String> argument containing all arguments of the external subcommand:
#[command(about = "Command runner", allow_external_subcommands = true)]
pub mod run {
pub struct Parameters<'a> {
#[arg(long)]
pub verbose: &'a bool,
}
#[default]
pub fn execute(params: &Parameters, args: Vec<String>) {
println!("Running external command with args: {:?}", args);
if *params.verbose {
println!("Verbose mode enabled");
}
}
pub fn builtin() {
println!("This is a built-in command");
}
}
Usage:
$ my-cli run --verbose custom-script --arg1 --arg2
Running external command with args: ["custom-script", "--arg1", "--arg2"]
Verbose mode enabled
$ my-cli run builtin
This is a built-in command
Comprehensive Example
Here's a complete example demonstrating most of Tusks' features in a single application:
src/main.rs:
use tusks::tusks;
#[tusks(root)]
#[command(
about = "DevOps automation toolkit",
long_about = "A comprehensive CLI for managing deployments, databases, and CI/CD pipelines",
version = "1.0.0",
author = "DevOps Team <devops@example.com>"
)]
pub mod cli {
pub fn health() -> u8 {
println!("Running system health checks...");
let healthy = check_system_health();
if healthy {
println!("✓ All systems operational");
0 } else {
println!("✗ System issues detected");
1 }
}
#[command(about = "Database operations")]
pub mod database {
#[default]
pub fn status(
#[arg(long, help = "Database connection string")]
connection: String,
) {
println!("Database status for: {}", connection);
println!("Connection pool: 10/50");
println!("Active queries: 3");
}
pub fn migrate(
#[arg(long, help = "Database connection string")]
connection: String,
#[arg(help = "Target migration version")]
version: String,
#[arg(long, help = "Perform dry-run without applying changes")]
dry_run: bool,
) -> Option<u8> {
println!("Migrating database to version: {}", version);
println!("Connection: {}", connection);
if dry_run {
println!("⚠ Dry-run mode - no changes applied");
return Some(0);
}
let success = perform_migration(&version);
if success {
println!("✓ Migration completed successfully");
Some(0)
} else {
println!("✗ Migration failed");
None
}
}
#[command(about = "Advanced database operations")]
pub mod advanced {
pub fn optimize(
#[arg(long, help = "Database connection string")]
connection: String,
) -> u8 {
println!("Optimizing database: {}", connection);
println!("✓ Optimization completed");
0
}
}
}
#[command(about = "Deployment commands")]
pub use crate::deploy::cli as deploy;
#[skip]
pub fn parse_port(s: &str) -> Result<u16, String> {
let port: u16 = s.parse()
.map_err(|_| format!("'{}' is not a valid port number", s))?;
if port < 1024 {
return Err("Port must be 1024 or higher".to_string());
}
Ok(port)
}
#[skip]
fn check_system_health() -> bool {
true
}
#[skip]
fn perform_migration(_version: &str) -> bool {
true
}
}
fn main() -> std::process::ExitCode {
std::process::ExitCode::from(cli::exec_cli().unwrap_or(0) as u8)
}
src/deploy.rs:
use tusks::tusks;
#[tusks()] pub mod cli {
pub use crate::cli as parent_;
pub fn start(
#[arg(help = "Application version to deploy")]
version: String,
#[arg(long, help = "Target environment")]
environment: String,
#[arg(long, help = "Server port", value_parser = crate::cli::parse_port)]
port: Option<u16>,
) -> u8 {
let port = port.unwrap_or(8080);
println!("Deploying version {} to {}", version, environment);
println!("Server will listen on port: {}", port);
println!("✓ Deployment initiated");
0
}
pub fn rollback(
#[arg(long, help = "Target environment")]
environment: String,
) {
println!("Rolling back deployment in {}", environment);
println!("✓ Rollback completed");
}
}
Usage examples:
$ my-cli health
Running system health checks...
✓ All systems operational
$ my-cli database --connection "postgres://localhost/mydb"
Database status for: postgres://localhost/mydb
Connection pool: 10/50
Active queries: 3
$ my-cli database status --connection "postgres://localhost/mydb"
Database status for: postgres://localhost/mydb
Connection pool: 10/50
Active queries: 3
$ my-cli database migrate --connection "postgres://localhost/mydb" v2.0 --dry-run
Migrating database to version: v2.0
Connection: postgres://localhost/mydb
⚠ Dry-run mode - no changes applied
$ my-cli database advanced optimize --connection "postgres://localhost/mydb"
Optimizing database: postgres://localhost/mydb
✓ Optimization completed
$ my-cli deploy start v1.5.0 --environment production --port 8080
Deploying version v1.5.0 to production
Server will listen on port: 8080
✓ Deployment initiated
$ my-cli deploy start v1.4.0 --environment staging --port 80
error: invalid value '80' for '--port <PORT>': Port must be 1024 or higher
$ my-cli deploy rollback --environment production
Rolling back deployment in production
✓ Rollback completed
Note: This example demonstrates how arguments can be defined directly in function signatures. You can also define module-level parameters using a Parameters struct which would then be available to all commands within that module and automatically passed down to nested submodules. The parameters would be specified before the subcommand name:
$ my-cli database --connection "..." --verbose migrate v2.0
$ my-cli database --connection "..." status
For more details on how to define and use module-level parameters, see Module-Level Parameters.
Equivalent with Raw Clap Syntax
Here's what the same CLI structure would look like using Clap's derive API directly (abbreviated for brevity):
use clap::{Parser, Subcommand, Args};
#[derive(Parser)]
#[command(
about = "DevOps automation toolkit",
long_about = "A comprehensive CLI for managing deployments, databases, and CI/CD pipelines",
version = "1.0.0",
author = "DevOps Team <devops@example.com>"
)]
struct Cli {
#[command(subcommand)]
command: Option<Commands>,
}
#[derive(Subcommand)]
enum Commands {
Health,
Database {
#[command(subcommand)]
command: Option<DatabaseCommands>,
},
Deploy {
#[command(subcommand)]
command: DeployCommands,
},
}
#[derive(Subcommand)]
enum DatabaseCommands {
Status {
#[arg(long, help = "Database connection string")]
connection: String,
},
Migrate {
#[arg(long, help = "Database connection string")]
connection: String,
version: String,
#[arg(long)]
dry_run: bool,
},
Advanced {
#[command(subcommand)]
command: AdvancedCommands,
},
}
#[derive(Subcommand)]
enum AdvancedCommands {
Optimize {
#[arg(long, help = "Database connection string")]
connection: String,
},
}
#[derive(Subcommand)]
enum DeployCommands {
Start {
version: String,
#[arg(long, help = "Target environment")]
environment: String,
#[arg(long, value_parser = parse_port)]
port: Option<u16>,
},
Rollback {
#[arg(long, help = "Target environment")]
environment: String,
},
}
fn main() -> std::process::ExitCode {
let cli = Cli::parse();
let exit_code = match cli.command {
Some(Commands::Health) => {
health()
}
Some(Commands::Database { command }) => {
match command {
Some(DatabaseCommands::Status { connection }) | None => {
database_status(&connection);
0
}
Some(DatabaseCommands::Migrate { connection, version, dry_run }) => {
database_migrate(&connection, &version, dry_run)
.unwrap_or(1)
}
Some(DatabaseCommands::Advanced { command }) => {
match command {
AdvancedCommands::Optimize { connection } => {
database_advanced_optimize(&connection)
}
}
}
}
}
Some(Commands::Deploy { command }) => {
match command {
DeployCommands::Start { version, environment, port } => {
deploy_start(&version, &environment, port)
}
DeployCommands::Rollback { environment } => {
deploy_rollback(&environment);
0
}
}
}
None => {
Cli::parse_from(&["cli", "--help"]);
0
}
};
std::process::ExitCode::from(exit_code)
}
fn health() -> u8 {
0
}
fn database_status(connection: &str) {
}
fn database_migrate(connection: &str, version: &str, dry_run: bool) -> Option<u8> {
Some(0)
}
fn database_advanced_optimize(connection: &str) -> u8 {
0
}
fn deploy_start(version: &str, environment: &str, port: Option<u16>) -> u8 {
0
}
fn deploy_rollback(environment: &str) {
}
As you can see, Tusks eliminates:
- Manual enum definitions for every command level
- Repetitive match/dispatch logic
- Manual parameter passing through the hierarchy
- Boilerplate for default command handling
License
MIT
Contributions
Contributions are welcome! Please create an issue or pull request on GitHub.
I'm still learning Rust. I always have an open ear for suggestions on best practices, code style, etc.
I will try to respond to contributions, but as I work full-time with a wife and child, this will not always be possible in a timely manner.
Trivia
This project originally came about because I've wanted to learn and use Rust for a long time, and also because I was looking for a replacement for Ruby Rake and Python Invoke that is idiomatic, future-oriented, and easy to use. The use of these tools is also always limited by the environment you're in. Often, the versions of interpreters and packages differ across various server environments. A compiled Rust application is much more flexible in this regard. However, there are also disadvantages. The effort and barrier to creating and extending a compiled application is higher than with a simple Python script. And of course, the appropriate toolchain must be available on the system where you develop. But Rust makes it quite easy with cargo.
During development, I worked extensively with various AIs. Otherwise, this would not have been possible within a week with my existing basic knowledge, especially not for a project that relies so heavily on source code parsing and generation, i.e., the creation of macros. In some places, I performed some refactoring. In other places, I only superficially adapted or reviewed the code. Little code was actually written 100% by myself. This is an interesting experience for me, and you can certainly view it critically. However, I think I still learned a lot, and I'm actually quite satisfied with the code quality. If I had actually done everything myself, it would probably have turned out significantly worse (or simply not finished). But one should always keep in mind that I'm a Rust beginner. The way to write code in Rust, to structure it, the patterns used - all of this is definitely very different in many ways from many programming languages I've used before. Accordingly, this is a beginner's project.
