{"id":13461806,"url":"https://github.com/apple/swift-argument-parser","last_synced_at":"2026-04-01T20:19:36.056Z","repository":{"id":37428168,"uuid":"241928033","full_name":"apple/swift-argument-parser","owner":"apple","description":"Straightforward, type-safe argument parsing for Swift","archived":false,"fork":false,"pushed_at":"2025-05-07T22:24:38.000Z","size":3287,"stargazers_count":3458,"open_issues_count":111,"forks_count":336,"subscribers_count":152,"default_branch":"main","last_synced_at":"2025-05-08T20:03:32.201Z","etag":null,"topics":["cli","command-line","flag","option"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apple.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2020-02-20T16:07:00.000Z","updated_at":"2025-05-08T16:27:26.000Z","dependencies_parsed_at":"2025-04-23T17:22:07.957Z","dependency_job_id":null,"html_url":"https://github.com/apple/swift-argument-parser","commit_stats":{"total_commits":380,"total_committers":104,"mean_commits":"3.6538461538461537","dds":0.5789473684210527,"last_synced_commit":"d6836f4508b0a6a3c7f5e9db614a031db914cacd"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apple%2Fswift-argument-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apple%2Fswift-argument-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apple%2Fswift-argument-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apple%2Fswift-argument-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apple","download_url":"https://codeload.github.com/apple/swift-argument-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253650920,"owners_count":21942230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","command-line","flag","option"],"created_at":"2024-07-31T11:00:58.142Z","updated_at":"2026-04-01T20:19:36.048Z","avatar_url":"https://github.com/apple.png","language":"Swift","readme":"# Swift Argument Parser\n\n## Usage\n\nBegin by declaring a type that defines the information\nthat you need to collect from the command line.\nDecorate each stored property with one of `ArgumentParser`'s property wrappers,\nand then declare conformance to `ParsableCommand` and add the `@main` attribute.\n(Note, for `async` renditions of `run`, conform to `AsyncParsableCommand` rather\nthan `ParsableCommand`.)\nFinally, implement your command's logic in the `run()` method.\n\n```swift\nimport ArgumentParser\n\n@main\nstruct Repeat: ParsableCommand {\n    @Flag(help: \"Include a counter with each repetition.\")\n    var includeCounter = false\n\n    @Option(name: .shortAndLong, help: \"How many times to repeat 'phrase'.\")\n    var count: Int? = nil\n\n    @Argument(help: \"The phrase to repeat.\")\n    var phrase: String\n\n    mutating func run() throws {\n        let repeatCount = count ?? 2\n\n        for i in 1...repeatCount {\n            if includeCounter {\n                print(\"\\(i): \\(phrase)\")\n            } else {\n                print(phrase)\n            }\n        }\n    }\n}\n```\n\nThe `ArgumentParser` library parses the command-line arguments,\ninstantiates your command type, and then either executes your `run()` method\nor exits with a useful message.\n\n`ArgumentParser` uses your properties' names and type information,\nalong with the details you provide using property wrappers,\nto supply useful error messages and detailed help:\n\n```\n$ repeat hello --count 3\nhello\nhello\nhello\n$ repeat --count 3\nError: Missing expected argument 'phrase'.\nHelp:  \u003cphrase\u003e  The phrase to repeat.\nUsage: repeat [--count \u003ccount\u003e] [--include-counter] \u003cphrase\u003e\n  See 'repeat --help' for more information.\n$ repeat --help\nUSAGE: repeat [--count \u003ccount\u003e] [--include-counter] \u003cphrase\u003e\n\nARGUMENTS:\n  \u003cphrase\u003e                The phrase to repeat.\n\nOPTIONS:\n  --include-counter       Include a counter with each repetition.\n  -c, --count \u003ccount\u003e     The number of times to repeat 'phrase'.\n  -h, --help              Show help for this command.\n```\n\n## Documentation\n\nFor guides, articles, and API documentation see the\n[library's documentation on the Web][docs] or in Xcode.\n\n- [ArgumentParser documentation][docs]\n- [Getting Started with ArgumentParser](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/gettingstarted)\n- [`ParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/parsablecommand)\n- [`AsyncParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/asyncparsablecommand)\n\n[docs]: https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser\n\n#### Examples\n\nThis repository includes a few examples of using the library:\n\n- [`repeat`](Examples/repeat/Repeat.swift) is the example shown above.\n- [`roll`](Examples/roll/main.swift) is a simple utility implemented as a straight-line script.\n- [`math`](Examples/math/Math.swift) is an annotated example of using nested commands and subcommands.\n- [`count-lines`](Examples/count-lines/CountLines.swift) uses `async`/`await` code in its implementation.\n- [`default-as-flag`](Examples/default-as-flag/DefaultAsFlag.swift) demonstrates hybrid options that can work both as flags and as options with values.\n\nYou can also see examples of `ArgumentParser` adoption among Swift project tools:\n\n- [`swift-format`](https://github.com/apple/swift-format/) uses some advanced features, like custom option values and hidden flags.\n- [`swift-package-manager`](https://github.com/apple/swift-package-manager/) includes a deep command hierarchy and extensive use of option groups.\n\n## Project Status\n\nThe Swift Argument Parser package is source-stable;\nversion numbers follow semantic versioning.\nSource-breaking changes to public API can only land in a new major version.\n\nThe public API of version 1.0.0 of the `swift-argument-parser` package\nconsists of non-underscored declarations that are marked public in the `ArgumentParser` module.\nInterfaces that aren't part of the public API may continue to change in any release,\nincluding the exact wording and formatting of the autogenerated help and error messages,\nas well as the package’s examples, tests, utilities, and documentation.\n\nFuture minor versions of the package may introduce changes to these rules as needed.\n\nWe want this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.\nAccordingly, from time to time,\nwe expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release.\nRequiring a new Swift release will only require a minor version bump.\n\n## Adding `ArgumentParser` as a Dependency\n\nTo use the `ArgumentParser` library in a SwiftPM project,\nadd it to the dependencies for your package and your command-line executable target:\n\n```swift\nlet package = Package(\n    // name, platforms, products, etc.\n    dependencies: [\n        // other dependencies\n        .package(url: \"https://github.com/apple/swift-argument-parser\", from: \"1.7.0\"),\n    ],\n    targets: [\n        .executableTarget(name: \"\u003ccommand-line-tool\u003e\", dependencies: [\n            // other dependencies\n            .product(name: \"ArgumentParser\", package: \"swift-argument-parser\"),\n        ]),\n        // other targets\n    ]\n)\n```\n\n### Supported Versions\n\nThe minimum Swift version supported by swift-argument-parser releases are detailed below:\n\nswift-argument-parser | Minimum Swift Version\n----------------------|----------------------\n`0.0.1 ..\u003c 0.2.0`     | 5.1\n`0.2.0 ..\u003c 1.1.0`     | 5.2\n`1.1.0 ..\u003c 1.3.0`     | 5.5\n`1.3.0 ..\u003c 1.7.1`     | 5.7\n`1.8.0 ...`           | 6.0\n","funding_links":[],"categories":["Swift","Libs","Command Line","Command Line [🔝](#readme)","HarmonyOS","Recently Updated","Frameworks with plugins","Additional Languages","[Swift](https://www.swift.org/)"],"sub_categories":["Command Line","Linter","Windows Manager","[Feb 05, 2025](/content/2025/02/05/README.md)","Swift 🦉","Useful awesome list for Ruby cli"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapple%2Fswift-argument-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapple%2Fswift-argument-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapple%2Fswift-argument-parser/lists"}