Skip to content

Tutorial

Jump to bottom
idimus edited this page Jul 10, 2026 · 9 revisions

Step 1: get the library

First, clone the repository to your local disk.

You can get the library via git:

Alternatively, you can download a zip archive of the source code from this link. Unpack the zip file to the desired location.

If you put the library under your project's root, the "argparse.h" file will be found automatically. Otherwise, don't forget to add the library's location to your build system's include search paths.

After that, you can finally use the library.

Step 2: check the library is visible to your project

First, include the library in your C++ source file. It should look something like:

#include "ArgParse/argparse.h" or #include <argparse.h>, depending on where you put the file and where your build system searches for includes.

If the build succeeds, you can move on to the next step. If not, fix the include-related errors.

Step 3: using the library

First, create an instance of the argument parser:

auto parser = argparse::ArgumentParser("Program name").SetDescription("Description of program");

After that, you can add arguments through AddArgument with argparse::CreateNamedArgument() or argparse::CreatePositionalArgument(). For example:

// required argument of type int with name "numbers" and 1 or more arguments count
parser.AddArgument(argparse::CreateNamedArgument().SetLongName("numbers").SetAnyNumberOfArgumentsButAtLeastOne().SetType(argparse::ArgTypeCast::e_int));
// non required argument of type int with name "some_boring_long_name" and 1 or more arguments count and custom help
parser.AddArgument(argparse::CreateNamedArgument()
    .SetLongName("some_boring_long_name")
    .SetAnyNumberOfArgumentsButAtLeastOne()
    .SetType(argparse::ArgTypeCast::e_int)
    .SetHelp("some_boring_long_name description with some important information for user.")
    .SetRequired(false));

There are three interchangeable ways to describe an argument — pick whichever reads best for you:

  1. Fluent setters (shown above): CreateNamedArgument().SetLongName(...).SetType(...).
  2. Positional factory arguments: CreateNamedArgument("n", "numbers", nargs, type, required, help).
  3. Keyword style (C++20): pass an aggregate spec with designated initializers — reads like Python's add_argument(type=..., required=...). You name only the fields you need; the rest take their defaults:
// Same two arguments as above, C++20 keyword style
parser.AddArgument(argparse::CreateNamedArgument({
    .longName = "numbers",
    .nargs    = argparse::kFromOneToInfiniteArgCount,
    .type     = argparse::ArgTypeCast::e_int}));
parser.AddArgument(argparse::CreateNamedArgument({
    .longName = "some_boring_long_name",
    .nargs    = argparse::kFromOneToInfiniteArgCount,
    .type     = argparse::ArgTypeCast::e_int,
    .required = false,
    .help     = "some_boring_long_name description with some important information for user."}));

The spec structs are NamedArgSpec (fields: shortName, longName, nargs, type, required, help) and PositionalArgSpec (name, nargs, type, required, help). Options not covered by the struct — SetChoices, SetDefault — are chained on the returned argument, e.g. CreateNamedArgument({...}).SetDefault(1). Designated initializers require C++20; the same structs also work with plain aggregate initialization in earlier standards.

Once you've added all the arguments you need, pass the command-line arguments to the parser. You'll get an instance of argparse::ArgumentsObject. It reports an error if parsing failed, or lets you access the parsed arguments if parsing succeeded.

// pass argc and argv to parser
auto obj = parser.ParseArgs(argc, argv);
// check whether parsing succeeded
if (obj.IsArgValid())
{
    // retrieve the argument named "numbers"
    auto arg = obj.GetArg("numbers");
    // checking whether the argument exists is redundant here, since it is required
    if (arg.GetArgumentExists())
    {
        // iterate through the input
        for (auto& el : arg.GetAsVecInt())
        {
            std::cout << el << std::endl;
        }
    }
}
else
{
    // 80 is the width of your terminal
    std::string help = parser.GetHelp(80);
    std::cout << help << std::endl;
}

If parsing fails, this example prints the following help to the console:

Program name -n,--numbers [n ...] [-s,--some_boring_long_name [s ...] ] -h,--help
Description of program

optional arguments:

-n,--numbers            Type: INT. Args count: at least one.
-s,--some_boring_long_name
                        some_boring_long_name description with some important information
                        for user. Type: INT. Args count: at least one.
-h,--help               Show help!

Notes:

The argparse::ArgumentParser::AddArgument function can throw an error that indicates a malformed argument. You don't need a try/catch block here — just run the program and fix the mistakes using the hints in the exception message.

For more details please see the Classes overview, examples, and Doxygen documentation.

Clone this wiki locally