We’ll be building out a new CLI named garden, so in a new directory we can run cargo init.

❯ cargo init --name garden
     Created binary (application) package

This gives us the usual Cargo project with a src/main.rs.

Since we’ve used clap before in other workshops, we’ll immediately roll into adding clap as a dependency and enabling both the env feature and the derive feature using the -F flag.

❯ cargo add clap -F env -F derive
    Updating crates.io index
      Adding clap v4.3.19 to dependencies.
             Features:
             + color
             + derive
             + env
             + error-context
             + help
             + std
             + suggestions
             + usage
             - cargo
             - debug
             - deprecated
             - string
             - unicode
             - unstable-doc
             - unstable-styles
             - unstable-v5
             - wrap_help
    Updating crates.io index

Our Cargo.toml will have clap as a dependency with these features enabled.

[package]
name = "garden"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
clap = { version = "4.3.19", features = ["env", "derive"] }

garden is going to have multiple subcommands. The first of which is garden write, which will be responsible for allowing the user to create new markdown files in a pre-determined directory. Our help text will look like this.

❯ cargo run -- --help
   Compiling garden v0.1.0 (/rust-adventure/digital-garden)
    Finished dev [unoptimized + debuginfo] target(s) in 2.83s
     Running `target/debug/garden --help`
A CLI for the growing and curation of a digital garden

Visit https://www.rustadventure.dev for more!

Usage: garden [OPTIONS] <COMMAND>

Commands:
  write  write something in your garden
  help   Print this message or the help of the given subcommand(s)

Options:
  -p, --garden-path <GARDEN_PATH>
          [env: GARDEN_PATH=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

The code that implements that is here. Our Args struct gets the Parser derive macro, as well as the clap version attribute which powers the --version flag.

Our garden_path is a global flag that can apply to any of our subcommands. It also uses clap(env) to enable setting the path via an environment variable. The environment variables name is inferred and would be GARDEN_PATH in this case.

use clap::{Parser, Subcommand};
use std::path::PathBuf;

/// A CLI for the growing and curation of a digital garden
///
/// Visit https://www.rustadventure.dev for more!
#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short = 'p', long, env)]
    garden_path: Option<PathBuf>,

    #[command(subcommand)]
    cmd: Commands,
}
#[derive(Subcommand, Debug)]
enum Commands {
    /// write something in your garden
    ///
    /// This command will open your $EDITOR, wait for you
    /// to write something, and then save the file to your
    /// garden
    Write {
        /// Optionally set a title for what you are going to write about
        #[clap(short, long)]
        title: Option<String>,
    },
}

fn main() {
    let args = Args::parse();
    dbg!(args);
}

The we use the command helper to define our subcommands via an enum.

We need to use the Subcommand derive macro to be able to use our enum like this.

The Commands enum then is a set of variants that define what our subcommands will be, as long as the flags they take.

The Write subcommand includes a --title flag with short and long forms. The flag doesn’t have to be provided, so we make the type an Option<String> and clap won’t fail if the title isn’t provided.

Our main function only handles running the parse function the Parser derive macro created for us, and debugging that value out.

Running the CLI

If we only run cargo run now, we’ll see the help text because the root without a subcommand doesn’t do anything.

We can use the write subcommand to see what values Args holds.

❯ cargo run -- write
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/garden write`
[src/main.rs:32] args = Args {
    garden_path: None,
    cmd: Write {
        title: None,
    },
}

We also get help text on our subcommands automatically. Both the short form

❯ cargo run -- write -h
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/garden write -h`
write something in your garden

Usage: garden write [OPTIONS]

Options:
  -t, --title <TITLE>  Optionally set a title for what you are going to write about
  -h, --help           Print help (see more with '--help')

and the long form

❯ cargo run -- write --help
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/garden write --help`
write something in your garden

This command will open your $EDITOR, wait for you to write something, and then save the file to your garden

Usage: garden write [OPTIONS]

Options:
  -t, --title <TITLE>
          Optionally set a title for what you are going to write about

  -h, --help
          Print help (see a summary with '-h')

All together, our CLI specification allows us to set a garden path via a flag or an environment variable, and use a subcommand. That subcommand then also gets to have its own flags, like --title.

All of this information gets dropped into our Args struct when we parse, making it easy to process later.

❯ cargo run -- -p some-garden write -t "My New Post"
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
     Running `target/debug/garden -p some-garden write -t 'My New Post'`
[src/main.rs:32] args = Args {
    garden_path: Some(
        "some-garden",
    ),
    cmd: Write {
        title: Some(
            "My New Post",
        ),
    },
}