{"id":50335311,"url":"https://github.com/bdombro/cpp-argsbarg","last_synced_at":"2026-05-29T13:01:46.964Z","repository":{"id":352185558,"uuid":"1214200473","full_name":"bdombro/cpp-argsbarg","owner":"bdombro","description":"A small C++23 header-only toolkit for pretty CLIs with sh completions.","archived":false,"fork":false,"pushed_at":"2026-04-18T09:30:24.000Z","size":37,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T10:34:42.212Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bdombro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2026-04-18T08:45:53.000Z","updated_at":"2026-04-18T09:30:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bdombro/cpp-argsbarg","commit_stats":null,"previous_names":["bdombro/cpp-argsbarg"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bdombro/cpp-argsbarg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fcpp-argsbarg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fcpp-argsbarg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fcpp-argsbarg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fcpp-argsbarg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdombro","download_url":"https://codeload.github.com/bdombro/cpp-argsbarg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fcpp-argsbarg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33652986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-29T13:01:46.283Z","updated_at":"2026-05-29T13:01:46.958Z","avatar_url":"https://github.com/bdombro.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Logo](logo.png)\n\u003c!-- Big money NE - https://patorjk.com/software/taag/#p=testall\u0026f=Bulbhead\u0026t=shebangsy\u0026x=none\u0026v=4\u0026h=4\u0026w=80\u0026we=false\u003e --\u003e\n\n[![GitHub](https://img.shields.io/badge/GitHub-bdombro%2Fcpp--argsbarg-181717?logo=github)](https://github.com/bdombro/cpp-argsbarg)\n\n[![CI](https://github.com/bdombro/cpp-argsbarg/actions/workflows/ci.yml/badge.svg)](https://github.com/bdombro/cpp-argsbarg/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![C++23](https://img.shields.io/badge/C%2B%2B-23-00599C?logo=cplusplus\u0026logoColor=white)](CONTRIBUTING.md#prerequisites)\n[![Linux](https://img.shields.io/badge/Linux-supported-yellowgreen?logo=linux\u0026logoColor=black)](CONTRIBUTING.md#prerequisites)\n[![macOS](https://img.shields.io/badge/macOS-supported-yellowgreen?logo=apple\u0026logoColor=white)](CONTRIBUTING.md#prerequisites)\n\nBuild beautiful, well-behaved CLI apps in modern C++ — no macros, no runtime dependencies, just a single header.\n\n**ArgsBarg** is *schema-first* -- define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear and self-describing upfront. `cpp-argsbarg` has siblings --\u003e [bun](https://github.com/bdombro/bun-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg).\n\nHalps! --\u003e\n![help-preview.png](docs/help-preview.png)\n\nSub-level Halps! --\u003e\n![help-l2-preview.png](docs/help-l2-preview.png)\n\nShell completions! --\u003e\n![completions-preview.png](docs/completions-preview.png)\n\nEverything you need for a first-class CLI:\n\n- Nested subcommands\n- POSIX-style options (`-x`, `--long`, `--long=value`)\n- Arg/option validation with contextual error messages\n- Scoped help at any routing depth\n- Default-command fallback\n- Bash and zsh completion scripts — generated at runtime, no extra tooling\n- Zero macros, zero third-party runtime dependencies\n\n## Platforms and stability\n\n- **Platforms:** **Linux** and **macOS** (POSIX). The headers use POSIX APIs for TTY detection (e.g. help styling); Windows isn't in scope for this release line.\n- **CMake:** 3.21+ (`find_package` config + install).\n- **API stability:** pre-1.0 SemVer — minor versions may include breaking changes. See [`CHANGELOG.md`](CHANGELOG.md) and [`feature-spec.md`](feature-spec.md) for details.\n\n---\n\n## Usage\n\n```cpp\n#include \u003cargsbarg/argsbarg.hpp\u003e\n#include \u003ciostream\u003e\n\nusing namespace argsbarg;\n\nint main(int argc, const char* argv[]) {\n    auto greet = [](Context\u0026 ctx) {\n        const auto name = ctx.string_opt(\"name\").value_or(\"world\");\n        if (ctx.flag(\"verbose\")) {\n            std::cout \u003c\u003c \"verbose mode\\n\";\n        }\n        std::cout \u003c\u003c \"hello \" \u003c\u003c name \u003c\u003c '\\n';\n    };\n\n    Application{\"helloapp\"}\n        .description(\"Tiny demo.\")\n        .fallback(\"hello\", FallbackMode::MissingOrUnknown)\n        .command(Leaf{\"hello\", \"Say hello.\"}\n            .handler(greet)\n            .option(Opt{\"name\", \"Who to greet.\"}.string().short_alias('n'))\n            .option(Opt{\"verbose\", \"Enable extra logging.\"}.short_alias('v')))\n        .run(argc, argv);\n}\n```\n\n---\n\n## Install\n\nThe imported target is always `argsbarg::argsbarg`, regardless of which method you use.\n\n### Option 1 — CMake `FetchContent` (no install step)\n\nCMake downloads the source at configure time and builds it alongside your project. Good for small teams and single-repo setups.\n\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(argsbarg\n    GIT_REPOSITORY https://github.com/bdombro/cpp-argsbarg.git\n    GIT_TAG        v0.5.0)\n# When embedding, examples and tests default to OFF (set ON if you want them).\n# You can still force them OFF explicitly:\n# set(ARGSBARG_BUILD_EXAMPLES OFF CACHE BOOL \"\" FORCE)\n# set(ARGSBARG_BUILD_TESTS    OFF CACHE BOOL \"\" FORCE)\nFetchContent_MakeAvailable(argsbarg)\n\ntarget_link_libraries(your_target PRIVATE argsbarg::argsbarg)\n```\n\n### Option 2 — `cmake --install` + `find_package`\n\nInstall once to a prefix, then any project on the machine can find it without cloning the repo.\n\n**Install:**\n\n```bash\n# Clone and install to ~/.local (or any prefix you choose)\ngit clone https://github.com/bdombro/cpp-argsbarg.git\ncd cpp-argsbarg\ncmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=\"$HOME/.local\"\ncmake --build build -j\ncmake --install build --component argsbarg_Development\n```\n\nOr from inside the repo: `PREFIX=\"$HOME/.local\" just install`.\n\n**Consume:**\n\n```cmake\nlist(APPEND CMAKE_PREFIX_PATH \"$ENV{HOME}/.local\") # match your install prefix\nfind_package(argsbarg 0.5.0 CONFIG REQUIRED)\n\ntarget_link_libraries(your_target PRIVATE argsbarg::argsbarg)\n```\n\nThe imported target **`argsbarg::argsbarg`** propagates **C++23** via `INTERFACE` compile features.\n\n### Option 3 — Conan (optional)\n\nThis repository ships a **Conan 2** recipe ([`conanfile.py`](conanfile.py)) and [`test_package/`](test_package/) for local validation:\n\n```bash\nconan create . --build=missing -s compiler.cppstd=23\n```\n\nTo publish on **Conan Center**, contribute a recipe via [conan-center-index](https://github.com/conan-io/conan-center-index/blob/master/docs/how_to_add_packages.md) (often based on the in-repo `conanfile.py`).\n\n---\n\n## Built-ins\n\nEvery app processed by `run()` gains:\n\n- `-h` / `--help` at any routing depth (scoped help).\n- `completion bash` — prints a bash completion script to **stdout**.\n- `completion zsh` — prints a zsh completion script to **stdout** (same pattern as bash).\n\nThe top-level name `completion` is reserved for the built-in group.\n\n---\n\n## How it works\n\nThere are really only three concepts to learn:\n\n1. Describe a tree with `Group` / `Leaf` and `Opt` / `Arg` fluent builders (see [`include/argsbarg/builders.hpp`](include/argsbarg/builders.hpp)).\n2. `Application::run` or `run(schema, argc, argv)` merges built-ins, validates the schema, parses argv, renders help or errors, dispatches the leaf handler, and `std::exit`s with the codes in [`feature-spec.md`](feature-spec.md) §8.\n3. From a handler, `err_with_help(ctx, \"message\")` prints a red error line plus contextual help on stderr and exits with status 1.\n4. `parse(merged_schema, argv_words)` and `help_render(merged_schema, path)` are pure helpers for tests and custom hosts (no I/O, no exit).\n\n### Fallback modes (`FallbackMode`)\n\n| Mode | Empty argv | Unknown first token |\n| --- | --- | --- |\n| `MissingOnly` | Default command | Error |\n| `MissingOrUnknown` | Default command | Default command (token becomes argv for the default) |\n| `UnknownOnly` | Root help (exit 1) | Default command |\n\nWith `MissingOrUnknown` / `UnknownOnly`, unrecognized **root** flags stop root-flag consumption and the remainder is passed to the default command (see [`feature-spec.md`](feature-spec.md) §5.3).\n\n### Positionals (help labels)\n\n| Builder | Help label |\n| --- | --- |\n| `Arg{\"n\", \"…\"}` | `\u003cn\u003e` |\n| `Arg{\"n\", \"…\"}.optional()` | `[n]` |\n| `Arg{\"f\", \"…\"}.min(0)` | `[f...]` |\n| `Arg{\"f\", \"…\"}.min(1)` | `\u003cf...\u003e` |\n| `Arg{\"f\", \"…\"}.min(1).max(3)` | `\u003cf...\u003e` (one to three words) |\n\n### Reading values (`Context`)\n\n- `ctx.flag(\"verbose\")` — presence options.\n- `ctx.string_opt(\"name\")` / `ctx.number_opt(\"count\")` — `std::optional`.\n- `ctx.args()` — positional words in order.\n- `ctx.schema()` — merged schema (for help paths in errors).\n\n---\n\n## Examples\n\nThis repository ships two demos under `examples/`, each with its own `justfile` so you can work inside the example directory.\n\n| Directory | Shows |\n| --- | --- |\n| `examples/minimal/` | Fluent `Application`, string + presence flags, `MissingOrUnknown` fallback. |\n| `examples/nested/` | Nested `Group`s, `Arg` tails, `UnknownOnly` + path-like default to `read`. |\n\nFrom the repo root:\n\n```bash\njust example-minimal ARGS='hello --name world'\njust example-nested ARGS='stat owner lookup --user-name alice ./README.md'\n```\n\nOr enter an example directory:\n\n```bash\ncd examples/minimal \u0026\u0026 just build \u0026\u0026 just run ARGS='hello -h'\n```\n\n---\n\n## Shell completions\n\n```bash\nmyapp completion bash \u003e ~/.bash_completion.d/myapp   # or: source \u003c(myapp completion bash)\nmyapp completion zsh \u003e ~/.zsh/completions/_myapp     # underscore name; ensure dir is on fpath\n```\n\n---\n\n## Public API overview\n\n| Header | Contents |\n| --- | --- |\n| [`include/argsbarg/argsbarg.hpp`](include/argsbarg/argsbarg.hpp) | Umbrella: `version()`, `run`, `err_with_help`, includes the rest. |\n| [`include/argsbarg/schema.hpp`](include/argsbarg/schema.hpp) | `Schema`, `Command`, `Option`, `FallbackMode`, `find_child`, `find_option_by_name`. |\n| [`include/argsbarg/builders.hpp`](include/argsbarg/builders.hpp) | Fluent `Leaf`, `Group`, `Opt`, `Arg`. |\n| [`include/argsbarg/application.hpp`](include/argsbarg/application.hpp) | Fluent `Application`. |\n| [`include/argsbarg/context.hpp`](include/argsbarg/context.hpp) | `Context` passed to handlers. |\n| [`include/argsbarg/parse.hpp`](include/argsbarg/parse.hpp) | `schema_validate`, `parse`, `post_parse_validate`. |\n| [`include/argsbarg/help.hpp`](include/argsbarg/help.hpp) | `help_render`, `help_render_stderr`. |\n| [`include/argsbarg/builtins.hpp`](include/argsbarg/builtins.hpp) | `merge_builtins`, completion path helpers. |\n| [`include/argsbarg/completion.hpp`](include/argsbarg/completion.hpp) | `completion_bash_script`, `completion_zsh_script` (string only; hosts print to stdout). |\n| [`include/argsbarg/schema_error.hpp`](include/argsbarg/schema_error.hpp) | `SchemaError` (`std::logic_error`). |\n\n---\n\n## Contributing\n\nContributions welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md). Security reports: [`SECURITY.md`](SECURITY.md). Community standards: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fcpp-argsbarg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdombro%2Fcpp-argsbarg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fcpp-argsbarg/lists"}