dev-cli-consistency-audit

Original：🇺🇸 English

Translated

Reviews a CLI tool's command interface for consistency in argument naming, flag conventions, help text, and README alignment. Use when building CLI tools or before releasing CLI updates. Triggers: "review CLI arguments", "align CLI conventions", "CLI consistency check", "make sure commands are aligned", "review command interface".

10installs

Sourcejackchuka/skills

Added on2026-03-11

NPX Install

npx skill4agent add jackchuka/skills dev-cli-consistency-audit

SKILL.md Content

View Translation Comparison →

CLI Consistency Review

Systematic review of a CLI tool's command interface to ensure consistent naming, conventions, and documentation alignment.

Workflow

Step 1: Inventory Commands

Run the CLI with
```
--help
```
or
```
-h
```
to get the top-level command list
For each subcommand, run
```
<cmd> <subcmd> --help
```
to get its full interface
Build an inventory table:

| Command       | Positional Args  | Flags              | Output Formats |
|---------------|------------------|--------------------|----------------|
| pull          | owner/repo       | --issues, --prs    | table, json    |
| search        | [query]          | --type, --limit    | fzf            |
| prune         | owner/repo       | --confirm, --dry-run| table         |

Step 2: Convention Analysis

Check for consistency across all commands:

Positional vs Flag arguments:
- Is the same concept (e.g.,
```
owner/repo
```
  ) passed as positional in some commands and as
```
--repo
```
  flag in others?
- Recommendation: Pick one approach and apply everywhere
Flag naming:
- Are similar concepts named consistently? (e.g.,
```
--output
```
  vs
```
--format
```
  vs
```
-o
```
  )
- Do boolean flags follow the same pattern? (
```
--dry-run
```
  vs
```
--confirm
```
  vs
```
--yes
```
  )
- Are shorthand flags (
```
-f
```
  ,
```
-o
```
  ) assigned consistently?
Pluralization:
- Subcommand names: singular vs plural (e.g.,
```
list files
```
  vs
```
list file
```
  )
- Flag names:
```
--issue
```
  vs
```
--issues
```
Default behaviors:
- Are defaults consistent? (e.g., if one command defaults to
```
--format=table
```
  , do others?)
- Are destructive commands safe by default? (require
```
--confirm
```
  or
```
--force
```
  )
Error messages:
- Do error messages follow a consistent format?
- Are they actionable (tell the user what to do)?

Step 3: Documentation Alignment

Compare the README documentation with actual
```
--help
```
output:
- Are all commands documented?
- Do the documented flags match the actual implementation?
- Are examples up to date and runnable?
Check help text quality:
- Does each command have a one-line description?
- Are flag descriptions clear and consistent in style?
- Do examples in
```
--help
```
  text work?

Step 4: Report

Present findings:

CLI Consistency Review:

Inconsistencies Found:
1. [Issue] — [Commands affected] — [Suggested fix]
2. ...

Documentation Gaps:
1. [What's missing] — [Where]
2. ...

Recommendations:
1. [Convention to adopt] — [Rationale]
2. ...

Step 5: Apply Fixes

For each accepted fix:

Update the command implementation (flag names, defaults, etc.)
Update help text and descriptions
Update README to match
Run
```
--help
```
again to verify alignment

Best Practices Reference

Positional arguments: Use for the primary subject (e.g.,
```
owner/repo
```
). Limit to 1-2 positional args.
Flags: Use for modifiers and options. Always provide
```
--long-form
```
; add
```
-s
```
shorthand only for frequently used flags.
Boolean flags: Use
```
--flag
```
to enable (default off). For "default on" behaviors, use
```
--no-flag
```
to disable.
Output format: If supporting multiple formats, use
```
--format=table|json|yaml
```
consistently.
Destructive operations: Default to dry-run or require explicit
```
--confirm
```
.
Verbosity: Use
```
--verbose
```
/
```
-v
```
consistently. Consider
```
--quiet
```
/
```
-q
```
as well.

Examples

Example 1: Full CLI review

User: "review our cli arguments and make sure they are aligned"
Action:
1. Run --help for all commands
2. Build inventory table
3. Identify naming inconsistencies
4. Check README alignment
5. Present report with specific fixes

Example 2: Pre-release check

User: "make sure our command implementation and comments are aligned"
Action:
1. Compare help text with actual behavior
2. Verify README examples work
3. Check for undocumented flags
4. Update docs to match implementation