Description
Announcing System.CommandLine 2.0.0-beta5 and our path to a stable release
We are excited to announce the release of System.CommandLine 2.0.0-beta5 and our path toward a stable release! This milestone reflects our commitment to delivering a high-quality command-line parsing library for the .NET ecosystem.
Celebrating success and adoption
System.CommandLine has seen significant and growing adoption across the .NET ecosystem over the past 5 years, powering thousands of applications including the .NET CLI itself. The previous release, 2.0.0-beta4, has been downloaded nearly 25 million times over the past 3 years, representing about half of all downloads. This broad usage highlights the library's stability, flexibility, and the trust the community has placed in it.
Our ambitious 'Powderhouse' reset
In early 2024, we announced a reset of System.CommandLine to isolate parsing behavior for sharing with other libraries. As part of the "Powderhouse" project, our stated goals included:
- A core parser that could be moved into the dotnet/runtime repository
- An open source, feature-rich framework relying on the core parser and extensible subsystems for end user behavior such as help
- An open ecosystem to encourage community creation/extension of pluggable subsystems
As we worked toward these goals, we recognized that achieving the full scope would require more ecosystem disruption than we could justify. This led us to adjust our approach and focus on delivering improvements with greater stability and a more measured evolution of the library.
Pivoting to 2.0.0-beta5
Our focus shifted toward improving the APIs and recommitting to the release of a stable version of System.CommandLine without an aspirational re-architecture. We are no longer aiming to extract a core parser out into the dotnet/runtime repository or create a subsystem framework as envisioned in 'Powderhouse'.
Nonetheless, 2.0.0-beta5 includes substantial improvements. The APIs are simplified, and they are more consistent and coherent with the Framework design guidelines. These changes include:
- Renaming some API types and members
- Exposing mutable collections
- Distinguishing between
Symbolnames and aliases - Supporting type-safe default values
- Improvements to custom parsing
- Separating parsing from invocation
- Simplification of configuration, command building, and invocation
We hope that the changes made in 2.0.0-beta5 will make the API more consistent, future-proof, and easier to use for both existing and new users. The public API surface is reduced while retaining the functionality needed to implement powerful command-line applications. With these changes, new users will need to learn fewer concepts and types and the libraries are set up for improved long-term maintainability and evolution.
These changes reduce the size of the library by 32% and the size of a baseline NativeAOT app by 20%. Performance is notably improved with these changes too; benchmarks show a 12% startup time improvement and 40% faster parsing compared to 2.0.0-beta4.
Path to a stable release
Our objective is to publish a stable (non-preview) release of System.CommandLine 2.0.0 around the same time .NET 10 ships in November 2025.
We will release version 2.0.0-beta6 in July, 2.0.0-beta7 in August, with Release Candidates expected in September and October alongside the .NET 10 monthly releases.
Call to action
To achieve this goal of a stable release this year, we need your help!
Upgrading from 2.0.0-beta4 to 2.0.0-beta5 introduces many breaking changes. The breaking changes were scoped to those with a favorable value to disruption comparison, but some applications will still need considerable effort to adopt the new release. We need to hear your success stories, blockers, issues, and other feedback.
With the release of 2.0.0-beta5, we updated the System.CommandLine documentation and added a 2.0.0-beta5 migration guide. The migration guide includes detailed API changes, updated tutorials, new code samples, and more.
Dogfooding in dotnet
It's well known that the .NET CLI itself is built on top of System.CommandLine, but there are also about a dozen other console applications within the dotnet organization that use the library. Before releasing 2.0.0-beta5 publicly, we have already updated all of our own dependencies from 2.0.0-beta4 (or earlier versions) to 2.0.0-beta5.
All of these upgrades were successfully incorporated into .NET 10 Preview 5.
We appreciate the community's engagement and encourage continued feedback as we push toward a stable release. Functional issues can be filed in dotnet/command-line-api and documentation feedback/issues can be filed in dotnet/docs.
Deprecating experimental projects
As part of our pivot and reevaluation, we reached decisions to deprecate experimental System.CommandLine projects that did not have a clear path toward a stable release. These packages were updated for the 2.0.0-beta5 breaking changes are included in June 2025 release, but they will be excluded from all future releases.
- System.CommandLine.NamingConventionBinder version 2.0.0-beta5.25306.1
- System.CommandLine.DragonFruit version 0.4.0-alpha.25306.1
- System.CommandLine.Hosting version 0.4.0-alpha.25306.1
- System.CommandLine.Rendering version 0.4.0-alpha.25306.1
These projects are being removed from the repository. The code can be referenced and forked if needed using the v2.0.0-beta5.25306.1 tag.
This decision allowed our team to focus on the core feature set of System.CommandLine while recognizing high-quality, open source projects outside this repository. We encourage users to explore these alternatives:
- Spectre.Console for rendering console applications
- DotMake Command-Line for a source generator which automagically converts your classes to a symbol tree
Thank you!
Thank you to everyone who has contributed to System.CommandLine, the Powderhouse project, the 2.0.0-beta5 milestone, and the broader ecosystem. We invite your feedback on 2.0.0-beta5 and this path forward.