{"id":21047068,"url":"https://github.com/thecalcaholic/bash-args","last_synced_at":"2026-02-19T06:02:34.009Z","repository":{"id":79248766,"uuid":"338833575","full_name":"theCalcaholic/bash-args","owner":"theCalcaholic","description":"An argument parsing library for bash scripts","archived":false,"fork":false,"pushed_at":"2022-05-16T17:11:09.000Z","size":38,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-23T17:03:14.601Z","etag":null,"topics":["argument-parser","bash","bash-script","bash-scripting","shell-script"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/theCalcaholic.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-02-14T15:17:10.000Z","updated_at":"2024-03-01T17:32:09.000Z","dependencies_parsed_at":"2023-05-29T10:15:25.554Z","dependency_job_id":null,"html_url":"https://github.com/theCalcaholic/bash-args","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/theCalcaholic/bash-args","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theCalcaholic%2Fbash-args","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theCalcaholic%2Fbash-args/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theCalcaholic%2Fbash-args/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theCalcaholic%2Fbash-args/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theCalcaholic","download_url":"https://codeload.github.com/theCalcaholic/bash-args/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theCalcaholic%2Fbash-args/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29604552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T05:11:50.834Z","status":"ssl_error","status_checked_at":"2026-02-19T05:11:38.921Z","response_time":117,"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","bash","bash-script","bash-scripting","shell-script"],"created_at":"2024-11-19T14:35:20.656Z","updated_at":"2026-02-19T06:02:33.966Z","avatar_url":"https://github.com/theCalcaholic.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bash args\n\n*Producing quality scripts with ease.*\n\n## Description\n\nbash-args is a small library which does the heavy-lifting for all your argument parsing needs (if not: [request a feature][gh-issues] :P) for your bash scripts.\nWritten originally for my own [bash-utils][bash-utils-repo].\n\n## How do I use it?\n\nSource the library, then define keyword and required arguments and call the `parse_args` function.\nIf you want to create a self-contained script with this library, you could use [bundle-script.sh][bundle-script] (which is what I do myself).\n\nExample (You can find this and more examples in the [examples](./examples) folder):\n\n```bash\n# Source the library\n. \"$(cd \"${BASH_SOURCE[0]%/*}/..\"; pwd)/parse_args.sh\"\n\n# Define the keywords to use for (optional) keyword arguments. You can define aliases by separating parameter names with the pipe symbol |\n# If using aliases, you for all purposes the first name in the list will be used (see below)\nKEYWORDS=(\"--config\" \"-i|--interactive;bool\" \"-s|--sleep;int\" \"--letter;list\")\n# Define required positional arguments\nREQUIRED=(\"username\")\n\n# Define a description which will be used in the --help message\nDESCRIPTION=\"A dummy function to showcase the bash-args library\"\n\n# Define usage information for your arguments which will be used in the aut-generated usage message, e.g. when the --help argument was given\n# Alternatively, you can define USAGE as a single string which will then replace the usage message generator\ndeclare -A USAGE\nUSAGE[--config]=\"Read configuration from a file\"\nUSAGE['-i']=\"Ask before doing anything dangerous\"\nUSAGE['-s']=\"Sleep \u003cnumber\u003e seconds before doing anything\" # Always use the first parameter name in your script if there are aliases\nUSAGE[username]=\"Your username\"\nUSAGE[\"--letter\"]=\"Provide some letters\"\n# Optionally, you can also set USAGE['COMMAND']. Otherwise, parse-args will defer the command name from your script\n\n# Parse all arguments in \"$@\" and exit if there are parsing errors\nparse_args \"$@\" || exit $?\n\n# Show the usage message on specific exit codes in your script\nset_trap 1 2\n\n# Retrieve the arguments\n\necho \"Your arguments:\"\necho \"username: ${NAMED_ARGS['username']}\"\necho \"config: ${KW_ARGS['--config']}\"\n# -i will always be set, because bools have a default value of \"false\"\necho \"interactive: ${KW_ARGS['-i']}\" \n# list type arguments allow you to supply the argument multiple times. The arguments will be stored to KW_ARGS \n# separated by newlines\necho \"Your letters: ${KW_ARGS['--letter']//$'\\n'/, }\"\n\n# Set a default value for the sleep argument\nsleep=\"${KW_ARGS['-s']:-0}\"\necho \"sleep: $sleep\"\necho \"any other args you provided: ${ARGS[*]}\"\n```\n\n### What does this get me?\n\nLet's say, you saved the example above as `example.sh` (don't forget adding a shebang and making it executable). Now, you'd get the following behavior:\n\n1. If you to call your script with `--help`, you get your usage instructions:\n\n  ```sh\n  $ ./examples/demo.sh --help\n  A dummy function to showcase the bash-args library\n  \n  USAGE:\n    demo.sh [--config] [-i|--interactive] [-s|--sleep] [--letter] username\n      username    Your username\n  \n    OPTIONS:\n      --sleep \u003cnumber\u003e, -s \u003cnumber\u003e    Sleep \u003cnumber\u003e seconds before doing anything\n      --config \u003cvalue\u003e                 Read configuration from a file\n      --interactive, -i                Ask before doing anything dangerous\n      --letter \u003cvalue\u003e                 Provide some letters (Can be supplied multiple times)\n  ```\n\n2. If you call it without the required positional argument `username`, you get an error:\n\n  ```sh\n  $ ./examples/demo.sh\n  ERROR: The following required arguments are missing: username\n  USAGE:\n    demo.sh [--config] [-i|--interactive] [-s|--sleep] [--letter] username\n      username    Your username\n  \n    OPTIONS:\n      --sleep \u003cnumber\u003e, -s \u003cnumber\u003e    Sleep \u003cnumber\u003e seconds before doing anything\n      --config \u003cvalue\u003e                 Read configuration from a file\n      --interactive, -i                Ask before doing anything dangerous\n      --letter \u003cvalue\u003e                 Provide some letters (Can be supplied multiple times)\n  ```\n\n3. If you call it with an invalid (non-int) argument for `-s` or `--sleep`, you get an error:\n\n  ```sh\n  $ ./examples/demo.sh -s five\n  ERROR: Expected a number but got 'five'!\n  \n  USAGE:\n    demo.sh [--config] [-i|--interactive] [-s|--sleep] [--letter] username\n      username    Your username\n  \n    OPTIONS:\n      --sleep \u003cnumber\u003e, -s \u003cnumber\u003e    Sleep \u003cnumber\u003e seconds before doing anything\n      --config \u003cvalue\u003e                 Read configuration from a file\n      --interactive, -i                Ask before doing anything dangerous\n      --letter \u003cvalue\u003e                 Provide some letters (Can be supplied multiple times)\n  ```\n\n4. If you call it with proper arguments, it does what it's supposed to:\n\n  ```sh\n  $ ./examples/demo.sh thecalcaholic -s 5 extra --config /home/thecalcaholic/example_config.json -i --letter a --letter b --letter c\n  Your arguments:\n  username: thecalcaholic\n  config: /home/thecalcaholic/example_config.json\n  interactive: true\n  Your letters: a, b, c\n  sleep: 5\n  any other args you provided: extra\n  ```\n\n## Roadmap\n\n* typed lists\n* type checking/support for named (required) arguments\n* some kind of automatic tests\n\n[gh-issues]: https://github.com/theCalcaholic/bash-args/issues\n[bash-utils-repo]: https://github.com/theCalcaholic/bash-utils\n[bundle-script]: https://github.com/theCalcaholic/bash-utils#bundle-scriptsh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecalcaholic%2Fbash-args","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecalcaholic%2Fbash-args","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecalcaholic%2Fbash-args/lists"}