skills.rest
magarcia
magarciaCOMMUNITY
Explore all skills by this author →
Website𝕏@martinprinsGitHub

cli-design

Guide CLI creators in designing human-first command structures and messaging.

Updated Mar 31, 2026
Search Tags:#configuration#error-handling#interactivity#output-formatting#cli-design#command-structure#help-system
One-click install
npx skills add https://github.com/magarcia/pylon-sync --skill cli-design-magarcia
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cli-design
Source: https://github.com/magarcia/pylon-sync/tree/main/.agents/skills/cli-design
Command: npx skills add https://github.com/magarcia/pylon-sync --skill cli-design-magarcia

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Engineers and product teams often rush to ship CLIs that feel inconsistent, opaque, or fragile, so this guide captures human-first philosophies and best practices for command structure, output, error handling, configuration, and extensibility before code is written.

Core Features & Use Cases

  • Command structure templates: Stick to noun-verb patterns, limit nesting to two levels, favor descriptive flags, and ensure every flag has a long form and consistent global flags.
  • Output, help, and UX guidelines: Detect TTYs, route data to stdout while keeping messages on stderr, support json/llm formats, respect NO_COLOR, lead with examples in help, and provide next steps plus typo suggestions.
  • Error, interactivity, and robustness playbooks: Use namespaced error codes, define exit-code semantics, avoid stack traces, honor --no-input/--yes, confirm destructive actions, close gaps around signals, and keep performance visible within 100ms.
  • Configuration, auth, testing, distribution, and extensibility rules: Follow XDG precedence, accept tokens via env/config, outline testing and release checklists, and adopt plugin/alias naming conventions that match established CLI ecosystems.
  • Use Case: When reviewing an existing CLI or designing a new sync tool, apply these rules to ensure every command feels conversational, predictable, and safe across desktop and mobile contexts.

Quick Start

Ask the skill to audit your CLI prototype, tighten command structure, output, and error handling, and report usability fixes.

Frequently Asked Questions about cli-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a CLI command structure that scales well with subcommands?▼

Structure a CLI by applying noun-verb patterns, limiting nesting to two levels, and providing consistent global flags with long-form alternatives. This ensures command-line tools remain predictable and human-first as subcommands are added.

What is the best way to format CLI output for both human and machine readability?▼

Format CLI output by detecting TTYs, routing data to stdout while keeping messages on stderr, and supporting json/llm formats. Respecting NO_COLOR and adapting output modes ensures command-line interfaces work for both human operators and automated pipelines.

How do I handle errors in a CLI without showing stack traces to users?▼

Handle CLI errors by using namespaced error codes, defining clear exit-code semantics, and avoiding stack traces. Leading with actionable messaging and providing typo suggestions ensures command-line interfaces remain resilient and human-first during failures.

How should CLI configuration precedence work across environment variables and config files?▼

CLI configuration precedence should follow XDG directory specifications, accepting tokens via environment variables and config files. Establishing clear priority rules for configuration sources ensures command-line tools behave predictably across different deployment environments.

Can I use interactive prompts in a CLI while supporting automated pipelines?▼

Support interactive CLI prompts alongside automation by honoring --no-input and --yes flags, confirming destructive actions explicitly, and closing gaps around system signals. This ensures command-line interfaces remain safe for desktop use and compatible with non-interactive contexts.

When do I need to add help systems and typo suggestions to a command-line tool?▼

Add help systems and typo suggestions to a CLI when designing new tools or adding subcommands. Leading with examples in help output and providing next steps ensures command-line interfaces feel conversational and guide users toward successful interactions.

Related Skills

Explore More Software Engineering Skills→
cna-bootcampcna-bootcamp
23

service-planning

Automates service planning from MVP definition to prototype generation.

Official
Advanced
terzigoluterzigolu
37

oz-platform

Manage Oz cloud agents via Warp's REST API and CLI.

Community
Advanced
LeroyAdonisLeroyAdonis

better-auth-best-practices

Configure Better Auth servers and clients with adapters, plugins, and environment variables.

Community
Advanced
ssiumhassiumha
9

cli-guidelines-resources-02

Provide CLI design guidance for help, errors, flags, and subcommands.

Community
Advanced