Default Subcommand

[pvshvp-oss]

Is there a way for clap to have a default subcommand that would be in effect if none are specified?

For example, I want to be able to use both

my_app create -t "some text" -p "some password"

and also

my_app -t "some text" -p "some password"

where "create" is assumed to be the default subcommand. However, when a different subcommand is specified, the default subcommand does not go into effect. For example:

my_app delete -id "1234"

Is there any stable or unstable item in the API to implement the above?

[epage]

At the moment there is not. You can do it manually though. Something like

let cmd = clap::Command::new("git")
    .subcommand(
        clap::Command::new("stash")
            .args_conflicts_with_subcommands(true)
            .args(push_args())
            .subcommand(clap::Command::new("push").args(push_args()))
    );

let matches = cmd.get_matches();
match matches.subcommand() {
    Some(("stash", sub_matches)) => match sub_matches.subcommand() {
        Some(("push"), sub_matches)) => push(sub_matches),
        None => push(sub_matches),
    }
}

We should probably add this to our "git" example.

[pvshvp-oss]

@epage Can this example be fully recreated using the Derive API?

[epage]

The git example I'm going to merge this into has both a derive and builder version, so that will be where I recreate it fully.

Basically, it comes down to creating a

#[clap::Args]
struct PushArgs {
}

and flattening that into both your subcommand and top-level command. For args_conflicts_with_subcommands, all function calls are automatically attributes. The derive reference tries to explain the principles for how the derive API builds on the builder API so people can use docs from both. Ideas for improving us meeting that goal can be added in #3189.

While some work is needed on it to fully match what I'm describing, you can also check out git-branch-stash's args

[epage]

Finally got to writing up examples for default subcommands: #3570

[epage]

FYI #4350 was merged which should simplify some default subcommand cases (the flattened struct can have required fields now)

[dnaka91]

Is there currently a way to do this with a required argument (like in StashPush in the example, with message being a String instead of Option<String>)?

What I try to achieve is, having two subcommands completions and manpages to output shell completions or generate man pages, respectively.

But the main entry point has a required argument, as the application would not work correctly without it. So I need some way of telling clap "ignore any required fields if a subcommand is present, but not otherwise".

This is a very simplified version:

// cli.rs

#[derive(Parser)]
pub struct Cli {
    #[command(subcommand)]
    pub cmd: Option<Command>,
    #[command(flatten)]
    pub run: Option<Run>,
}

#[derive(Subcommand)]
pub enum Command {
    Run(Run),
    Completions {
        #[arg(value_enum)]
        shell: Shell,
    },
    Manpages {
        #[arg(value_hint = ValueHint::DirPath)]
        dir: PathBuf,
    }
}

#[derive(Args)]
pub struct Run {
    #[arg(short, long, value_hint = ValueHint::FilePath)]
    pub input: PathBuf,
    // further optional args omitted for simplicity
}

Then calling it as follows:

// main.rs

mod cli;

fn main() {
    let cli = Cli::parse();
    let cmd = cli.cmd.or_else(|| cli.run.map(Command::Run)).unwrap();
    // don't really like the unwrap, but we can really make `run` a non-Option, right?

    map cmd {
        // ...
    }
}

Now, when trying to run the completions for example, it still requires input to be present, even being part of the help message:

$ cargo run -- completions -h
Usage: ffprog --input <INPUT> completions <SHELL>

... Args and options part omitted here

---

Is there any special option that I'm missing to make it ignore the input argument somehow, or is it simply not possible at the moment? Btw, using latest 4.0.12.

[epage]

For anyone else, a slightly easier copy to reproduce with

#!/usr/bin/env -S rust-script

//! ```cargo
//! [dependencies]
//! clap = { version = "=4.0.12", features = ["derive"] }
//! clap_complete = { version = "4.0" }
//! ```

use std::path::PathBuf;

use clap::Args;
use clap::Parser;
use clap::Subcommand;
use clap::ValueHint;
use clap_complete::Shell;

#[derive(Parser, Debug)]
#[command(args_conflicts_with_subcommands = true)]
pub struct Cli {
    #[command(subcommand)]
    pub cmd: Option<Command>,
    #[command(flatten)]
    pub run: Option<Run>,
}

#[derive(Subcommand, Debug)]
pub enum Command {
    Run(Run),
    Completions {
        #[arg(value_enum)]
        shell: Shell,
    },
    Manpages {
        #[arg(value_hint = ValueHint::DirPath)]
        dir: PathBuf,
    },
}

#[derive(Args, Debug)]
pub struct Run {
    #[arg(short, long, value_hint = ValueHint::FilePath)]
    pub input: PathBuf,
    // further optional args omitted for simplicity
}

fn main() {
    let cli = Cli::parse();
    println!("{:?}", cli);
}

[epage]

With the above code, it works for me

$ ./clap-3566.rs completions bash
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `/home/epage/src/personal/cargo-script-mvs/target/debug/rust-script ./clap-3566.rs completions bash`
Cli { cmd: Some(Completions { shell: Bash }), run: None }

[dnaka91]

I now realize, the problem only occurs when there are multiple values in the Run struct. So with the following it works:

#[derive(Args, Debug)]
pub struct Run {
    #[arg(short, long, value_hint = ValueHint::FilePath)]
    pub input: PathBuf,
}

But as soon as I add another option, it fails:

pub struct Run {
    #[arg(short, long, value_hint = ValueHint::FilePath)]
    pub input: PathBuf,
    #[arg(short, long)]
    pub overwrite: bool,
}

[epage]

Looks like we had a bug with defaults; should be fixed in v4.0.14

[dnaka91]

Thank you so much. Just gave it a try, and works now 🚀