Modern CLI Guidelines

Output Formatting

Design output that works for both human users and script consumption. When your command returns structured data, consider where you place human-readable messages.

Message Placement with Structured Output

When your command returns structured data (like JSON), the placement of human-readable messages affects both user experience and script parsing.

The Problem: Auto-scrolling

If your command returns lengthy structured output, messages placed before the output will auto-scroll away and can be missed by users.

# ❌ Message gets lost due to scrolling
$ mycommand
Resource created successfully!
{
  "id": "resource-123",
  "name": "my-resource",
  "properties": {
    // ... many lines of JSON ...
  }
}

The Solution: Messages After Output

Place human-readable messages after the structured output so users see them at the end where their eyes naturally land.

# ✅ Message visible at the end
$ mycommand  
{
  "id": "resource-123",
  "name": "my-resource", 
  "properties": {
    // ... many lines of JSON ...
  }
}

Resource created successfully!

Case Study: Azure CLI and PowerShell

Azure tools demonstrate different approaches to the same challenge:

Azure PowerShell Approach

Azure PowerShell returns a table format for the object, optimized for human readability:

PS> Get-AzVM
Name    ResourceGroup    Location    Status
----    ---------------  ----------  --------  
vm1     myRG            eastus      running
vm2     myRG            westus      stopped

Azure CLI Approach

In Azure CLI, when Azure resources are created successfully, the command returns the JSON object. This object can get quite lengthy. So when showing messages that need to be read by users, it's better to add it at the end of the JSON object. Otherwise, it will auto-scroll to the bottom and the message can be dismissed.

Azure Login Example (past design iteration, not currently shipped):
In az login, when we used to show JSON objects of all the subscriptions and I wanted to add a custom message, this was the approach I explored:

$ az login
[
  {
    "cloudName": "AzureCloud",
    "homeTenantId": "12345678-1234-1234-1234-123456789012", 
    "id": "87654321-4321-4321-4321-210987654321",
    "isDefault": true,
    "name": "My Subscription",
    "state": "Enabled",
    "tenantId": "12345678-1234-1234-1234-123456789012",
    "user": {
      "name": "user@example.com",
      "type": "user"
    }
  }
]

You have logged in. Now let us find all the subscriptions to which you have access.

Design Guidelines

Terminal Display Differences

Consider this! Different terminals handle styling and formatting in various ways. Don't rely on specific visual styles to convey important information - what looks perfect in your terminal might be broken or confusing in others.

The Challenge: Style Interpretation Varies

The same CLI output can appear completely different across terminals:

Hyperlink Display Variations

Hyperlinks are particularly problematic because terminals handle them inconsistently. Here's the real-world compatibility landscape:

Real Examples Across Terminals

Safe Design Patterns

Design your CLI output to work across all terminal types:

# Clear visual hierarchy
✓ SUCCESS: Deploy completed
✗ ERROR: Build failed  
→ NEXT: Run 'logs' command
ℹ INFO: Check status page

# Alternative with brackets
[OK] Deploy completed
[FAIL] Build failed
[NEXT] Run 'logs' command

# ❌ Color-dependent
Deploy completed
Build failed

# Multiple ways to access information
Documentation: https://docs.example.com
• Click the link above
• Run: myapp open-docs  
• Copy URL to browser

# Clear fallback instructions

Cross-Platform Compatibility

The Challenge: Terminal Capability Differences

Modern terminals have rich features like clickable links, but older terminals and different operating systems have varying levels of support. You need to design for the lowest common denominator while still providing enhanced experiences where possible.

Case Study: Intercept Survey Implementation

Here's a real example from Azure PowerShell showing how cross-platform constraints affect design decisions:

The Requirement

We needed to show an intercept survey message occasionally to gather user feedback. The survey should be easy to access but not disruptive to the workflow.

Initial Design vs. Reality

# What we wanted to do (doesn't work everywhere)
PS C:\Users\account> Get-AzVM
Name    ResourceGroup    Location    Status
----    ---------------  ----------  --------  
vm1     myRG            eastus      running

📋 Click here to take our 5-minute survey # ❌ Not all terminals support clickable links

What We Actually Implemented

# Cross-platform compatible solution
PS C:\Users\account> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

[Survey] Help us improve Azure PowerShell by sharing your experience. This survey should take about 5 minutes.
Run 'Open-SurveyLink' to open in browser. Learn more at https://go.microsoft.com/?id=2349.

PS C:\Users\account>

Design Decisions Made

Cross-Platform Design Principles

Automation Mode

The Design Mindset

When designing how a command works, remember that it might also be executed in a script. Commands often need to support automation. If you introduce a confirmation prompt, consider how it should behave in scripted scenarios. Should confirmation be enabled by default, or only when a specific parameter is provided?

The Problem

A command that works perfectly for humans can completely break automation:

# This works great for humans
$ deploy-app
Are you sure you want to deploy to production? (y/N)
> y
Deploying...

# But breaks scripts - the script hangs waiting for input
#!/bin/bash
deploy-app  # ❌ Script stops here, waiting forever

The Solution: Choose Your Approach

There are two main strategies. Consider which makes more sense for your command:

Strategy 1: Prompt by Default, Flag to Skip

Best for dangerous operations where human confirmation is valuable:

# Interactive mode - safe defaults with confirmation
$ deploy-app
Are you sure you want to deploy to production? (y/N)

# Automation mode - explicit flags bypass prompts
$ deploy-app --force
$ deploy-app --yes

Strategy 2: No Prompts by Default, Flag to Enable

Best for commands that will be frequently scripted:

# Default mode - no prompts, works in scripts
$ deploy-app
Deploying to production...

# Interactive mode - opt into confirmations when wanted
$ deploy-app --interactive
$ deploy-app --confirm

Implementation Patterns

Backward Compatibility

Why Backward Compatibility Matters

CLI tools often become deeply integrated into scripts, automation pipelines, and user workflows. Breaking changes can:

• Break existing scripts and automation
• Require immediate user action to fix their workflows
• Create frustration and resistance to updates
• Force users to pin to older versions

Compatibility Strategy Options

Here are some options to consider when introducing changes:

# Use new behavior
$ myapp deploy --api-version=v2

# Keep old behavior
$ myapp deploy --api-version=v1

# Enable new feature
$ myapp config set new-feature=true

# Disable new feature
$ myapp config set new-feature=false

# Enable new behavior
$ export MYAPP_NEW_DEPLOY=1
$ myapp deploy

Real Example: Azure CLI Login Experience

This is what we used when introducing new az login experience:

Implementation Example

# Enable new login experience
$ az config set core.enable_broker_on_windows=true

# If it's turned on by default, show user how to turn it off
$ az login
Using new enhanced login experience.
To use the previous experience, run: az config set core.enable_broker_on_windows=false

# User can easily revert
$ az config set core.enable_broker_on_windows=false

Communication Strategy

If it's turned on by default, show to user how they can turn it off in the command output:

Good Communication Examples

# Clear notification with revert instructions
$ myapp deploy
ℹ️  Using new deployment engine (faster, more reliable)
   To use the previous engine: myapp config set engine=legacy
   
Deploying application...

# Deprecation warning with timeline
$ myapp old-command
⚠️  Warning: 'old-command' is deprecated and will be removed in v3.0
   Use 'myapp new-command' instead
   Migration guide: https://myapp.com/migration

# Feature announcement with opt-out
$ myapp status
🎉 New: Enhanced status display is now enabled
   To disable: myapp config set enhanced-status=false
   
Project: healthy (3 services running)

Accessibility

Designing for both screen reader and non–screen reader users can be challenging. Terminals don’t support accessibility attributes like aria-label, so whatever appears on screen is exactly what will be read aloud. Optimizing for both audiences in a single experience can be difficult. An alternative approach is to tailor the design or interaction model based on whether a screen reader is active. Here are a few options:

Detection and Adaptation Strategies

1. Ask the User: Prompt during setup or first run to configure accessibility preferences

2. Environment Detection: Check for common screen reader environment variables or running processes

3. Configuration Setting: Allow users to explicitly enable accessibility optimizations

4. Command Line Flag: Provide immediate accessibility mode for any command

# Readable without colors
[ERROR] Connection timeout
[OK] File saved successfully
[NEXT] Run setup command

# Clear without bold/italic
IMPORTANT: Backup your data first
WARNING: This action cannot be undone
NOTE: Process may take several minutes

# Simple, clear instructions
Choose what to deploy:
1. Web application only
2. Database and web application  
3. Full system with monitoring

Enter 1, 2, or 3:

ASCII Art — Use with Caution

ASCII art can be visually striking and fun — we get it, it looks cool. However, screen readers will read it as gibberish since there is no aria-label support in terminals. If you choose to use ASCII art, follow these guidelines:

• Limit when it appears — Show ASCII art only on special occasions such as the very first run after install, or after a major upgrade.
• Detect screen readers — If you can detect screen readers, don't show the ASCII art when the reader is on.
• Always include a plain-text alternative — The essential information in the art should also be conveyed in regular text.

ASCII Art Done Right

# ⚠️ Caution - a screen reader would read every character of this as gibberish
# Only show on first run or upgrade, and skip for screen reader users

 ██╗  ██╗███████╗██╗     ██╗      ██████╗
 ██║  ██║██╔════╝██║     ██║     ██╔═══██╗
 ███████║█████╗  ██║     ██║     ██║   ██║
 ██╔══██║██╔══╝  ██║     ██║     ██║   ██║
 ██║  ██║███████╗███████╗███████╗╚██████╔╝
 ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝ ╚═════╝
 ██╗    ██╗ ██████╗ ██████╗ ██╗     ██████╗ ██╗
 ██║    ██║██╔═══██╗██╔══██╗██║     ██╔══██╗██║
 ██║ █╗ ██║██║   ██║██████╔╝██║     ██║  ██║██║
 ██║███╗██║██║   ██║██╔══██╗██║     ██║  ██║╚═╝
 ╚███╔███╔╝╚██████╔╝██║  ██║███████╗██████╔╝██╗
  ╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═════╝ ╚═╝

 Welcome to MyCLI v2.0 — type 'help' to get started.

# ✅ Always include a plain-text fallback with the same info
# This is what screen reader users (and --no-banner users) would see instead:

Hello World!
Welcome to MyCLI v2.0 — type 'help' to get started.