Clap - getting started accepting command line parameters in Rust

Clap cli derive struct arg long help

A minimal example of using clap to handle command line parameters.

Create crate

cargo new simple-example
cd simple example

Add clap as a dependency

cargo add clap --features derive

As of this writing clap has two interfaces. The higher-level one and the recommended one is the derive interface. In order to use it we need to add the derive feature.

The resulting Cargo.toml file will look like this, though by the time you read this the version number will be probably higher.


name = "simple-example"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at

clap = { version = "4.4.11", features = ["derive"] }

The Code


use clap::Parser;

struct Cli {
    host: String,

fn main() {
    let args = Cli::parse();


If we just run the program in will complain of a missing command line parameter called --host, but also offer us the --help flag.

$ cargo run

error: the following required arguments were not provided:
  --host <HOST>

Usage: simple-example --host <HOST>

For more information, try '--help'.


cargo run --help

will give us help on cargo itself. Not what we wanted.

cargo run -- --help

will work fine and show us this help:

Usage: simple-example --host <HOST>

      --host <HOST>
  -h, --help         Print help

The extra -- is needed to separate the flags of cargo from those of your application.

Help in the compiled binary

However, don't worry. If you take the compiled binary (either the debug one or the released one later on), then the user does not need to provide the extra --:

Try this, for example:

./target/debug/simple-example  --help

Providing more detailed help message

In another article you can see how to provide additional text for the help message of each parameter separately by adding the help argument.

Passing the required parameter

cargo run -- --host

or if we would like to use the compiled binary directly then the -- is not needed:

./target/debug/simple-example  --host


We create a struct that will describe the command line parameters.

The name of the struct does not matter, but I like to call it Cli.

What is important is that it has the #[derive(Parser)] on it to add the cli::Parser trait.

The struct has one attribute called host having type String and we add the long argument so clap will expected a named command line flag.

    host: String,

Then we call the parse method that will return us an instance of the Cli struct.

    let args = Cli::parse();

Once we have this we can access the attribute of the struct for which the value was received from the command line.

Usage and Help

Clap automatically added the Usage message and the --help flag.

Related Pages

Clap - show version number of the command line application in Rust
Clap - accept string, integer, floating point numbers, booleans on the command line
Clap - Command Line Argument Parser for Rust
Clap - Add help text for each command line parameter in Rust


Gabor Szabo (szabgab)

Gabor Szabo, the author of the Rust Maven web site maintains several Open source projects in Rust and while he still feels he has tons of new things to learn about Rust he already offers training courses in Rust and still teaches Python, Perl, git, GitHub, GitLab, CI, and testing.

Gabor Szabo