If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/apple/swift-argument-parser shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 23+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live apple/swift-argument-parser repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apple/swift-argument-parser.

What it runs against: a local clone of apple/swift-argument-parser — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in apple/swift-argument-parser | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apple/swift-argument-parser. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apple/swift-argument-parser.git
#   cd swift-argument-parser
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of apple/swift-argument-parser and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apple/swift-argument-parser(\\.git)?\\b" \\
  && ok "origin remote is apple/swift-argument-parser" \\
  || miss "origin remote is not apple/swift-argument-parser (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/ArgumentParser/Parsable Types/ParsableCommand.swift" \\
  && ok "Sources/ArgumentParser/Parsable Types/ParsableCommand.swift" \\
  || miss "missing critical file: Sources/ArgumentParser/Parsable Types/ParsableCommand.swift"
test -f "Sources/ArgumentParser/Parsing/ArgumentDecoder.swift" \\
  && ok "Sources/ArgumentParser/Parsing/ArgumentDecoder.swift" \\
  || miss "missing critical file: Sources/ArgumentParser/Parsing/ArgumentDecoder.swift"
test -f "Sources/ArgumentParser/Parsable Properties/Argument.swift" \\
  && ok "Sources/ArgumentParser/Parsable Properties/Argument.swift" \\
  || miss "missing critical file: Sources/ArgumentParser/Parsable Properties/Argument.swift"
test -f "Sources/ArgumentParser/Parsing/CommandParser.swift" \\
  && ok "Sources/ArgumentParser/Parsing/CommandParser.swift" \\
  || miss "missing critical file: Sources/ArgumentParser/Parsing/CommandParser.swift"
test -f "Sources/ArgumentParser/Parsing/ArgumentDefinition.swift" \\
  && ok "Sources/ArgumentParser/Parsing/ArgumentDefinition.swift" \\
  || miss "missing critical file: Sources/ArgumentParser/Parsing/ArgumentDefinition.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/apple/swift-argument-parser"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

swift-argument-parser is a type-safe, declarative command-line argument parsing library for Swift that eliminates boilerplate by using property wrappers (@Argument, @Option, @Flag) to automatically generate parsers, help text, and error messages from struct definitions. It handles validation, type coercion, and shell completion generation without manual string parsing. Single-package structure: Sources/ArgumentParser contains core parsing logic split into Completions/, with Examples/ providing runnable demos (repeat, math, roll). Build system via Package.swift and CMakeLists.txt; Plugins/ contains build-time code generation for documentation and manual pages. Tests likely in Tests/ (not listed but standard Swift Package layout).

Swift developers building CLI tools and command-line applications who want to avoid manual argument parsing logic and automatically get help generation, error handling, and bash/zsh completion support. Also used by tool maintainers who need accessible, self-documenting command interfaces.

Production-ready and actively maintained by Apple. The repo shows substantial Swift codebase (~1M LOC), has comprehensive examples (repeat, math, roll, count-lines), CI/CD via GitHub Actions (pull_request.yml), and plugin infrastructure (GenerateManual, GenerateDoccReference) indicating ongoing enhancement. Well-documented with official Swift Package Index presence.

Low risk: Apple-backed project with clear CODEOWNERS, CONTRIBUTING.md, and established PR template processes. No obvious single-maintainer dependency; however, new users should track CHANGELOG.md for API changes as the library is pre-1.0 in some Swift versions. Plugin system adds complexity but is optional.

Active development on plugin system (GenerateDoccReference, GenerateManual suggest recent documentation automation work). Dependabot configured (.github/dependabot.yml) for dependency updates. Swift formatting and linting standards enforced (.swift-format, .editorconfig, license header templates).

git clone https://github.com/apple/swift-argument-parser.git && cd swift-argument-parser && swift build && swift run --example repeat hello --count 3

Daily commands: swift build compiles the library. swift run --example <name> runs any example (repeat, math, roll, count-lines, color, default-as-flag). Development: swift test runs the test suite.

• Sources/ArgumentParser/Parsable Types/ParsableCommand.swift — Primary entry point protocol that users conform to with @main; defines the run() method contract and command lifecycle.
• Sources/ArgumentParser/Parsing/ArgumentDecoder.swift — Core decoder responsible for parsing raw command-line arguments into Swift types; handles all type coercion and validation logic.
• Sources/ArgumentParser/Parsable Properties/Argument.swift — Property wrapper for positional arguments; must understand its relationship to Option and Flag to avoid conflicts.
• Sources/ArgumentParser/Parsing/CommandParser.swift — Orchestrates the parsing pipeline, merges argument definitions, and handles subcommand routing.
• Sources/ArgumentParser/Parsing/ArgumentDefinition.swift — Abstract representation of a single argument/option/flag; foundational to how all property wrappers register themselves.
• Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift — Metadata container for command help text, subcommand routing, and execution hints; used by both ParsableCommand and CommandGroup.
• Sources/ArgumentParser/Completions/CompletionsGenerator.swift — Base protocol for shell completions; essential for understanding how bash/zsh/fish integrations extend the core parser.

Add a New Command Type with Custom Options

1. Create a struct conforming to ParsableCommand with @main attribute (Examples/repeat/Repeat.swift)
2. Declare properties with @Flag, @Option, and @Argument property wrappers; each specifies help text and name customization (Sources/ArgumentParser/Parsable Properties/Flag.swift)
3. Implement mutating func run() throws to execute command logic; throw ParsingError or other errors for validation failures (Sources/ArgumentParser/Parsing/ParserError.swift)
4. For subcommands, add a @CommandGroup property and conform to CommandGroup protocol; use ParentCommand to link subcommand to parent (Sources/ArgumentParser/Parsable Types/CommandGroup.swift)

Support Custom Types as Arguments/Options

1. Extend your custom type to conform to ExpressibleByArgument protocol (Sources/ArgumentParser/Parsable Types/ExpressibleByArgument.swift)
2. Implement init?(argument: String) to parse a string representation into your type; throw ParsingError for invalid input (Sources/ArgumentParser/Parsing/ParserError.swift)
3. Optionally implement static var completionKind to enable shell completions (e.g., .file, .directory, .list(values)) (Sources/ArgumentParser/Parsable Properties/CompletionKind.swift)
4. Use @Option or @Argument with your type; the decoder will invoke your ExpressibleByArgument conformance automatically (Sources/ArgumentParser/Parsing/ArgumentDecoder.swift)

Add Shell Completion Support for a New Shell

1. Create a new struct conforming to CompletionsGenerator protocol (Sources/ArgumentParser/Completions/CompletionsGenerator.swift)
2. Examine an existing shell generator (e.g., BashCompletionsGenerator) to understand the completion script format and command tree traversal (Sources/ArgumentParser/Completions/BashCompletionsGenerator.swift)
3. Implement generateCompletion(for:) to traverse the command tree and produce shell-specific completion code (Sources/ArgumentParser/Completions/CompletionsGenerator.swift)
4. Register your generator in CommandParser so --completion-script calls it when --completion-script=yourshell is passed (Sources/ArgumentParser/Parsing/CommandParser.swift)

Customize Help Text and Command Metadata

1. In your ParsableCommand, define a static var configuration: CommandConfiguration property to override defaults (Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift)
2. Set abstract, discussion, version, shouldDisplay, subcommands, and defaultSubcommand fields to customize help and routing (Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift)
3. For individual properties, pass help:, helpName:, and visibility: arguments to @Flag, @Option, @Argument (Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift)
4. The CommandParser automatically formats help output; verify by running your command with --help (Sources/ArgumentParser/Parsing/CommandParser.swift)

• Property wrappers (@Flag, @Option, @Argument) — Declarative, compile-time-checked syntax; allows compile-time validation that property types conform to ExpressibleByArgument
• ParsableCommand protocol with @main — Single-entry-point pattern; enables compile-time guarantee that command struct is properly structured; @main auto-invokes main(

No hidden traps are obvious from the file structure. Notable: async support requires AsyncParsableCommand not ParsableCommand (see README). CMakeLists.txt suggests CMake build support exists alongside Swift Package Manager—ensure consistency when modifying build config. License header template enforcement via .license_header_template and .licenseignore may cause CI failures if not followed on new files.

• Property Wrappers (@propertyWrapper) — Core Swift feature (SE-0258) that swift-argument-parser leverages to declaratively attach parsing metadata (help text, defaults, validation) to properties without boilerplate
• Parser Combinators — The library likely uses combinator patterns internally to compose simple parsers into complex grammars; understanding this pattern helps contribute to parsing logic extensions
• Type-Safe Argument Parsing — swift-argument-parser shifts validation from runtime (string checks) to compile-time (Swift type system); this is the core design philosophy differentiating it from untyped CLIs
• Command Pattern (Gang of Four) — ParsableCommand protocol embodies the command pattern, allowing hierarchical subcommand composition and polymorphic command execution
• Bash/Zsh Shell Completion — BashCompletionsGenerator.swift auto-generates shell-native completion scripts; understanding completion spec format is needed to extend completion support to new option types
• Build-time Code Generation (Swift Plugins) — Plugins/ directory uses SPM's build plugin API (SE-0303) to generate man pages and documentation at build time; relevant for extending auxiliary outputs
• Variadic Generics / TypeErasing — swift-argument-parser uses type erasure to unify heterogeneous property wrapper types (Flag, Option, Argument) into a single parser; crucial for understanding the internal architecture

• apple/swift-package-manager — SPM is the package distribution mechanism and build system for swift-argument-parser; understanding SPM plugins is essential to extending this library
• jpsim/Yams — Common companion library for CLI tools that need config file parsing alongside argument parsing
• pointfreeco/swift-composable-architecture — Modern Swift architectural pattern that some complex CLI tools adopt for state management; relevant for users building stateful command hierarchies
• nicklockwood/SwiftFormat — Demonstrates another real-world CLI tool built with swift-argument-parser; excellent reference for idiomatic usage patterns
• realm/SwiftLint — Large-scale Swift CLI tool using argument parsing; reference implementation for complex subcommand hierarchies and real-world error handling

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for BashCompletionsGenerator, FishCompletionsGenerator, and ZshCompletionsGenerator

The Completions module has four generator implementations (Sources/ArgumentParser/Completions/*.swift) but there's no visible test coverage in the file structure. Shell completion generation is critical functionality that needs validation across different shell formats. Adding unit tests would ensure completions work correctly for various argument types, subcommands, and edge cases across all three shells.

• [ ] Create Tests/ArgumentParserTests/CompletionsTests/ directory structure
• [ ] Add BashCompletionsGeneratorTests.swift with tests for flag completion, option completion, and subcommand completion
• [ ] Add FishCompletionsGeneratorTests.swift with Fish-specific syntax validation
• [ ] Add ZshCompletionsGeneratorTests.swift with Zsh-specific completion format tests
• [ ] Verify tests cover custom completion providers and nested subcommands

Expand Documentation.docc with examples for shell completion integration

The Documentation.docc/Articles/ directory includes GettingStarted.md and CustomizingCompletions.md, but there's no article specifically covering installation and practical usage of the completion generators. Sources/ArgumentParser/Completions/ has four generator classes that deserve dedicated documentation with examples for each shell type (Bash, Fish, Zsh).

• [ ] Review existing CustomizingCompletions.md to identify gaps
• [ ] Create Documentation.docc/Articles/ShellCompletionSetup.md with step-by-step integration for Bash, Fish, and Zsh
• [ ] Add code examples showing how to generate and install completion scripts for each shell
• [ ] Include troubleshooting section for common completion issues
• [ ] Reference the completion generator classes from Sources/ArgumentParser/Completions/

Add integration tests for AsyncParsableCommand with complex subcommand hierarchies

The repo supports AsyncParsableCommand (mentioned in README and visible in Documentation.docc/Extensions/AsyncParsableCommand.md), but there's no clear test coverage for async command execution with nested subcommands. This is a non-trivial feature that requires validation to ensure async/await patterns work correctly in multi-level command structures.

• [ ] Review existing test structure to locate command parsing tests
• [ ] Create Tests/ArgumentParserTests/AsyncCommandTests.swift
• [ ] Add tests for AsyncParsableCommand with single and nested subcommands
• [ ] Include tests for error handling and cancellation in async contexts
• [ ] Verify async command execution timing and output ordering in complex scenarios

• Add comprehensive error message tests for the Completions/BashCompletionsGenerator.swift—currently hard to trace what bash completion scenarios are covered; create fixtures in Tests/ for edge cases like options with spaces, subcommands, and required arguments
• Document the plugin system with a worked example: create Examples/plugin-demo/ showing how to invoke GenerateManual or GenerateDoccReference on a custom command, with before/after output
• Extend the type coercion system: currently supports basic types (Int, String, Bool). Add UUID and URL property wrapper support with tests in Sources/ArgumentParser/, following the existing pattern of the optional/array variants

Swift Argument Parser is a well-maintained, security-focused library with minimal vulnerabilities. The codebase follows secure design principles for a command-line argument parsing library. No critical or high-severity issues were identified. Minor observations regarding secure coding practices are provided as recommendations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.