{"id":44377055,"url":"https://github.com/igormironchik/args-parser","last_synced_at":"2026-02-11T21:13:21.003Z","repository":{"id":28623728,"uuid":"32142460","full_name":"igormironchik/args-parser","owner":"igormironchik","description":"args-parser is a small C++ header-only library for parsing command line arguments.","archived":false,"fork":false,"pushed_at":"2026-01-02T05:58:56.000Z","size":5328,"stargazers_count":91,"open_issues_count":0,"forks_count":17,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-01-07T23:31:49.221Z","etag":null,"topics":["argument-parser","arguments","c-plus-plus","cli","command-line","cpp","header-only","parser","qt","subcommands"],"latest_commit_sha":null,"homepage":"http://igormironchik.github.io/args-parser/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igormironchik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-03-13T08:17:15.000Z","updated_at":"2026-01-02T05:58:59.000Z","dependencies_parsed_at":"2023-11-09T16:25:33.276Z","dependency_job_id":"82e6325b-5097-4085-acb3-ca6bd650eb0a","html_url":"https://github.com/igormironchik/args-parser","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/igormironchik/args-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igormironchik%2Fargs-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igormironchik%2Fargs-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igormironchik%2Fargs-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igormironchik%2Fargs-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igormironchik","download_url":"https://codeload.github.com/igormironchik/args-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igormironchik%2Fargs-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29345433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T20:11:40.865Z","status":"ssl_error","status_checked_at":"2026-02-11T20:10:41.637Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argument-parser","arguments","c-plus-plus","cli","command-line","cpp","header-only","parser","qt","subcommands"],"created_at":"2026-02-11T21:13:19.379Z","updated_at":"2026-02-11T21:13:20.996Z","avatar_url":"https://github.com/igormironchik.png","language":"C++","readme":"\u003c!--\n\tSPDX-FileCopyrightText: 2013-2024 Igor Mironchik \u003cigor.mironchik@gmail.com\u003e\n\tSPDX-License-Identifier: MIT\n--\u003e\n\nThis is `args-parser`.\n\n`args-parser` is a small C++ header-only library for parsing command line arguments.\n\n* [Syntax](#syntax)\n* [Different types of strings.](#different-types-of-strings)\n* [Different types of list of strings.](#different-types-of-list-of-strings)\n* [Q/A](#qa)\n  * [Why not to add description, long description, etc. into constructors of arguments, so it will be possible to initialize argument in one line?](#why-not-to-add-description-long-description-etc-into-constructors-of-argumentsso-it-will-be-possible-to-initialize-argument-in-one-line)\n  * [How can I add `args-parser` to my project?](#how-can-i-add-args-parser-to-my-project)\n  * [Why should I use this library?](#why-should-i-use-this-library)\n  * [How to print help programmatically?](#how-to-print-help-programmatically)\n  * [Why doesn't `args-parser` provide bindings of variables to arguments?](#why-doesnt-args-parser-provide-bindings-of-variables-to-arguments)\n  * [Why don't you provide comparisons with other CLI libraries?](#why-dont-you-provide-comparisons-with-other-cli-libraries)\n* [Changelog](#changelog)\n* [Example](#example)\n  * [One-line syntax with commands](#one-line-syntax-with-commands)\n  * [One-line syntax with arguments](#one-line-syntax-with-arguments)\n  * [And with the old syntax](#and-with-the-old-syntax)\n\n# Syntax\n\n * An argument starts with two dashes. For example `--argument`.\n * A flag starts with one dash. For example `-b`.\n * If an argument has a value, then the value can be specified after a space or after an equal sign.\nFor example `--argument value` and `--argument=value`.\n * Flags without values can be combined into one block. For example\n`-abc` defines three flags `-a`, `-b` and `-c`.\n * The last flag in a flags' block can have a value. For example `-abc=value`. And here, flag `-c` will have the value `value`.\n * `MultiArg` class provides the ability to define more than one value for an argument. These types\nof arguments can be specified more than once in the command line. And the resulted value\nof the argument will be `StringList`.\n * `Command` class can be used to define command in command line interface.\nCommand is the argument without dash/dashes at the beginning, `add` for example.\n * `Command` can has children arguments or even subcommands.\n * In `args-parser` groups can be used to group arguments into groups to check their\ndefinitions after parsing, so if constraint of group will be violated\nexception will be thrown.\n * `args-parser` provides `Help` argument that provides help printing. `Help`\nuses `-h, --help` arguments. `Help` can receive value with name\nof argument or command to print help about. If `Help` receives the name\nof a command as the value, then the name of a subcommand or a child argument\ncan also be provided as the next value, to get help about the subcommand/child argument.\n * If `args-parser` don't know about argument in command line interface it provides\ninformation about possible arguments if some misspelling was in command\nline interface. If `args-parser` can't assume anything about entered argument it\nwill just say about unknown argument through the exception and parsing will\nfail.\n * With `CmdLine::HandlePositionalArguments` option provided to `CmdLine`\nconstructor, `args-parser` will handle positional arguments, these are such arguments\nthat can't be parsed with provided arguments, flags, commands and stay at the end\nof the command line. Be careful with combining `MultiArg` and positional arguments,\nbecause `MultiArg` can eat almost everything that is not a valid argument.\n\n# Different types of strings.\n\nSince version `4.0.0` `args-parser` can be built with different strings - `std::string`,\n`std::wstring` and `QString`.\n\n * To build `args-parser` with `std::wstring` support define `ARGS_WSTRING_BUILD`\n * To build `args-parser` with `QString` support define `ARGS_QSTRING_BUILD`\n * If nothing was defined then `args-parser` will be build with `std::string`.\n\n# Different types of list of strings.\n\n`args-parser` extensively uses list of string in internal structures and to return\nvalues of arguments outside. In the code this is `StringList`\ntype defined in `args-parser/types.hpp`. By default underlying type is\n`std::vector` or `QVector` when building with Qt that can be changed\nto `std::list`, `QLinkedList` or `std::deque`, `QList`.\n\n * Define `ARGS_LIST` to build `args-parser` with `std::list`, `QLinkedList`\nas `StringList`\n * Define `ARGS_DEQUE` to build `args-parser` with `std::deque`, `QList`\nas `StringList`\n\n# Q/A\n\nWhy not to add description, long description, etc. into constructors of arguments,\nso it will be possible to initialize argument in one line?\n---\n\n * This is impossible because constructors will be ambiguous but you can use\nauxiliary API that allows to define arguments in one line of code.\n\nHow can I add `args-parser` to my project?\n---\n\n * The simplest way is just copy `args-parser` directory with headers to any location in\nyour project. With CMake you can clone entire `args-parser` project somewhere in your\nproject and just do `add_subdirectory()`, if you will do so you have to\nadd include directory path to your project with\n`include_directories( ${args-parser_INCLUDE_DIRECTORIES} )`.\n\n * You can clone/download `args-parser`, build and install it with CMake. In this\ncase it will be possible to use `find_package( args-parser )` in `CMakeLists.txt` of\nyour project.\n\n * You can use `Conan` package manager.\n\nWhy should I use this library?\n---\n\n * There are tons of libraries for parsing command line arguments on the\nInternet. But `args-parser` also provides the possibility to define commands, like\n\n    ```\n    git add -A\n    git commit\n    git push\n    ```\n\n    Help output is very user-friendly.\n\n    If you need only simple arguments in style `--do-it \u003cvalue\u003e` then possibly\n    you will find another library more useful for you, but who knows...\n\nHow to print help programmatically?\n---\n\n * For those, who use old style syntax the answer should be on the plate, as developer\ncan look at the code of `Help` class, that implements help argument. But for those, who\nprefer one-line syntax the answer can be not so evident, but it's so too. It doesn't matter\nwhat syntax you use, new (one-line) syntax is just a wrapper for old one. I.e. line:\n\n   ```cpp\n   cmd.addHelp( true, argv[ 0 ],\n     \"This application just show power of the Args help.\" );\n   ```\n\n   Is just a wrapper around of `Help` class. For printing help `args-parser` uses\n   `HelpPrinter` class. So developer can use it for printing help in some rare cases,\n   as:\n\n   ```cpp\n   HelpPrinter printer;\n\n   printer.setExecutable( argv[ 0 ] );\n   printer.setAppDescription( \"This application just show power of the Args help.\" );\n   printer.setLineLength( length );\n   printer.setCmdLine( cmd );\n\n   printer.print( outStream() );\n   ```\n\nWhy doesn't `args-parser` provide bindings of variables to arguments?\n---\n\n * This is a question of why doesn't `args-parser` provide validators? It's the same.\nI decided that this aspect is very application specific. There is no need for such library\nto do any conversions of arguments' values, to bind them to some variables. This will\ndo API very complex only. I know what you will say: this is very nice feature, it helps...\nReally? How often and how much it helped you? Arguments parser should handle the string\nthat user provided to the application, it should separate arguments, commands, values,\nstore it in internal state of parser, and allow to developer just write some `if`\noperators to choose branch of the program logic. What will give you, as to developer,\nif values will be bind to concrete variables? Will not you write the same code with `if`\noperators? So why I should do the library more complex?\n\nWhy don't you provide comparisons with other CLI libraries?\n---\n\n * I found only one library at GitHub that can compete with `args-parser`, and this is\n[CLI11](https://github.com/CLIUtils/CLI11). And here is the question of the taste more.\nBut `CLI11` can handle commands as usual arguments, it's doesn't matter how much times\nthey present in command line, whereas `args-parser` handles commands as commands. Theirs\napproach possibly more flexible, but when I designed `args-parser` I thought on commands\nas on some action to do in application's logic, whereas arguments are for data. I can do\nthe same, but is it needed?\n\n   `CLI11` has possibility to set formatter of the help, `args-parser` allow to set\n   custom `HelpPrinterIface` on the `Help` argument. But who and when will do it?\n   And I believe that help in `args-parser` is a little better than in `CLI11`.\n\n   `CLI11` works more with callbacks, whereas `args-parser` uses hierarchy of\n   classes with polymorphism. In `args-parser` you can inherit from any argument's\n   class, override methods you need and receive something very application specific.\n   And again, this is more question of taste.\n   \n   Uh, oh, I found one more interesting arguments parsing library, This is\n   [Taywee/Args](https://github.com/Taywee/args). Guys, this is a question of taste.\n   And, as said in `CLI11` documentation about `Taywee/Args`, `args-parser` as\n   `CLI11` less verbose. `Taywee/Args` has benchmark to compare performance with\n   `TCLAP` and `boost::program_options.`, I want to say that `args-parser` 2 times\n   faster than `Taywee/Args`, dry numbers says that `Tyawee/Args` runs 0.635314\n   second, whereas `args-parser` runs 0.346813 second.\n   \n   What I want to say about minuses of `args-parser`is that I don't support other\n   delimiter characters than `-` for flags and `--` for arguments.\n\n# Changelog\n\n| Version | Changes |\n| --- | --- |\n| **6.3.5** | Added printing of default value in the help. Added possibility to split description by paragraphs with `\\n` in the description. Too long words in the help splits now if they don't fit in. |\n| **6.3.4** | Fixed issue with `MSVC` when globally defined `::Command` class was detected as friend of `ArgIface` instead of `Args::Command` |\n| **6.3.3** | Minor fix for compilation with `-Werror=shadow` |\n| **6.3.2** | Fixed multiple definitions when included from different compile units. |\n| **6.3.1** | Improved performance. Added possibility to set positional arguments string for the help. Added benchmark. |\n| **6.3.0** | Added possibility to handle positional arguments. |\n| **6.2.0.1** | Ready for use with Qt6. |\n| **6.2.0.0** | Allowed to inherit from some classes. Added `addArg()` methods into API. |\n| **6.1.1.1** | Added possibility to set up custom help printer in help argument. |\n| **6.1.1.0** | Improved API with new syntax, now it's impossible to mess with end() methods. Fixed issue with printing help of global argument under command. |\n| **6.1.0.0** | Added possibility to add `Command` into groups. |\n| **6.0.0.0** | In this version was removed `ArgAsCommand` class, and was added fully-featured support for sub-commands, that can be created with `Command` class, i.e. `Command` can has `Command` as child. So it's possible to create such CLI as `git submodule update --init --recursive`. |\n\n# Example\n\nFirst of all you must know that practically all classes of the `args-parser` throws exceptions on errors\nand there is one specific exceptions that inform you about that that help was shown. This specific\nexception (HelpHasBeenPrintedException) is needed for processing program's logic that usually stops\nexecution at this point.\n\nSince version `5.0.0` `args-parser` provides two API: the old one and auxiliary API\nthat allows to define arguments in one line of code. Let's look.\n\n## One-line syntax with commands\n\n```cpp\n// args-parser include.\n#include \u003cargs-parser/all.hpp\u003e\n\nusing namespace Args;\n\nint main( int argc, char ** argv )\n{\n  try {\n    CmdLine cmd( argc, argv, CmdLine::CommandIsRequired );\n\n    cmd.addCommand( \"add\", ValueOptions::NoValue, true, \"Add file.\" )\n        .addCommand( \"file\", ValueOptions::ManyValues, false, \"File name.\", \"\", \"\", \"fn\" )\n        .end()\n      .end()\n      .addCommand( \"delete\", ValueOptions::NoValue, true, \"Delete file.\" )\n        .addCommand( \"file\", ValueOptions::ManyValues, false, \"File name.\", \"\", \"\", \"fn\" )\n        .end()\n      .end()\n      .addHelp( true, argv[ 0 ],\n        \"This application just show power of the args-parser help.\" );\n\n    cmd.parse();\n\n    if( cmd.isDefined( \"file\" ) )\n      for( const auto \u0026 fn : cmd.values( \"file\" ) )\n        outStream() \u003c\u003c fn \u003c\u003c \"\\n\";\n  }\n  catch( const HelpHasBeenPrintedException \u0026 )\n  {\n    return 0;\n  }\n  catch( const BaseException \u0026 x )\n  {\n    outStream() \u003c\u003c x.desc() \u003c\u003c \"\\n\";\n\n    return 1;\n  }\n\n  return 0;\n}\n```\n\n## One-line syntax with arguments\n\n```cpp\n#include \u003cargs-parser/all.hpp\u003e\n\nusing namespace Args;\n\nvoid process( bool b, const std::string \u0026 value )\n{\n  outStream() \u003c\u003c \"Boolean: \" \u003c\u003c b \u003c\u003c \" , value: \\\"\" \u003c\u003c value \u003c\u003c \"\\\"\\n\";\n}\n\nint main( int argc, char ** argv )\n{\n  try {\n    CmdLine cmd( argc, argv );\n\n    cmd.addArgWithFlagAndName( 'b', \"bool\", false, false, \"Boolean flag\",\n        \"Boolean flag, used without value\" )\n      .addArgWithFlagAndName( 'v', \"value\", true, false, \"With value\",\n        \"Argument with value\", \"\", \"VAL\" )\n      .addHelp( true, argv[ 0 ], \"CLI with boolean and value.\" );\n\n    cmd.parse();\n\n    bool b = false;\n    std::string value;\n\n    if( cmd.isDefined( \"-b\" ) )\n      b = true;\n\n    if( cmd.isDefined( \"-v\" ) )\n      value = cmd.value( \"-v\" );\n\n    process( b, value );\n  }\n  catch( const HelpHasBeenPrintedException \u0026 )\n  {\n    return 0;\n  }\n  catch( const BaseException \u0026 x )\n  {\n    outStream() \u003c\u003c x.desc() \u003c\u003c \"\\n\";\n\n    return 1;\n  }\n\n  return 0;\n}\n```\n\n## And with the old syntax\n\n\n```cpp\n// args-parser include.\n#include \u003cargs-parser/all.hpp\u003e\n\n// C++ include.\n#include \u003ciostream\u003e\n\n\nint main( int argc, char ** argv )\n{\n  try {\n    /*\n      We create Args::CmdLine instance for parsing\n      command line arguments.\n    */\n    Args::CmdLine cmd( argc, argv );\n\n    /*\n      And create our arguments.\n    */\n\n    /*\n      This is argument with flag \"-o\" and name \"--host\".\n      He is with value and required.\n    */\n    Args::Arg host( 'o', \"host\",\n      // Argument is with value.\n      true,\n      // Argument is required.\n      true );\n    // Set description of the argument.\n    host.setDescription( \"Host. Can be \\\"localhost\\\", \\\"any\\\" or regular IP.\" );\n    // We can specify long description too.\n    host.setLongDescription( \"Host. This argument told to the application \"\n      \"where to open socket for communication.\" );\n\n    Args::Arg port( 'p', \"port\", true, true );\n    port.setDescription( \"Port number to create socket.\" );\n\n    /*\n      This argument have name \"--timeout\" only.\n      He is with value but optional.\n    */\n    Args::Arg timeout( \"timeout\", true );\n    // This argument want to specify value specifier in the help. Let's do it.\n    timeout.setValueSpecifier( \"ms\" );\n    timeout.setDescription( \"Timeout before new messages will be sent \"\n      \"in milliseconds.\" );\n\n    /*\n      We create help now.\n    */\n    Args::Help help;\n    // Set executable name to the help printer.\n    help.setExecutable( argv[ 0 ] );\n    // And set description of the application.\n    help.setAppDescription( \"This application just show \"\n      \"the power of args-parser.\" );\n\n    /*\n      Now add our argument to the command line.\n    */\n    cmd.addArg( host );\n    cmd.addArg( port );\n    cmd.addArg( timeout );\n    cmd.addArg( help );\n\n    /*\n      Now parse our arguments.\n    */\n    cmd.parse();\n\n    if( timeout.isDefined() )\n      auto timeoutValue = timeout.value();\n  }\n  catch( const Args::HelpHasBeenPrintedException \u0026 )\n  {\n    return 0;\n  }\n  catch( const Args::BaseException \u0026 x )\n  {\n    std::cout \u003c\u003c x.what() \u003c\u003c \"\\n\";\n\n    return 1;\n  }\n\n  return 0;\n}\n```\n\nHelp output for the example with the old syntax.\n\n```txt\nThis application just show the power of args-parser.\n\nUSAGE: sample.help.exe -s, --host \u003carg\u003e -p, --port \u003carg\u003e [ -h, --help \u003carg\u003e ]\n       [ --timeout \u003cms\u003e ]\n\nREQUIRED:\n -s, --host \u003carg\u003e   Host. Can be \"localhost\", \"any\" or regular IP.\n\n -p, --port \u003carg\u003e   Port number to create socket.\n\nOPTIONAL:\n -h, --help \u003carg\u003e   Print this help.\n\n     --timeout \u003cms\u003e Timeout before new messages will be sent in milliseconds.\n```\n\n*That's it. Use it and enjoy it. Good luck.*\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figormironchik%2Fargs-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figormironchik%2Fargs-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figormironchik%2Fargs-parser/lists"}