Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

sota-cli-ux

/sota-cli-ux

Pomaga projektować narzędzia wiersza poleceń: komendy i flagi, wyjście stdout i stderr, tryb --json, kody wyjścia, sygnały, dry-run, uzupełnianie i dystrybucję pakietów.

Repozytorium
SOTA-skills ↗
Licencja
CC-BY-4.0
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

CC-BY-4.0, otwarta.

Co robi i kiedy

Pomaga projektować narzędzia wiersza poleceń: komendy i flagi, wyjście stdout i stderr, tryb --json, kody wyjścia, sygnały, dry-run, uzupełnianie i dystrybucję pakietów.

Oryginalny opis (EN)

State-of-the-art CLI and developer-tool UX guidance (2026) covering command and flag design, output and interaction (stdout/stderr, --json, TTY detection, exit codes, prompts), runtime behavior and lifecycle (signals, dry-run, idempotency, XDG paths, completions, telemetry), and distribution (packaging, checksums, docs). Use when designing or building any command line tool, subcommand, TUI, or developer tool — in any framework (argparse, click, typer, clap, cobra, oclif, commander) — AND when auditing an existing CLI for usability, scriptability, and compatibility. Not for shell-script correct

Jak działa

  1. Purpose
  2. BUILD mode
  3. AUDIT mode
  4. Rules index
  5. Top-10 non-negotiables
Sekcje z nagłówków SKILL.md, w oryginale · 130 linii, 1 210 słów
Podgląd SKILL.md
---
name: sota-cli-ux
description: >-
  State-of-the-art CLI and developer-tool UX guidance (2026) covering command
  and flag design, output and interaction (stdout/stderr, --json, TTY
  detection, exit codes, prompts), runtime behavior and lifecycle (signals,
  dry-run, idempotency, XDG paths, completions, telemetry), and distribution
  (packaging, checksums, docs). Use when designing or building any command
  line tool, subcommand, TUI, or developer tool — in any framework (argparse,
  click, typer, clap, cobra, oclif, commander) — AND when auditing an existing
  CLI for usability, scriptability, and compatibility. Not for shell-script
  correctness or security — use sota-shell-scripting. Trigger keywords: CLI,
  command line tool, flags, subcommands, terminal output, TUI, developer tool,
  argparse, clap, cobra, exit code, shell completion, man page, stdin, stdout.
---

# SOTA CLI & Developer-Tool UX

## Purpose

Expert-level rules for building and auditing command-line tools: the grammar of
commands/flags/args, config layering, human-vs-machine output, TTY-aware
interaction, exit codes, signal handling, lifecycle behavior, and distribution.
The core thesis: **a CLI has three users — a human at a TTY, a script in CI,
and an AI agent driving the tool (a stricter script) — and every design
decision must serve all three without flags-gymnastics.** Rules are
imperative with rationale and good/bad terminal examples; every rules file ends
with an audit checklist. Load only the files relevant to the task via the index
below.

## BUILD mode

When designing or implementing a CLI:

1. **Design the command grammar before writing code.** Write the `--help` text
   first: subcommand tree, every flag (short + long), args, examples. If the
   help is hard to write, the grammar is wrong ([`rules/01`](rules/01-commands-flags-config.md)).
2. **Defaults carry the common path.** A new user must get a useful result with
   zero flags. Anything required for the 80% case is a design bug ([`rules/01`](rules/01-commands-flags-config.md) §3).
3. **Split the streams from day one**: primary output → stdout, everything else
   (logs, progress, prompts, errors) → stderr. Retrofitting this breaks users'
   pipes ([`rules/02`](rules/02-output-interaction.md) §1).
4. **Make it pipe-safe by default**: detect TTY; disable color/progress/prompts
   when piped; honor `NO_COLOR`; ship `--json` with every listing/reading
   command from v0.1, because output format is API ([`rules/02`](rules/02-output-interaction.md)).
5. **Treat exit codes, flags, env vars, and JSON shapes as a public API**:
   document them, version them, deprecate — never repurpose or remove without a
   cycle ([`rules/02`](rules/02-output-interaction.md) §3, [`rules/03`](rules/03-behavior-lifecycle.md) §7).
6. **Build the unhappy paths with the happy path**: Ctrl-C cleanup, `--dry-run`
   on mutating commands, re-runnable/resumable operations, stdin-closed CI
   behavior, offline behavior ([`rules/03`](rules/03-behavior-lifecycle.md)).
7. **Plan distribution early**: single static binary if the ecosystem allows,
   checksums + signatures, completions and man page generated from the same
   source as `--help` ([`rules/03`](rules/03-behavior-lifecycle.md) §8, [`rules/04`](rules/04-distribution-docs.md)).
8. Before declaring done, run every relevant **Audit checklist** against your
   own tool, including the brutal smoke test: `tool cmd | cat`,
   `tool cmd > out.txt 2> err.txt`, `tool cmd < /dev/null`, `echo $?`.

## AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

When reviewing an existing CLI:

1. Identify the surface: parser setup (argparse/clap/cobra/etc.), main/entry
   point, output and error paths, signal handlers, config loading, install/
   release scripts. Load the matching rules files.
2. **Run the tool, don't just read it.** Minimum probe set:
   - `tool --help`, `tool <sub> -h`, `tool --version`, `tool definitelynotacmd`
   - `tool list | cat` and `tool list | head -1` (color codes? broken pipe panic?)
   - `tool list > /dev/null` — does anything still reach the human? (it should, on stderr)
   - `tool mutate < /dev/null` — hang waiting for a prompt = CI killer
   - `echo $?` after success, after a usage error, after a real failure
   - Ctrl-C mid-operation: prompt state restored? partial state cleaned or resumable?
3. Then verify in code what can't be probed: config precedence order, secret
   handling, temp/state file locations, update/telemetry behavior.

### Severity conventions

- **Critical** — corrupts data or destroys trust: destructive op with no
  confirmation/`--force` and no dry-run; non-zero work reported as exit 0 (or
  vice versa) so CI lies; prompt hangs forever with stdin closed; secrets
  echoed to terminal/logs/argv; auto-update or telemetry without disclosure.
- **High** — breaks scripting or interrupts users: machine output polluted by
  ANSI codes/log lines on stdout; no `--json` on listing commands; SIGINT
  leaves corrupt partial state; undocumented/colliding exit codes; config
  precedence nondeterministic; breaking flag removal without deprecation.
- **Medium** — erodes usability: missing long forms; required flags on common
  path; no progress on >2s ops; errors without remediation; `$HOME` dotfile
  litter instead of XDG; no completions; no `-q`/`-v`; >500ms `--help`.
- **Low** — polish: help without examples, no suggest-on-typo, inconsistent
  subcommand naming, missing man page, table borders in output.

### Finding format

```
[SEVERITY] <one-line title>
Where: <file:line | command invocation that reproduces it>
Rule: <rules-file §section>
Issue: <what is wrong, with observed evidence (transcript or code)>
Impact: <who breaks: the human at the TTY, the script in CI, an agent driving the tool, or all>
Fix: <specific change; exact flag/stream/exit-code where load-bearing>
```

Order findings by severity; one finding per root cause; include the reproducing
command line whenever the issue was observed by running the tool.

## Rules index

| File | Read this when... |
|---|---|
| [`rules/01-commands-flags-config.md`](rules/01-commands-flags-config.md) | Designing/auditing the command surface: subcommand grammar (noun-verb consistency), POSIX/GNU flag conventions, short/long forms, `--` separator, args vs flags vs stdin, defaults, dangerous-op flags, config precedence chain, env var naming, help text quality, suggest-on-typo. |
| [`rules/02-output-interaction.md`](rules/02-output-interaction.md) | Anything the tool prints or asks: stdout vs stderr contract, `--json`/`--plain`, TTY detection, color and `NO_COLOR`/`TERM`, exit codes as API, streaming vs buffering, progress indication, prompts and `--yes`/CI behavior, quiet/verbose levels, error message anatomy, `--debug` vs stack traces, agent-facing design (`--fields`, confirmation envelopes, frozen output contracts). |
| [`rules/03-behavior-lifecycle.md`](rules/03-behavior-lifecycle.md) | Runtime behavior and tool lifecycle: startup latency, idempotent re-runnable commands, `--dry-run`, `--self-test` for tools whose output is a verdict, SIGINT/SIGTERM handling, crash-only resumable design, network-op responsiveness and offline behavior, self-update caution, telemetry consent, XDG base directories, shell completions, semantic versioning of the CLI surface. |
| [`rules/04-distribution-docs.md`](rules/04-distribution-docs.md) | Shipping and documenting: single-binary packaging, install channels (brew/curl-script/registry) with checksums + signatures, docs generated from the `--help` source of truth, man pages, README quickstart, version pinning for CI. |

## Top-10 non-negotiables

1. **Primary output to stdout, everything else to stderr** — logs, progress,
   prompts, warnings, errors. `tool x | next` must receive only data. ([rules/02](rules/02-output-interaction.md) §1)
2. **Pipe-safe by default**: TTY-detect; no color, no spinners, no prompts when
   piped; honor `NO_COLOR` (set and non-empty) and `TERM=dumb`; `--json` on
   every command that lists or reads data. ([rules/02](rules/02-output-interaction.md) §2, §4)
3. **Exit 0 only on success; distinct, documented nonzero codes** for usage
   error vs operational failure; never `exit 0` after printing an error. ([rules/02](rules/02-output-interaction.md) §3)
4. **Every flag has a long form**; short forms only for the frequent few;
   GNU/POSIX syntax (`-f`, `--flag`, `--flag=value`, `--` ends flags). ([rules/01](rules/01-commands-flags-config.md) §2)
5. **No required flags on the common path** — good defaults; and the reverse:
   destructive operations require explicit `--force`/typed confirmation on a
   TTY and refuse (don't hang) without one. ([rules/01](rules/01-commands-flags-config.md) §3, §5)
6. **Every prompt is skippable**: `--yes`/`--no-input` equivalent exists; stdin
   closed or non-TTY ⇒ use default or fail fast with the flag to pass — never
   block CI. ([rules/02](rules/02-output-interaction.md) §6)
7. **Errors say what failed, why, and what to do next** — path, value, and the
   exact command to run; stack traces only under `--debug`. ([rules/02](rules/02-output-interaction.md) §7)
8. **Ctrl-C is sacred**: first SIGINT exits promptly with cleanup and exit code
   130, second SIGINT force-quits; terminal state always restored; interrupted
   work is resumable or rolled back. ([rules/03](rules/03-behavior-lifecycle.md) §3)
9. **`--dry-run` on every mutating command**, printing the real plan through
   the real code path. ([rules/03](rules/03-behavior-lifecycle.md) §2)
10. **The CLI surface is a semver'd API**: flags, exit codes, JSON fields, env
    vars. Deprecate with warnings for a full cycle; never silently change
    meaning. Config precedence is exactly flags > env > project config > user
    config > defaults, documented. ([rules/01](rules/01-commands-flags-config.md) §6, [rules/03](rules/03-behavior-lifecycle.md) §7)
Pliki w paczce (5)
  • SKILL.md 10 KB
  • rules/01-commands-flags-config.md 13 KB
  • rules/02-output-interaction.md 15 KB
  • rules/03-behavior-lifecycle.md 16 KB
  • rules/04-distribution-docs.md 7 KB

Wersje

W bazie nie ma innych skilli o nazwie sota-cli-ux.

Migawka bazy z 13.11.2026 · wersja paczki 376ba7902ffb (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100cli-style
    Stosuje system projektowy CLI i Agent-Experience autorstwa Steve'a Francii (spf13) z 56 zasadami CLI Style: wykrywanie TTY dla każdego strumienia, typowane strumienie i semantyczne kody wyjścia przy projektowaniu i audycie CLI.
  • 100build-cli
    Pomaga tworzyć i rozbudowywać narzędzia wiersza poleceń w TypeScript, Go, Pythonie lub Rust: podpolecenia, typowane argumenty, priorytety konfiguracji, --json, kody wyjścia, --dry-run i testy uruchamiające binarkę.
  • 95cli-design
    Opisuje wzorce projektowania composable CLI w stylu Unix: rozdział stdout i stderr, flagi formatu (--json, --plain), kody wyjścia, wykrywanie TTY, kompozycja i projekt błędów.
  • 90CLI Artisan Agent
    Podpowiada, jak projektować interfejsy wiersza poleceń: flagi, podkomendy, komunikaty błędów i pasek postępu.
  • 91cli
    Wspiera budowę narzędzi wiersza poleceń i aplikacji terminalowych w Pythonie: argparse, click, typer, rich, TUI w textual, testy CLI, formatowanie wyjścia i kody wyjścia.
  • 100unix-cli
    Podaje wytyczne projektowania narzędzi wiersza poleceń w duchu UNIX: konwencje POSIX, kody wyjścia, strumienie stdout i stderr, sygnały oraz skrypty powłoki.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.