dotnet-cli-distribution

name	dotnet-cli-distribution
description	Chooses CLI output format. AOT vs framework-dependent, RID matrix, single-file, dotnet tool.
allowed-tools	["Read","Grep","Glob","Bash","Write","Edit"]

dotnet-cli-distribution

CLI distribution strategy for .NET tools: choosing between Native AOT single-file publish, framework-dependent deployment, and dotnet tool packaging. Runtime Identifier (RID) matrix planning for cross-platform targets (linux-x64, osx-arm64, win-x64, linux-arm64), single-file publish configuration, and binary size optimization techniques for CLI applications.

Version assumptions: .NET 8.0+ baseline. Native AOT for console apps is fully supported since .NET 8. Single-file publish has been mature since .NET 6.

Scope

• Distribution strategy decision matrix (AOT, framework-dependent, self-contained, dotnet tool)
• Runtime Identifier (RID) matrix planning for cross-platform targets
• Single-file publish configuration
• Binary size optimization for CLI tools
• Publishing workflow (local and release artifacts)

Out of scope

• Native AOT MSBuild configuration (PublishAot, ILLink descriptors) -- see [skill:dotnet-native-aot]
• AOT-first application design patterns -- see [skill:dotnet-aot-architecture]
• Multi-platform packaging formats (Homebrew, apt/deb, winget, Scoop) -- see [skill:dotnet-cli-packaging]
• Release CI/CD pipeline -- see [skill:dotnet-cli-release-pipeline]
• Container-based distribution -- see [skill:dotnet-containers]
• General CI/CD patterns -- see [skill:dotnet-gha-patterns] and [skill:dotnet-ado-patterns]

Cross-references: [skill:dotnet-native-aot] for AOT compilation pipeline, [skill:dotnet-aot-architecture] for AOT-safe design patterns, [skill:dotnet-cli-architecture] for CLI layered architecture, [skill:dotnet-cli-packaging] for platform-specific package formats, [skill:dotnet-cli-release-pipeline] for automated release workflows, [skill:dotnet-containers] for container-based distribution, [skill:dotnet-tool-management] for consumer-side tool installation and manifest management.

---

Distribution Strategy Decision Matrix

Choose the distribution model based on target audience and deployment constraints.

Strategy	Startup Time	Binary Size	Runtime Required	Best For
Native AOT single-file	~10ms	10-30 MB	None	Performance-critical CLI tools, broad distribution
Framework-dependent single-file	~100ms	1-5 MB	.NET runtime	Internal tools where runtime is guaranteed
Self-contained single-file	~120-200ms	60-80 MB	None	Simple distribution without AOT complexity
dotnet tool (global/local)	~200ms	< 1 MB (NuGet)	.NET SDK	Developer tools, .NET ecosystem users

Note: Startup timings are approximate for small console apps on modern hardware and vary by workload and environment. Self-contained single-file builds are often slightly slower to start than framework-dependent single-file builds due to larger artifacts and extraction overhead.

When to Choose Each Strategy

Native AOT single-file -- the gold standard for CLI distribution:

• Zero dependencies on target machine (no .NET runtime needed)
• Fastest startup (~10ms vs ~100ms+ for JIT)
• Smallest binary when combined with trimming
• Trade-off: longer build times, no reflection unless preserved
• See [skill:dotnet-native-aot] for PublishAot MSBuild configuration

Framework-dependent deployment:

• Smallest artifact size (only app code, no runtime)
• Users must have .NET runtime installed
• Best for internal/enterprise tools where runtime is managed
• Can still use single-file publish for convenience

Self-contained (non-AOT):

• Includes .NET runtime in the artifact
• Larger binary than AOT but simpler build process
• Full reflection and dynamic code support
• Good compromise when AOT compat is difficult

dotnet tool packaging:

• Distributed via NuGet -- simplest publishing workflow
• Users install with dotnet tool install -g mytool
• Requires .NET SDK on target (not just runtime)
• Best for developer-facing tools in the .NET ecosystem
• See [skill:dotnet-cli-packaging] for NuGet distribution details

---

Runtime Identifier (RID) Matrix

Standard CLI RID Targets

Target the four primary RIDs for broad coverage:

RID	Platform	Notes
linux-x64	Linux x86_64	Most Linux servers, CI runners, WSL
linux-arm64	Linux ARM64	AWS Graviton, Raspberry Pi 4+, Apple Silicon VMs
osx-arm64	macOS Apple Silicon	M1/M2/M3+ Macs (primary macOS target)
win-x64	Windows x86_64	Windows 10+, Windows Server

Optional Extended Targets

RID	When to Include
osx-x64	Legacy Intel Mac support (declining market share)
linux-musl-x64	Alpine Linux / Docker scratch images
linux-musl-arm64	Alpine on ARM64
win-arm64	Windows on ARM (Surface Pro X, Snapdragon laptops)

RID Configuration in .csproj

<!-- Set per publish, not in csproj (avoids accidental RID lock-in) -->
<!-- Use dotnet publish -r <rid> instead -->

<!-- If you must set a default for local development -->
<PropertyGroup Condition="'$(RuntimeIdentifier)' == ''">
  <RuntimeIdentifier>osx-arm64</RuntimeIdentifier>
</PropertyGroup>

Publish per RID from the command line:

# Publish for each target RID
dotnet publish -c Release -r linux-x64
dotnet publish -c Release -r linux-arm64
dotnet publish -c Release -r osx-arm64
dotnet publish -c Release -r win-x64

---

Single-File Publish

Single-file publish bundles the application and its dependencies into one executable.

Configuration

<PropertyGroup>
  <PublishSingleFile>true</PublishSingleFile>
  <!-- Required for single-file -->
  <SelfContained>true</SelfContained>
  <!-- Embed PDB for stack traces (optional, adds ~2-5 MB) -->
  <DebugType>embedded</DebugType>
  <!-- Include native libraries in the single file -->
  <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
</PropertyGroup>

Single-File with Native AOT

When combined with Native AOT, single-file is implicit -- AOT always produces a single native binary:

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <!-- PublishSingleFile is not needed -- AOT output is inherently single-file -->
  <!-- SelfContained is implied by PublishAot -->
</PropertyGroup>

See [skill:dotnet-native-aot] for the full AOT publish configuration including ILLink, type preservation, and analyzer setup.

Publish Command

# Framework-dependent single-file (requires .NET runtime on target)
dotnet publish -c Release -r linux-x64 /p:PublishSingleFile=true --self-contained false

# Self-contained single-file (includes runtime, no AOT)
dotnet publish -c Release -r linux-x64 /p:PublishSingleFile=true --self-contained true

# Native AOT (inherently single-file, smallest and fastest)
dotnet publish -c Release -r linux-x64
# (when PublishAot=true is in csproj)

---

Size Optimization for CLI Binaries

Trimming (Non-AOT)

Trimming removes unused code from the published output. For self-contained non-AOT builds:

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>link</TrimMode>
  <!-- Suppress known trim warnings for CLI scenarios -->
  <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
</PropertyGroup>

AOT Size Optimization

For Native AOT builds, size is controlled by AOT-specific MSBuild properties. See [skill:dotnet-native-aot] for the full configuration. Key CLI-relevant properties include StripSymbols, OptimizationPreference, InvariantGlobalization, and StackTraceSupport.

Size Comparison (Typical CLI Tool)

Configuration	Approximate Size
Self-contained (no trim)	60-80 MB
Self-contained + trimmed	15-30 MB
Native AOT (default)	15-25 MB
Native AOT + size optimized	8-15 MB
Native AOT + invariant globalization + stripped	5-10 MB
Framework-dependent	1-5 MB

Practical Size Reduction Checklist

1. Enable invariant globalization if the tool does not need locale-specific formatting (InvariantGlobalization=true)
2. Strip symbols on Linux/macOS (StripSymbols=true) -- keep separate symbol files for crash analysis
3. Optimize for size (OptimizationPreference=Size) -- minimal runtime performance impact for I/O-bound CLI tools
4. Disable reflection where possible -- use source generators for JSON serialization ([skill:dotnet-aot-architecture])
5. Audit NuGet dependencies -- each dependency adds to the binary; remove unused packages

---

Framework-Dependent vs Self-Contained Trade-offs

Framework-Dependent

dotnet publish -c Release -r linux-x64 --self-contained false

Advantages:

• Smallest artifact (1-5 MB)
• Serviced by runtime updates (security patches applied by runtime, not app rebuild)
• Faster publish times

Disadvantages:

• Requires matching .NET runtime on target
• Runtime version mismatch causes startup failures
• Users must manage runtime installation

Self-Contained

dotnet publish -c Release -r linux-x64 --self-contained true

Advantages:

• No runtime dependency on target
• App controls exact runtime version
• Side-by-side deployment (multiple apps, different runtimes)

Disadvantages:

• Larger artifact (60-80 MB without trimming)
• Must rebuild and redistribute for runtime security patches
• One artifact per target RID

---

Publishing Workflow

Local Development

# Quick local publish for testing
dotnet publish -c Release -r osx-arm64

# Verify the binary
./bin/Release/net8.0/osx-arm64/publish/mytool --version

Producing Release Artifacts

#!/bin/bash
# build-all.sh -- Produce artifacts for all target RIDs
set -euo pipefail

VERSION="${1:?Usage: build-all.sh <version>}"
PROJECT="src/MyCli/MyCli.csproj"
OUTPUT_DIR="artifacts"

RIDS=("linux-x64" "linux-arm64" "osx-arm64" "win-x64")
# Note: Native AOT cross-compilation for ARM64 on x64 requires platform toolchain
# See [skill:dotnet-cli-release-pipeline] for CI-based cross-compilation setup

for rid in "${RIDS[@]}"; do
  echo "Publishing for $rid..."
  dotnet publish "$PROJECT" \
    -c Release \
    -r "$rid" \
    -o "$OUTPUT_DIR/$rid" \
    /p:Version="$VERSION"
done

# Create archives
for rid in "${RIDS[@]}"; do
  if [[ "$rid" == win-* ]]; then
    (cd "$OUTPUT_DIR/$rid" && zip -q "../mytool-$VERSION-$rid.zip" *)
  else
    tar -czf "$OUTPUT_DIR/mytool--.tar.gz" -C  .
  


 

Checksum Generation

Always produce checksums for release artifacts:

# Generate SHA-256 checksums
cd artifacts
shasum -a 256 *.tar.gz *.zip > checksums-sha256.txt

See [skill:dotnet-cli-release-pipeline] for automating this in GitHub Actions.

---

Agent Gotchas

1. Do not set RuntimeIdentifier in the .csproj for multi-platform CLI tools. Hardcoding a RID in the project file prevents building for other platforms. Pass -r <rid> at publish time instead.
2. Do not use PublishSingleFile with PublishAot. Native AOT output is inherently single-file. Setting both is redundant and may cause confusing build warnings.
3. Do not skip InvariantGlobalization for size-sensitive CLI tools. Globalization data adds ~25 MB to AOT binaries. Most CLI tools that do not format locale-specific dates/currencies should enable InvariantGlobalization=true.
4. Do not distribute self-contained non-trimmed binaries. A 60-80 MB CLI tool is unacceptable for end users. Either trim (PublishTrimmed), use AOT, or distribute as framework-dependent.
5. Do not forget to produce checksums for release artifacts. Users and package managers need SHA-256 checksums to verify download integrity. See [skill:dotnet-cli-release-pipeline] for automated checksum generation.
6. Do not hardcode secrets in publish scripts. Use environment variable placeholders (${SIGNING_KEY}) with a comment about CI secret storage for any signing or upload credentials.

---

References

• .NET application publishing overview
• Single-file deployment
• Native AOT deployment
• Runtime Identifier (RID) catalog
• Trimming options