How to create a cli that operates as a cargo plugin

[NathanFrasier]

I'm trying to build a simple CLI tool that should be able to be used as a cargo plugin. As such my tool could be invoked as cargo toolname subcommand or cargo-toolname subcommand. I am struggling to use the derive attributes correctly to sometimes consume the first argument, but only when it matches the correct value. Below is my code, any help is appreciated!

#[derive(Parser)]
#[command(version, about, long_about = None)]
#[command(propagate_version = true)]
struct Cli {
    #[arg(name = "toolchainer")]
    dummy: (),
    #[command(subcommand)]
    command: Commands,
}

Specifically this seems to consume any first argument that doesn't match a subcommand, which leads to less than clear error messages when a typo is made in that subcommand. ie cargo-toolname urpdate yields the top level command help, rather than the subcommand not recognized help.

[epage]

We have an example of a cargo plugint https://docs.rs/clap/latest/clap/_derive/_cookbook/cargo_example_derive/index.html

Sounds like you are wanting it to work standalone and as a plugin. I generally recommend against that. If you still want to do it, check out our git-derive cookbook entry for git-derive stash which shows a "default subcommand".

[NathanFrasier]

I don't want to be that guy, but can you elaborate why you recommend against that? is it just more fragile or more complex?

I would expect most users of this tool would have cargo installed, so it's not a terrible loss if I limit it to use only as a cargo plugin, however I would prefer to not limit users ability to use this command only if they have cargo installed. Additionally, it simplifies the testing loop when doing development on the tool.

[NathanFrasier]

Looking at the git-derive cookbook, I think I understand what you are trying to suggest. however the use of a subcommand to consume the "toolchainer" that might exist seems fragile, I also can't get it to compile, because the "default subcommand" has a subcommand in it.

Here is my code thus far, currently not compiling:

#[derive(Parser)]
#[command(version, about, long_about = None)]
#[command(propagate_version = true)]
struct Cli {
    #[command(subcommand)]
    toolchainer: Option<Toolchainer>,

    #[command(flatten)]
    command: Commands,
}

// This only exists to try and consume the "toolchainer" arg that may exist if invoked as a cargo plugin
#[derive(Debug, Subcommand)]
enum Toolchainer {
    #[command(subcommand)]
    Command(Commands),
}

#[derive(Debug, Subcommand)]
enum Commands {
    Update(UpdateArgs),
    //TODO more commands in the future
}

The issue with the above is that the command field cannot be there, because it is a duplicate subcommand.

What I'm looking for is to simply discard the first arg if it matches an exact string. So my criteria for success is that the app should behave the same whether toolchainer is supplied after the bin arg or not. i.e. cargo run -- toolchainer update --help === cargo run -- update --help and cargo run -- toolchainer --help === cargo run -- --help

Is there a better way to do this, perhaps not using derive? I wouldn't be opposed to putting in some runtime handling code if it means that the above would work.

[epage]

I would expect most users of this tool would have cargo installed, so it's not a terrible loss if I limit it to use only as a cargo plugin, however I would prefer to not limit users ability to use this command only if they have cargo installed. Additionally, it simplifies the testing loop when doing development on the tool.

It is unnecessary complexity, adding more corner cases for things to go wrong or to not be as polished for little gain. If you have a binary that is meant to be run outside of cargo, name it as such. If its a cargo plugin, then its that.

The examples provided don't seem to explain which part is the "default subcommand" or what making it a "default subcommand" does. Those details are necessary to figure out how that is relevant to my issue.

Sorry, I had written that assuming a shared understanding of the git stash command. git stash <args> is shorthand for git stash push <args> When no subcommand is given to git stash, it is assumed that the subcommand is push. A way of framing your problem is that you are looking for cargo-plugin <args> to be a shorthand for cargo-plugin plugin <args>.

So you'd want something like

#!/usr/bin/env nargo
---
[dependencies]
clap = { version = "4", features = ["derive"] }
---
use clap::Parser;

#[derive(Parser, Debug)]
#[command(args_conflicts_with_subcommands = true)]
struct Cli {
    #[command(subcommand)]
    command: Option<CargoCli>,
    #[command(flatten)]
    args: Option<PluginArgs>,
}

#[derive(clap::Subcommand, Debug)]
enum CargoCli {
    #[command(hide = true)]
    #[command(bin_name = "cargo plugin")]
    #[command(display_name = "cargo plugin")]
    Plugin(PluginArgs),
}

#[derive(clap::Args, Debug)]
#[command(version, about, long_about = None)]
struct PluginArgs {
    some_arg: String
}

fn main() {
    let cli = Cli::parse();
    dbg!(cli);
}

Replace "Plugin" with the name of your plugin

• As you are trying to make cargo-plugin -h look like a regular command, I hide the subcommand (as it should only really be used by cargo) and I skipped setting the names to cargo
  • Skipping bin_name = "cargo"' has the downside that cargo plugin -h won't correctly say cargo plugin in the usage but will instead say cargo-plugin plugin. To fix this, clap would need to allow users to overwrite usage_name.
• flatten_help is more for how git stash behaves with the other subcommands, so I skipped that
• git stash should be updated to wrap StashPushArgs in an Option<_> like I did above. Doing this makes it easier to add required arguments to PluginArgs

[NathanFrasier]

The examples provided don't seem to explain which part is the "default subcommand" or what making it a "default subcommand" does. Those details are necessary to figure out how that is relevant to my issue.

Sorry, I had written that assuming a shared understanding of the git stash command. git stash is shorthand for git stash push When no subcommand is given to git stash, it is assumed that the subcommand is push. A way of framing your problem is that you are looking for cargo-plugin to be a shorthand for cargo-plugin plugin .

Firstly, I wrote that part while I was particularly frustrated, as such it had more than a little snark in it. I apologize for my tone.
Secondly, I think the disconnect was not with a shared understanding of git stash but understanding what specific parallels you were trying to draw to it. The framing of my problem as similar is what I was missing.

Lastly, I have adapted the code shown above. I'm not sure I fully understand it yet, but wanted to let you know it does appear to do what I want after tweaking it with the name changes. I'm curious if the slightly higher maintenance burden is really enough to suggest not to allow the dual approach. I suppose if this is something that clap "advises against" then there's no strong guarantee it will continue to work in future major version revisions.

For now, at least until I get a chance to look into it deeper, my questions are answered. Thanks!