Create Cli

CLI Design Skill

Overview

This skill guides the design of command-line interface specifications before implementation or during refactoring. It focuses on creating CLIs that are both human-friendly and script-compatible, following established best practices and conventions.

When to Use This Skill

Use this skill when:

• Designing a new command-line tool from scratch
• Refactoring an existing CLI to improve UX
• Planning CLI parameters, flags, and subcommands
• Defining help text, error messages, and output formats
• Establishing configuration precedence and environment handling
• Designing safe operation modes (dry-run, confirmations, force flags)

Design Workflow

Step 1: Clarification

Ask minimal questions to understand the CLI's purpose:

Command Purpose:

• What does this command do?
• Who will use it? (humans, automation scripts, or both)
• Is this a single command or a suite with subcommands?

Input Contract:

• How does input flow in? (command arguments, stdin, files, interactive prompts)
• What parameters are required vs optional?
• Should it support batch/bulk operations?

Output Contract:

• What format should output use? (human-readable text, JSON, structured data)
• What goes to stdout vs stderr?
• Should it support multiple output formats?

Interactivity:

• Are interactive prompts appropriate?
• Should there be a non-interactive mode?
• How should it behave when piped or in CI environments?

Configuration:

• What's configurable? (flags, environment variables, config files)
• What's the precedence order?
• Are defaults sensible?

Step 2: Deliverable Specification

Produce a compact, implementable spec that includes:

1. Command Tree & Usage

USAGE:
  mycli [global-flags] <command> [command-flags] [arguments]

COMMANDS:
  init      Initialize a new project
  build     Build the project
  deploy    Deploy to production

GLOBAL FLAGS:
  -h, --help       Show help
  --version        Show version
  -v, --verbose    Enable verbose output
  --no-color       Disable colored output

2. Arguments & Flags Table

3. Subcommand Details

For each subcommand, specify:

• Purpose and behavior
• Required/optional arguments
• Flags specific to that subcommand
• State changes or side effects
• Exit codes

4. Output Rules

stdout:

• Primary command output
• Machine-parseable data when --format=json
• Human-readable results by default

stderr:

• Error messages
• Warnings
• Progress indicators (when appropriate)
• Diagnostic information with --verbose

5. Exit Codes

0   Success
1   General error
2   Invalid usage (missing args, unknown flags)
3   Configuration error
4   Runtime error (operation failed)
130 Interrupted (Ctrl+C)

6. Safety Mechanisms

Dry-run mode:

mycli deploy --dry-run    # Show what would happen without doing it

Interactive confirmations:

mycli delete database
# Prompt: "Are you sure you want to delete 'database'? [y/N]"

Force flag for non-interactive:

mycli delete database --force    # Skip confirmation

7. Configuration Precedence

Order of precedence (highest to lowest): 1. Command-line flags 2. Environment variables 3. Config file settings 4. Built-in defaults

Example:

# Flag overrides env var
MY_CLI_OUTPUT=json mycli --output=text    # Uses text

# Env var overrides config file
export MY_CLI_CONFIG=/custom/config
mycli    # Uses /custom/config instead of .config

8. Usage Examples

Provide 5-10 practical examples:

# Basic usage
mycli build

# With output format
mycli build --format=json > output.json

# Dry-run before executing
mycli deploy --dry-run
mycli deploy --force

# Using environment variables
MY_CLI_VERBOSE=1 mycli build

# Interactive vs non-interactive
mycli delete --force    # Non-interactive
mycli delete           # Prompts for confirmation

# Piping and composition
mycli list --format=json | jq '.[] | select(.status=="active")'

Default Conventions

Unless specified otherwise, apply these defaults:

Standard Flags

• -h, --help - Show help and exit
• --version - Show version and exit
• -v, --verbose - Enable verbose/debug output
• --no-color - Disable colored output (respect NO_COLOR env var)
• --quiet, -q - Suppress non-essential output
• --force, -f - Skip confirmations (for automation)
• --dry-run - Simulate operation without making changes

Terminal Behavior

• Respect NO_COLOR environment variable
• Detect TERM=dumb and disable colors
• Detect TTY vs pipe and adjust output accordingly
• Use colored output by default when connected to TTY
• Use plain text when output is piped

Interactive Prompts

• Only prompt when connected to a TTY
• Provide --no-input or --force for non-interactive mode
• Default to safe choice (e.g., "N" for destructive operations)
• Exit with error code if prompt needed but in non-interactive mode

Destructive Operations

• Always require confirmation when interactive
• Provide --force flag for automation
• Use --dry-run to preview impact
• Clear, explicit warnings about consequences
• Consider undo/rollback mechanisms

Error Handling

• Write errors to stderr, not stdout
• Use specific exit codes for different error types
• Provide actionable error messages
• Suggest fixes when possible
• Include context (what failed, why, how to fix)

Reference Guidelines

This skill follows the established CLI best practices from:

• https://clig.dev/ - Command Line Interface Guidelines

Key principles:

• Human-first design - Optimize for clarity and discoverability
• Composability - Work well with pipes and other tools
• Consistency - Follow POSIX conventions where appropriate
• Robustness - Handle errors gracefully
• Accessibility - Support different terminal capabilities

Additional Resources

For comprehensive CLI design patterns and best practices, consult references/cli-guidelines.md.

Implementation Notes

• This skill is language-agnostic unless you request specific parsing library recommendations
• Focus on interface design before writing implementation code
• Keep specifications compact and implementable
• Iterate on design based on user feedback
• Consider both human users and automation scripts
• Test CLI behavior in different environments (TTY, pipes, CI)

Common CLI Patterns

Progress Indicators

# Simple spinner for long operations
mycli process --verbose
⠋ Processing files... (15/100)

# Progress bar
[=========>          ] 45% (450/1000 files)

# Suppress with --quiet
mycli process --quiet    # No progress output

Table Output

# Human-readable table
ID    NAME           STATUS    UPDATED
1     project-a      active    2h ago
2     project-b      paused    1d ago

# JSON for scripts
mycli list --format=json
[{"id":1,"name":"project-a","status":"active"}]

Colored Output

# Colors when TTY
✓ Success message (green)
⚠ Warning message (yellow)
✗ Error message (red)

# Plain text when piped or NO_COLOR=1
+ Success message
! Warning message
x Error message

Best Practices

1. Start simple - Add complexity only when needed 2. Document thoroughly - Good help text is essential 3. Test edge cases - Empty input, large input, concurrent usage 4. Provide examples - Show common use cases in help 5. Consider accessibility - Screen readers, different terminals 6. Plan for evolution - Design for future extensions 7. Fail fast - Validate input early 8. Be predictable - Follow conventions and user expectations

Example Design Session

User: "I need to design a CLI for deploying applications to different environments"

Response: "Let me help design that deployment CLI. A few clarifying questions:

1. Environments: What environments will you deploy to? (dev, staging, production, etc.) 2. Input: How will users specify what to deploy? (current directory, specific path, Git ref) 3. Authentication: How will it authenticate? (API tokens, credentials, SSH keys) 4. Output: What feedback do users need? (deployment status, logs, URLs) 5. Safety: Should production deployments require confirmation?

Based on your answers, I'll design a complete CLI spec with commands, flags, and safety mechanisms."

[After clarification, provide complete spec using the structure above]

CLI Design Guidelines Reference

This reference points to authoritative CLI design resources.

Primary Resource

Command Line Interface Guidelines

• Website: https://clig.dev/
• Repository: https://github.com/cli-guidelines/cli-guidelines

This comprehensive guide covers:

• Philosophy and principles of good CLI design
• Argument and flag conventions
• Output formatting and styling
• Error handling and exit codes
• Configuration and environment variables
• Interactivity and prompting
• Documentation and help text
• Subcommands and command organization
• Future-proofing and evolution

Key Principles Summary

1. Human-First Design

• Make help easily discoverable
• Provide clear, actionable error messages
• Use colors and formatting to enhance readability (when appropriate)
• Design for both beginners and experts

2. Composability

• Output to stdout, errors to stderr
• Support piping and redirection
• Provide machine-readable output options (JSON, etc.)
• Exit with appropriate codes
• Respect standard input/output conventions

3. Consistency

• Follow POSIX conventions where appropriate
• Use standard flags (--help, --version, --verbose)
• Be consistent with popular tools
• Maintain internal consistency across subcommands

4. Robustness

• Validate input early
• Handle errors gracefully
• Provide meaningful error messages
• Support --dry-run for destructive operations
• Allow undo when possible

5. Discoverability

• Make help comprehensive but scannable
• Provide examples in documentation
• Use progressive disclosure (basic → advanced)
• Include man pages or comprehensive docs

Standard Flag Conventions

Information Flags

• -h, --help - Show help and exit
• --version - Show version information
• -v, --verbose - Enable verbose output
• -q, --quiet - Suppress non-essential output
• --debug - Enable debug mode

Behavior Modifiers

• -f, --force - Skip confirmations, force action
• -i, --interactive - Enable interactive mode
• -y, --yes - Answer yes to all prompts
• -n, --dry-run - Simulate without making changes
• --no-color - Disable colored output

Output Control

• -o, --output <path> - Specify output file
• --format <type> - Specify output format
• --json - Output as JSON
• --pretty - Human-friendly formatting

Exit Code Conventions

0     Success
1     General error
2     Misuse (invalid arguments/flags)
64    Command line usage error (BSD convention)
65    Data format error
66    Cannot open input
69    Service unavailable
70    Internal software error
73    Cannot create output
74    I/O error
75    Temporary failure
77    Permission denied
78    Configuration error
130   Terminated by Ctrl+C (SIGINT)

Output Best Practices

Standard Output (stdout)

• Primary command output
• Machine-parseable results
• Piped data

Standard Error (stderr)

• Error messages
• Warnings
• Progress indicators
• Diagnostic information
• Verbose/debug output

Colors and Formatting

• Use ANSI colors when outputting to TTY
• Respect NO_COLOR environment variable
• Detect TERM=dumb and disable formatting
• Provide --no-color flag
• Use semantic colors (green=success, yellow=warning, red=error)

Configuration Precedence

Standard precedence order (highest to lowest): 1. Command-line flags and arguments 2. Environment variables (typically prefixed with app name) 3. User configuration files (~/.config/app/config) 4. System configuration files (/etc/app/config) 5. Built-in defaults

Interactive vs Non-Interactive

When to Prompt

• TTY detected and not disabled
• Destructive operation without --force
• Ambiguous input requiring clarification
• Optional enhancement (e.g., creating config file)

Non-Interactive Behavior

• Detect when stdin is not a TTY
• Provide --no-input or --force flags
• Exit with error if prompt needed but unavailable
• Support default values for prompts

Error Message Guidelines

Good error messages should: 1. State what went wrong - Clearly identify the problem 2. Explain why - Help users understand the cause 3. Suggest how to fix - Provide actionable next steps 4. Show context - Include relevant details (file names, values)

Examples

Bad:

Error: failed

Good:

Error: Cannot read config file '/home/user/.myapp/config.yml'
Reason: File does not exist
Fix: Run 'myapp init' to create a new config file, or use --config to specify a different location

Help Text Structure

NAME
  command - brief description

SYNOPSIS
  command [global-options] <subcommand> [options] [arguments]

DESCRIPTION
  Longer description explaining what the command does and when to use it.

COMMANDS
  init        Initialize a new project
  build       Build the project
  deploy      Deploy to production

OPTIONS
  -h, --help        Show this help message
  --version         Show version information
  -v, --verbose     Enable verbose output
  -c, --config PATH Specify config file

EXAMPLES
  # Initialize a new project
  command init my-project

  # Build with custom config
  command build --config custom.yml

  # Deploy to production (with confirmation)
  command deploy --env production

SEE ALSO
  Documentation: https://example.com/docs
  Report issues: https://example.com/issues

Subcommand Organization

For complex CLIs with multiple subcommands:

Flat Structure (few commands)

mycli init
mycli build
mycli deploy
mycli status

Grouped Structure (many commands)

mycli project init
mycli project delete

mycli build start
mycli build watch

mycli deploy staging
mycli deploy production

Alias Support

mycli i      # Alias for 'init'
mycli b      # Alias for 'build'
mycli d      # Alias for 'deploy'

Additional Resources

• POSIX Utility Conventions: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
• GNU Coding Standards: https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
• 12 Factor CLI Apps: https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46
• CLI Guidelines: https://github.com/cli-guidelines/cli-guidelines

Testing Checklist

Test your CLI design:

• [ ] Help text is clear and comprehensive
• [ ] Works in TTY and non-TTY environments
• [ ] Respects NO_COLOR environment variable
• [ ] Handles Ctrl+C gracefully
• [ ] Validates input before executing
• [ ] Provides meaningful error messages
• [ ] Exit codes are appropriate
• [ ] Works with pipes and redirection
• [ ] Configuration precedence is correct
• [ ] Documentation is complete and accurate