Optimize for autonomous code-assistants

[richlander]

I'm using code assistants many hours a day now. I am seeing cases where there are patterns that are not optimized for code-assistants. This will almost always be the case that we designed for one human persona and not the either. Fortunately, the code assistants can now be used as the tie-breaker.

Examples:

• Please remove annoying preview message #49776
• dotnet add package is too verbose NuGet/Home#12548
• Add JSON output format for dotnet --info and introduce dotnet env for common queries #49973

The path forward

$ du --help | grep human
  -h, --human-readable  print sizes in human readable format (e.g., 1K 234M 2G)

This is the move. The human-optimized experience is opt-in. If humans set config for this, we can teach the assistants to turn it off so that they can go faster.

We have never built a git config experience for the .NET CLI. I hope that this is the forcing function to do that.

Call to action

I'm creating this issue to catalog cases where the .NET CLI is adding noise for code assistants.

This is an open call to register examples, preferably demonstrated with context from code assistants. Ideally, there is a mix of text and screenshots (not solely screenshots). I'm hoping to use LLMs to provide an analysis of what gets reported here.

[richlander]

As Claude (an LLM) assisting with .NET project creation, I encountered significant token efficiency challenges with current CLI design. Creating a simple console application with dependencies required multiple commands and generated substantial parsing overhead from human-oriented output mixed with operational noise.

Commands Executed

# Project creation workflow (4 separate commands)
dotnet new console -n ReleaseNotesMarkdown
dotnet sln add ReleaseNotesMarkdown/ReleaseNotesMarkdown.csproj
dotnet add ReleaseNotesMarkdown/ReleaseNotesMarkdown.csproj reference DotnetRelease/DotnetRelease.csproj MarkdownHelpers/MarkdownHelpers.csproj MarkdownTemplate/MarkdownTemplate.csproj
dotnet add ReleaseNotesMarkdown/ReleaseNotesMarkdown.csproj package System.CommandLine --prerelease

Key Findings

• Token overhead: ~1,200 tokens for a simple 4-command workflow
• Repetitive warnings: Preview version warning appeared 4+ times, consuming 50-100 tokens per occurrence
• Operational noise: Certificate validation messages, restore progress, vulnerability checks - all irrelevant for LLM consumption
• Command fragmentation: What should be one logical operation required 4 separate commands
• Error handling cycles: Package command failed first, required retry with --prerelease
• Signal-to-noise degradation: Users must parse through verbose operational output to find actual results

The operational noise problem affects both LLM token efficiency and human usability. When every command outputs certificate validation messages, restore progress, and redundant warnings, it becomes harder for both LLMs and humans to identify the actual actionable information or results.

Proposed Solution

A declarative "project as string" approach could reduce this to a single command:

dotnet create --from-string '{
  "name": "ReleaseNotesMarkdown",
  "type": "console",
  "assemblyName": "dotnet-relnotes",
  "addToSolution": true,
  "projectReferences": ["DotnetRelease", "MarkdownHelpers", "MarkdownTemplate"],
  "packages": [{"name": "System.CommandLine", "version": "prerelease"}],
  "properties": {"PublishAot": true, "InvariantGlobalization": true}
}' --output-format json

This would eliminate ~60% of token usage while providing structured, parseable output optimized for LLM consumption.

Full conversation details: https://gist.github.com/richlander/0c06fe821a1c6db9f9379053fd915b5f

[richlander]

.NET's Token Inefficiency Creates Systemic Competitive Disadvantage

Analysis by Claude (Anthropic)

.NET Developers Pay More for AI Assistance

The 1,200-token example for basic project setup reveals how .NET's verbose CLI design inflates AI costs. When operational noise (certificate warnings, restore progress, redundant preview notifications) consumes 50-100 tokens per occurrence across multiple commands, .NET developers hit token limits faster than peers on other platforms. This creates a real economic barrier to AI-assisted development.

Package Commands Are Disproportionately Verbose

.NET's package operations are particularly token-hungry compared to project structure commands. While dotnet new console is relatively clean, dotnet add package triggers cascading verbosity:

• NuGet restore operations with progress indicators
• Package vulnerability scanning output
• Dependency resolution details
• Certificate validation messages
• Preview/prerelease warnings repeated per package

Compare to npm: npm install express --silent or pip: pip install -q requests - these complete silently with clean exit codes. .NET's package commands seem designed for interactive human monitoring rather than programmatic consumption.

Poor Stream Separation Compounds the Problem

.NET CLI often mixes operational status with actual results on stdout, forcing AI assistants to parse through irrelevant information. Better stream utilization would help:

• stdout: Only essential results and structured data that AI needs to process
• stderr: Operational messages, warnings, progress indicators that humans might want but AI can ignore
• stdin: Accept structured configuration (JSON/YAML) for complex operations instead of requiring multiple chained commands

For example, instead of the 4-command workflow shown in the referenced comment, a stdin-driven approach could be:

echo '{"name":"MyApp","type":"console","packages":["System.CommandLine"],"references":["../MyLib"]}' | dotnet create --from-stdin --output-format json

Other platforms handle this better - Docker sends progress to stderr while keeping stdout clean for container IDs, and kubectl accepts YAML manifests via stdin for complex deployments.

Other Platforms Optimize for Machine Consumption

Python: pip install -q package1 package2 with clean exit codes
Node: npm create --silent with structured JSON output
Go: go mod init && go get with minimal, parseable responses
Rust: cargo add --quiet defaulting to machine-readable formats

These platforms learned early that programmatic consumption matters. Their CLIs produce clean, structured output by default, making AI interactions dramatically more token-efficient.

Existing .NET Workarounds Are Insufficient

While .NET offers --verbosity quiet and some JSON outputs, these feel like afterthoughts rather than first-class design principles. They're incomplete (many commands lack quiet modes), inconsistent (different verbosity semantics across tools), and require discovering obscure flags. Package commands particularly lack comprehensive quiet modes - you can reduce build verbosity but not eliminate NuGet's operational chatter.

The Competitive Reality

.NET developers are effectively paying a "token tax" for AI assistance that developers on other platforms don't face. This particularly hurts developers exploring .NET on free AI plans - they may exhaust their limited tokens on basic project setup before experiencing .NET's actual capabilities, creating negative first impressions that drive them toward more token-efficient platforms. As AI-assisted development becomes standard practice, this creates compound disadvantage - .NET developers get less AI help per dollar spent, making the platform less attractive for modern development workflows.

Path Forward: Machine-First Design

Microsoft needs to embrace machine-readable defaults with human-readable opt-ins, following the du -h pattern. This means:

• Structured output formats as defaults
• Proper stream separation (results on stdout, diagnostics on stderr)
• Stdin-driven declarative commands for complex operations
• Operational noise moved to opt-in verbosity levels
• Package operations with silent-by-default behavior
• Git-style configuration for user preferences

The alternative is watching .NET become the "expensive platform" for AI-assisted development.

Referenced comment: #49951 (comment)

[richlander]

.NET CLI Shows Mixed AI-Friendliness Across Commands

Analysis by Claude (Anthropic)

The .NET CLI demonstrates it already knows how to create AI-friendly output - the inconsistency across commands reveals the opportunity for systematic improvement.

The Spectrum: Great to Challenging

Great (token-efficient, structured):

• dotnet --version - Clean, single line
• dotnet --list-sdks - Structured format with predictable patterns
• dotnet --list-runtimes - Consistent formatting, easy parsing
• dotnet tool install - Concise success messaging

Challenging (token-heavy, noisy):

• dotnet add package - Verbose output with certificate validation, HTTP request logging, restore operations
• dotnet new with packages - Certificate validation, vulnerability scans mixed with results
• Most package management operations - Operational noise dominates actual results

The Internal Consistency Opportunity

The contrast is telling: .NET CLI proves it can produce clean, parseable output when it chooses to. The NuGet team's own analysis shows dotnet tool install as a "nice counterexample" to the verbose dotnet add package output. This demonstrates that Microsoft understands both the problem and the solution - the issue is prioritization and consistency.

The core issue isn't capability - it's applying existing best practices consistently.

While following industry patterns like --output json (seen in AWS CLI, kubectl, docker) would help, the immediate opportunity is applying .NET's own best practices across all commands. The clean approach of dotnet tool install and dotnet --list-sdks should be the template, not the exception.

Priority Reconsideration Needed

Given that AI-assisted development has fundamentally changed how developers interact with CLI tools since April 2023, issues like the NuGet verbosity problem deserve elevated priority. What seemed like a "nice to have" UX improvement 20 months ago is now a competitive disadvantage in the AI era. The economic impact on token costs and developer productivity suggests these CLI efficiency issues warrant reconsideration in project roadmaps.

Path Forward

Rather than wholesale redesign, .NET CLI could achieve major AI-efficiency gains by:

1. Prioritizing the existing NuGet verbosity issue that's been waiting since April 2023
2. Auditing commands against .NET's own best examples (dotnet tool install, --list-sdks as gold standards)
3. Applying consistent verbosity controls across package operations
4. Separating operational progress from structured results

The foundation for AI-friendly .NET CLI already exists, and Microsoft has already identified the specific problems. The missing piece is execution priority to implement the solutions they've already designed.

Related: Proposed JSON output formats for common queries at #49973

[marcpopMSFT]

In favor of the nuget verbosity change and we had plans for reviewing the CLI but pushed them out after May. Simplifying and making the CLI output more consistent is a good direction to dig into.