Build Ultra‑Fast Cross‑Platform CLI Tools with .NET 8 Native AOT and System.CommandLine

Why native compilation matters for command‑line utilities

Imagine a developer who needs a tool that starts in less than 50 ms on Windows, Linux and macOS, without requiring a runtime installation. Traditional .NET Core apps load the CLR, JIT‑compile code, and pay a noticeable start‑up penalty. .NET 8 Native AOT eliminates the JIT step, producing a single native executable that launches instantly and uses a fraction of memory. The result aligns perfectly with the expectations of modern CLI development, where users demand speed, small footprint, and zero‑install distribution.

Preparing the development environment

System requirements are modest: .NET SDK 8.0 or later on any supported OS, and a terminal with write access. Install the SDK with a single command:

dotnet --version

If the version is lower than 8.0, download the latest installer from Microsoft’s official site. After the SDK is in place, create a fresh console project:

dotnet new console -n FastCli

Navigate into the folder and add the System.CommandLine package, which supplies a rich API for parsing arguments, sub‑commands, and automatic help generation.

cd FastCli && dotnet add package System.CommandLine --prerelease

Configuring Native AOT in the project file

Edit FastCli.csproj to enable AOT publishing and to target the three main runtimes. The following XML snippet demonstrates the minimal configuration:

<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>net8.0</TargetFramework> <PublishAot>true</PublishAot> <RuntimeIdentifier>win-x64;linux-x64;osx-x64</RuntimeIdentifier> </PropertyGroup> <ItemGroup> <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" /> </ItemGroup> </Project>

Setting PublishAot to true instructs the compiler to generate native code for each RID. The RuntimeIdentifier list ensures a single build produces three platform‑specific binaries, satisfying the cross‑platform .NET 8 requirement.

Implementing a robust command hierarchy with System.CommandLine

The library lets you define commands, options, and validation logic declaratively. Below is a concise example that implements a greet sub‑command with a --name option. The handler writes a personalized message and returns an exit code.

using System.CommandLine; using System.CommandLine.Invocation; var root = new RootCommand("Fast CLI demo"); var greet = new Command("greet", "Print greeting"); var nameOption = new Option<string>("--name", () => "World", "Name to greet"); greet.AddOption(nameOption); greet.SetHandler((string name) => Console.WriteLine($\"Hello {name}!\"), nameOption); root.AddCommand(greet); return await root.InvokeAsync(args);

This pattern scales: you can add additional commands such as calc for arithmetic, each with its own options and validation callbacks. System.CommandLine automatically generates --help output, reducing boilerplate and improving user experience.

Performance testing and optimization tactics

After publishing with dotnet publish -c Release -r win-x64 --self-contained false /p:PublishAot=true, measure start‑up time using the time utility on Linux or Measure-Command in PowerShell. In a recent benchmark (April 2024), a native‑AOT CLI built with System.CommandLine started in 32 ms on an Intel i7 laptop, compared to 180 ms for a regular framework‑dependent build.

Key optimization tips include: avoid reflection‑heavy libraries, prefer span‑based APIs, and enable TrimMode=Full in the project file to remove unused IL. These steps shrink the executable from ~12 MB to under 7 MB, which matters when distributing tools via package managers.

Packaging for seamless distribution

Because each binary is self‑contained, you can ship them as simple zip archives or place them in a GitHub release. Users download the appropriate file for their OS, extract, and run the command without installing .NET. For CI pipelines, add a step that uploads the three binaries to a NuGet‑style feed, enabling internal teams to consume the tool via a versioned package.

To automate the multi‑RID publishing, use a one‑liner in a shell script:

for rid in win-x64 linux-x64 osx-x64; do dotnet publish -c Release -r $rid -p:PublishAot=true --self-contained false; done

This loop respects the RuntimeIdentifier values defined earlier, producing FastCli.exe, FastCli (Linux), and FastCli (macOS) ready for immediate use.

Conclusion

Combining .NET 8 Native AOT with System.CommandLine gives developers a powerful recipe for ultra‑fast, cross‑platform CLI tools. The approach eliminates runtime dependencies, delivers sub‑50 ms start‑up, and keeps the binary size competitive with native Go or Rust utilities. By following the step‑by‑step setup, configuring AOT, and leveraging System.CommandLine’s declarative API, you can focus on business logic while the platform handles performance and distribution concerns.

Sources

Microsoft .NET Documentation – Native AOT guide; System.CommandLine GitHub repository; .NET 8 release notes (2023‑11‑14).

Author: Mahmut Sarıkaya — sarikayadev.com