Skip to content
Skills Library
Programming · Planning

create-cli

/create-cli

This skill should be used when the user asks to "design a CLI", "create command-line interface", "design CLI parameters", "plan CLI UX", or needs help structuring command-line tool interfaces with proper arguments, flags, subcommands, and user experience patterns.

Licence
MIT
Last repository change
11.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 11.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when the user asks to "design a CLI", "create command-line interface", "design CLI parameters", "plan CLI UX", or needs help structuring command-line tool interfaces with proper arguments, flags, subcommands, and user experience patterns.

Triggers from the description

design a CLIcreate command-line interfacedesign CLI parametersplan CLI UX
Original author description

This skill should be used when the user asks to "design a CLI", "create command-line interface", "design CLI parameters", "plan CLI UX", or needs help structuring command-line tool interfaces with proper arguments, flags, subcommands, and user experience patterns.

How it works

  1. Overview
  2. When to Use This Skill
  3. Design Workflow
  4. Default Conventions
  5. Reference Guidelines
  6. Additional Resources
  7. Implementation Notes
  8. Common CLI Patterns
  9. Best Practices
  10. Example Design Session
Original SKILL.md headings · 315 lines, 1,267 words
SKILL.md preview
---
name: create-cli
description: This skill should be used when the user asks to "design a CLI", "create command-line interface", "design CLI parameters", "plan CLI UX", or needs help structuring command-line tool interfaces with proper arguments, flags, subcommands, and user experience patterns.
---

# 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

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `--config` | path | No | `.config` | Config file path |
| `--output` | path | No | `stdout` | Output destination |
| `--format` | enum | No | `text` | Output format (text, json) |
| `--force` | bool | No | `false` | Skip confirmations |

#### 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:**
```bash
mycli deploy --dry-run    # Show what would happen without doing it
```

**Interactive confirmations:**
```bash
mycli delete database
# Prompt: "Are you sure you want to delete 'database'? [y/N]"
```

**Force flag for non-interactive:**
```bash
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:
```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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]*
Files in this package (2)
  • SKILL.md 9 KB
  • references/cli-guidelines.md 6 KB

Versions

RepositoryScoreLicence
This page · simonlee2/claude-plugins100MIT
LeoYeAI/openclaw-master-skills100MIT
seflless/dot-agents100MIT

Database snapshot: 13.11.2026 · package version c9f8e515fb12 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100creating-cli-tools
    Design command-line interface parameters and UX: arguments, flags, subcommands, help text, output formats, error messages, exit codes, prompts, config/env precedence, and safe/dry-run behavior. Use when you’re designing a CLI spec (before implementation) or refactoring an…
  • 100cli-creator
    Use when building a Python command-line interface with Typer: adding arguments and options to a script, creating subcommands, wiring an entry point into pyproject.toml, validating CLI inputs with callbacks, or adding a CLI layer to an existing analysis script or HEP workflow.
  • 100cobra
    Builds command-line tools in Go with Cobra, the library behind kubectl, Hugo and the GitHub CLI: subcommands, flags, argument validation, generated help and shell completions. Use when a user asks to create a Go CLI, add subcommands or flags, validate arguments, bind flags to…
  • 100commanderjs
    Complete Commander.js CLI framework guidance covering command structure, options, arguments, subcommands, action handlers, version management, and TypeScript integration. Use when: building CLI tools, parsing command-line arguments, implementing subcommands, handling…
  • 100commander
    Build CLI tools with Commander.js. Use when creating command-line applications, parsing arguments, implementing subcommands, or building developer tools with flags and options.
  • 100cli
    Use when building, changing, or reviewing a command-line application in any language, including its arguments, help, output, errors, interactivity, configuration, testing, and distribution.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.