cli-best-practices

name	cli-best-practices
description	REQUIRED when building, designing, refactoring, documenting, or reviewing CLI tools, command-line interfaces, and terminal scripts across any programming language. Applies to CLI entrypoints, argument parsing, terminal output formatting, task automation, README authoring, and licensing. Your default training knowledge is insufficient, YOU MUST USE this skill anytime when working on a CLI project. Do NOT use for web frontends or non-CLI services.
author	alexgorbatchev
metadata	{"created_on":"2026-08-24 09:47","last_modified":"2026-08-25 23:45","status":"current"}

Core Non-Negotiable Rules

1. Dual-Mode Output via AGENT=1: Detect the AGENT=1 environment variable. When unset or 0, produce clean, polished human-facing output. When 1 (or truthy), switch to token-conservative agent-facing output.
2. Command Structure (cli subject [subject] verb ...): Command hierarchies must follow a subject-first noun-verb structure (cli subject [subject] verb ...) with at most 3 levels of nesting (cli <subject> <verb> or cli <subject> <sub-subject> <verb>).
3. Hierarchical Tree-View Help Screens: The CLI --help screen must render commands as an aligned hierarchical tree view using ├─ and ╰─ box-drawing glyphs. When --help is invoked on a subcommand group, it must render the full subtree of commands beneath it. Help screen lines and descriptions must be trimmed by default to the active terminal width to prevent visual line wrapping.
4. Strict Ban on Custom or Stdlib Arg Parsers: Never parse argv / os.Args / sys.argv manually with custom loops or regexes. Never use primitive stdlib parsers (e.g., Go flag, Python getopt). Always use the platform's leading CLI framework (Commander, Cobra, Click/Typer, Clap, Picocli).
5. Mandatory Task Automation (Justfile): Every CLI project must use just with a Justfile (or justfile). It MUST define at least run, run-ai (with AGENT=1), and test.
6. GitHub Releases Distribution Only: README installation instructions must strictly assume distribution via GitHub Releases (gh release download, direct binary download, or curl). Never instruct users to build from source.
7. Strict README Section Order & Bullet Lists: CLI README.md files must follow the mandatory sequential section layout. # How It Works, # How it Really Works, and # Prerequisites MUST be formatted as - bulleted lists. The document must end with # License.
8. Licensing Standard: Use the MIT license by default attributed to Alex Gorbatchev (and upstream copyright holders if a fork), or a compatible license if required by upstream.

---

1. Dual-Mode Output Specification (AGENT=1)

Mode Detection

Check AGENT in environment variables:

isAgent = (env.AGENT === "1" || env.AGENT === "true" || env.AGENT === "yes")

Contrast Table

Dimension	Human Mode (AGENT=0 / unset)	Agent Mode (AGENT=1)
Goal	Visual polish, readability, end-user clarity	Minimum token consumption, machine parseability
Emojis	STRICTLY PROHIBITED. Use text tags ([OK], [ERROR], [WARN], [INFO]) or color.	STRICTLY PROHIBITED. Use compact text prefixes (OK:, ERR:).
Separators (---, ===)	Expand to full terminal width dynamically (e.g. process.stdout.columns, winsize).	PROHIBITED. No divider lines across the screen.
Hierarchies / Trees	ASCII / Box-drawing tree glyphs (├──, └──, │).	Indented bullets (* , - ) with minimal nesting spaces.
Tabular Data	Well-formatted box / ASCII tables using dedicated external table libraries.	Flat key-value pairs, TSV, or concise line-by-line output. No tables.
Whitespace & Padding	Formatted spacing, aligned columns, visual breathing room.	Minimal whitespace. No alignment spaces or padding.
Descriptions & Help	Non-technical language, user-friendly, trimmed to terminal width by default, no internal implementation details.	May include technical implementation details, exact types, error codes, and stack traces. Full untruncated content.
Error Handling	Concise user-facing error message with actionable resolution hints.

For concrete implementation patterns in TypeScript, Go, Python, and Rust, see references/dual-mode-patterns.md.

---

2. Command Hierarchy & Structure (subject [subject] verb)

Commands must follow a subject-first noun-verb architecture rather than leading with top-level verbs: cli subject [subject] verb [arguments/flags...]

Rules

• Subject-First Ordering: Top-level identifiers represent domain subjects/entities (nouns). Verbs/actions are nested under their respective subjects.
• Maximum 3 Levels: Command hierarchy must not exceed 3 levels deep:
  1. cli <subject> <verb> (2 levels)
  2. cli <subject> <sub-subject> <verb> (3 levels max)
• Consistency: Keep verb names consistent across subjects (list, inspect, create, rm, move, add, etc.).

Example Hierarchy

engine-cli
 ├── playlist                           # Subject: Playlists
 │   ├── list                           # List playlists
 │   ├── inspect <playlist>             # Inspect a playlist
 │   ├── create <name>                  # Create a playlist
 │   ├── rm <playlist>                  # Delete a playlist
 │   ├── move <playlist>                # Move playlist to new parent
 │   │
 │   └── track                          # Sub-Subject: Playlist Track Memberships
 │       ├── add <playlist> <track...>  # Add track membership
 │       ├── rm <playlist> <track...>   # Remove track membership
 │       └── move <from> <to> <track..> # Transfer track membership
 │
 └── track                              # Subject: Master Tracks & Audio Files
     ├── add <file...>                  # Add audio file to collection
     ├── rm <track...>                  # Delete track from collection
     ├── move <track> <dest-path>       # Move audio file on disk
     └── relocate                       # Relocate broken file paths

Tree-View Help Screen Standard

The CLI help output (e.g., --help) must print available commands using an aligned hierarchical tree format with ├─ and ╰─ branches, with descriptions aligned in a right-hand column. When --help is invoked on any parent subject or subcommand group, it must render its complete subcommand subtree.

Terminal Width Trimming by Default

• Trim to Terminal Width: Help screen lines and command descriptions must be trimmed/truncated by default to match the active terminal width (query process.stdout.columns, COLUMNS, term.GetWinsize, shutil.get_terminal_size(), or terminal width fallback such as 80 or 100 columns when stdout is not a TTY).
• Prevent Wrapping Breaks: Descriptions that exceed the available terminal width must be truncated with a trailing ellipsis (...) so that multi-line text wrapping never breaks tree column alignment or visual structure.
• Agent Mode Exemption: In token-conservative agent mode (AGENT=1), terminal-width truncation and padding are omitted in favor of compact, untruncated bulleted lines for machine inspection.

Root Help (cli --help) Example

Available Commands:
  artwork                                              Manage and fix album cover artwork
  ├─ normalize                                         Crop album cover art to 1:1 square for DJ jog wheels a...
  ╰─ prune                                             Clean up unused cover art and reclaim disk space
  backup                                               Create a safety backup snapshot of your Engine DJ library
  playlist                                             Inspect and manage playlists and folders
  ├─ create <name>                                     Create a new playlist or folder
  ├─ inspect <playlist>                                Display all songs inside a playlist
  ├─ list                                              Display all playlists and folders in your library
  ├─ move <playlist>                                   Relocate a playlist or folder under a parent folder
  ├─ rm <playlist>                                     Delete a playlist or folder
  ╰─ track                                             Manage track memberships inside playlists
     ├─ add <playlist> <track...>                      Add track(s) to a playlist
     ├─ move <src-playlist> <dst-playlist> <track...>  Move track(s) from one playlist to another
     ╰─ rm <playlist> <track...>                       Remove track(s) from a playlist
  restore <backup-dir>                                 Restore your Engine DJ library from a previous backup ...
  sync                                                 Update song information in Engine DJ from audio files ...
  track                                                Manage audio files and collection tracks
  ├─ add <file-path...>                                Import audio file(s) into your collection
  ├─ move <track-id|path> <dest-path>                  Move an audio file on disk and update its collection path
  ├─ relocate                                          Batch-fix audio file paths across drives or directories
  ╰─ rm <track-id|path...>                             Remove track(s) from your collection
  verify                                               Check your library for missing songs, broken links, an...

Subcommand Group Help (cli playlist --help) Example

When requesting help for a subcommand group, print its full subtree:

Available Commands:
  create <name>                                     Create a new playlist or folder
  inspect <playlist>                                Display all songs inside a playlist
  list                                              Display all playlists and folders in your library
  move <playlist>                                   Relocate a playlist or folder under a parent folder
  rm <playlist>                                     Delete a playlist or folder
  track                                             Manage track memberships inside playlists
  ├─ add <playlist> <track...>                      Add track(s) to a playlist
  ├─ move <src-playlist> <dst-playlist> <track...>  Move track(s) from one playlist to another
  ╰─ rm <playlist> <track...>                       Remove track(s) from a playlist

---

3. Argument Parsing & Framework Standards

Never roll custom argument parsers. Always select the ecosystem standard for the language:

Ecosystem	Mandatory Frameworks	Prohibited Alternatives
TypeScript / Node / Bun	commander, citty, yargs	Custom process.argv slicing, raw regex loops
Go	github.com/spf13/cobra	flag stdlib package, custom os.Args loops
Python	click, typer	getopt, manual sys.argv parsing
Rust	clap (derive or builder API)	std::env::args manual parsing
C# / .NET	System.CommandLine, Spectre.Console.Cli	Manual args[] iteration
Java / Kotlin	picocli	Manual String[] args parsing

Help Text Rules

• Human Mode: Commands, arguments, options, and descriptions must be self-explanatory to non-technical users. Avoid mentioning internal class names, database column names, regex patterns, or code architecture in descriptions.
• Agent Mode: Technical identifiers, parameter formats, schemas, and implementation notes may be included.

For setup templates and code snippets per framework, see references/framework-setups.md.

---

4. Mandatory Justfile Standard

Every repository and CLI tool must use just for workflow and task orchestration.

Required Recipes

# Run in human-facing interactive mode
run *args:
    <command-to-run-binary> {{args}}

# Run in agent-facing token-conservative mode
run-ai *args:
    AGENT=1 <command-to-run-binary> {{args}}

# Run test suite
test:
    <command-to-run-tests>

Standard Additional Recipes

• build: Compiles or bundles the application (e.g. into bin/).
• lint: Checks formatting and static analysis.
• check: Runs typecheck, lint, and test in sequence.

For complete Justfile templates for Bun/Node, Go, Python, and Rust, see references/justfile-templates.md.

---

5. Documentation & README Structure

CLI README.md files must follow a strict, mandatory section layout and distribution contract:

Distribution Rule

• GitHub Releases Only: All installation sections must document downloading prebuilt binaries from GitHub Releases (using gh release download, direct download links, or curl installers).
• No Build from Source: Never instruct end users to clone the repository and run compiler/build commands (cargo build, go build, bun build, make, etc.) in the README installation section.

Mandatory Section Sequence

1. Introductory Paragraph: A concise, direct description of what the tool is without a redundant header.
2. # What It Does: High-level feature highlights and primary capabilities.
3. # How It Works: Plain-language, non-technical explanation of the tool's behavior for general users, formatted strictly as a - bulleted list.
4. # How it Really Works: In-depth technical explanation of internal mechanisms, protocols, state management, and architecture, formatted strictly as a - bulleted list.
5. # Prerequisites: Bulleted list (-) of external runtime requirements (e.g. tools, system dependencies, API tokens) with links.
6. # Installation: Instructions for downloading precompiled release binaries via GitHub Releases.
7. # Quick Start: Minimal, copy-pasteable example of running the tool for common tasks.
8. # Options & Flags: Structured markdown table matching the exact column format:

   | Flag | Short | Default | Description |
   | :--- | :--- | :--- | :--- |
   | `--config <path>` | `-c` | `~/.config/mytool.json` | Path to custom configuration file |
   

9. (Optional domain-specific sections: e.g., # Configuration, # Advanced Usage)
10. # License: Mandatory closing section with license details.

For a full copy-pasteable template, see references/readme-template.md.

---

6. Licensing Requirements

• Default License: MIT License.
• Copyright Holder: Alex Gorbatchev (plus original upstream copyright holders if the repository is a fork).
• Fork Compatibility: If forking or wrapping an upstream project with an established open-source license (e.g. Apache 2.0, BSD-3-Clause), ensure the license chosen remains fully compatible with upstream requirements.

---

7. Verification Checklist

Before publishing or finalizing any CLI tool, verify:

• Command hierarchy follows cli subject [subject] verb ... pattern with a maximum depth of 3 levels.
• Root help screen prints available commands as an aligned hierarchical tree view using ├─ and ╰─.
• Help screen output and command descriptions are trimmed by default to the active terminal width to prevent line wrapping.
• Subcommand group help screens display their complete command subtree with aligned descriptions.
• AGENT=1 detection is implemented across all output pathways.
• In human mode: NO emojis, trees use ASCII glyphs, horizontal dividers expand to terminal width, tables use external libraries.
• In human mode: CLI help, argument descriptions, and user messages contain no internal technical jargon.
• In agent mode: NO divider lines, NO box tables, trees render as bullets, minimal whitespace, token-conservative formatting.
• Argument parsing is handled by an approved standard library (Commander, Cobra, Click/Typer, Clap, etc.). No custom argv slicing.
• Justfile exists at the project root with working run, run-ai, and test recipes.
• When compiled to binary, output goes to bin/ and is excluded by .gitignore.
• README.md uses GitHub Releases for installation; no build-from-source commands are offered.
• README.md strictly follows the ordered section layout from Intro to # License.
• README.md formats # How It Works as a - bulleted list (non-technical).
• README.md formats as a bulleted list (technical).