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

cli

/cli

Projektuje aplikacje wiersza poleceń: konwencje argumentów, strumienie wyjścia, kody wyjścia, hierarchię konfiguracji, tryby interaktywne i UX terminala.

Repozytorium
cc-foundry ↗
Licencja
MIT
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
8
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

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Projektuje aplikacje wiersza poleceń: konwencje argumentów, strumienie wyjścia, kody wyjścia, hierarchię konfiguracji, tryby interaktywne i UX terminala.

Oryginalny opis (EN)

CLI application design: argument conventions, output streams, exit codes, configuration hierarchy, interactive modes, and terminal UX. Invoke whenever task involves any interaction with command-line tools or terminal applications — building, reviewing, debugging, or designing CLI interfaces.

Jak działa

  1. References
  2. Output Streams
  3. Arguments
  4. Subcommands
  5. Exit Codes
  6. Configuration
  7. Color and Terminal Output
  8. Interactive Behavior
  9. Signal Handling
  10. Help Text
Sekcje z nagłówków SKILL.md, w oryginale · 201 linii, 1 647 słów
Podgląd SKILL.md
---
name: cli
description: >-
  CLI application design: argument conventions, output streams, exit codes,
  configuration hierarchy, interactive modes, and terminal UX. Invoke whenever
  task involves any interaction with command-line tools or terminal
  applications — building, reviewing, debugging, or designing CLI interfaces.
---

# CLI Design

**Programs are composable by default.** stdout carries data, stderr carries diagnostics, exit codes carry status, and
signals carry intent. Get the boundaries right and everything else follows.

## References

- **Arguments** [`${CLAUDE_SKILL_DIR}/references/arguments.md`] — Full POSIX guidelines, GNU long option table,
  subcommand patterns, flag design
- **Output** [`${CLAUDE_SKILL_DIR}/references/output.md`] — Stream separation details, color codes, ANSI escapes,
  NO_COLOR spec, pager setup
- **Exit codes** [`${CLAUDE_SKILL_DIR}/references/exit-codes.md`] — Standard/extended code tables, signal exit codes,
  partial success patterns
- **Interaction** [`${CLAUDE_SKILL_DIR}/references/interaction.md`] — TTY detection, prompting patterns, confirmation
  levels, progress display, error format
- **Configuration** [`${CLAUDE_SKILL_DIR}/references/configuration.md`] — Full hierarchy, XDG spec, env var catalog,
  config file formats, secret handling
- **Signals** [`${CLAUDE_SKILL_DIR}/references/signals.md`] — Full signal table, SIGPIPE handling, crash-only design,
  child process signals

## Output Streams

This is the single most important convention. Mixing data and diagnostics in stdout is the #1 way to break
composability.

- **stdout is data.** Primary output goes to stdout -- query results, computed values, formatted data. This is what gets
  piped to the next command or redirected to a file.
- **stderr is diagnostics.** Progress indicators, status messages, warnings, errors, and debug output go to stderr.
  Users see stderr in the terminal even when stdout is redirected.
- **Check each stream independently.** stdout may be piped while stderr is still a TTY. Adapt output format per-stream:
  human-readable when TTY, machine-parseable when piped.
- **No animations when not a TTY.** Disable spinners, progress bars, and color when the target stream is not an
  interactive terminal. This prevents CI logs from becoming escape-code garbage.
- **Print something within 100ms.** Before any network request or long operation, print a status line to stderr. Silence
  looks like a hang.
- **Tell the user what changed.** When a command modifies state, describe what happened and suggest what to do next.

## Arguments

- **POSIX short flags, GNU long flags.** Single-letter options use `-x`, multi-letter use `--long-name`. Every short
  flag must have a long equivalent. Reserve one-letter flags for frequently-used options.
- **`--` terminates options.** Everything after `--` is an operand, even if it starts with `-`. This is POSIX Guideline
  10 and is non-negotiable.
- **Prefer flags over positional arguments.** Flags are self-documenting. Exception: primary action on a single target
  (`rm file.txt`, `cat file.txt`). Two or more positional args for different things is a design smell.
- **`-` means stdin/stdout.** When a command accepts file arguments, `-` means read from stdin (or write to stdout when
  context is clear).
- **Use standard flag names.** `-h`/`--help`, `--version`, `-v`/`--verbose`, `-q`/`--quiet`, `-f`/`--force`,
  `-n`/`--dry-run`, `-o`/`--output`, `--json`, `--no-color`, `--no-input`. Don't reinvent these.
- **Make flags order-independent.** Users add flags by pressing up-arrow and appending. `mycmd --flag subcmd` and
  `mycmd subcmd --flag` should both work where possible.

## Subcommands

- **`noun verb` or `verb noun`, pick one and be consistent.** Don't mix ordering styles. `docker container create` and
  `docker image pull` follow `noun verb`.
- **Support help at every level.** `mycmd --help`, `mycmd subcmd --help`, and `mycmd help subcmd` should all work.
- **No catch-all subcommand.** Don't interpret unknown first arguments as an implicit default subcommand. This prevents
  you from ever adding new subcommands.
- **No arbitrary abbreviations.** If `mycmd i` aliases `mycmd install`, you can never add `mycmd init`. Aliases must be
  explicit and stable.

## Exit Codes

- **0 = success, 1 = error, 2 = usage error.** This covers most programs. Only define additional codes when callers need
  to distinguish specific failure modes.
- **Signal exit codes use 128+N.** SIGINT (Ctrl-C) exits 130, SIGTERM exits 143. Preserve this convention so calling
  scripts can distinguish "user cancelled" from "error."
- **Never return 0 on failure.** Scripts depend on exit codes via `$?` and `set -e`. A false success silently breaks
  pipelines.

## Configuration

- **Flags > env vars > project config > user config > system config > defaults.** This is the universal precedence
  hierarchy. A flag always wins over an env var, which always wins over a config file.
- **Follow XDG for user-level files.** Use `$XDG_CONFIG_HOME/myapp/` (default `~/.config/myapp/`), not `~/.myapp`.
  Respect `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`.
- **Respect well-known environment variables.** `NO_COLOR`, `FORCE_COLOR`, `DEBUG`, `EDITOR`, `PAGER`,
  `HTTP_PROXY`/`HTTPS_PROXY`, `TMPDIR`, `HOME`, `TERM`, `LINES`, `COLUMNS`. Check these before inventing app-specific
  alternatives.
- **Never read secrets from environment variables.** They leak through `ps`, Docker inspect, systemd, and process
  listings. Accept secrets via `--password-file`, stdin, or a credential helper.
- **Never read secrets from flags.** `--password=secret` leaks into `ps` output and shell history. Use `--password-file`
  or stdin.

## Color and Terminal Output

- **Disable color when:** stdout/stderr is not a TTY (check each independently), `NO_COLOR` is set and non-empty,
  `TERM=dumb`, or `--no-color` is passed.
- **Support `FORCE_COLOR` or `--color`** to override detection and force color output when the user explicitly wants it.
- **Use color intentionally.** Red for errors, green for success, yellow for warnings. Don't paint everything -- if
  everything is colored, nothing stands out.
- **Use a color library.** Don't hand-code ANSI escape sequences. Libraries handle NO_COLOR, TERM detection, and
  cross-platform differences.

## Interactive Behavior

- **Only prompt when stdin is a TTY.** If stdin is not interactive, fail with an error telling the user which flag to
  pass. Never hang waiting for input that will never come.
- **Provide `--no-input`.** An explicit flag to disable all prompts. Required for CI/CD, cron, and automation.
- **Confirm before destructive actions.** Prompt for `y/N` interactively, require `--force` non-interactively. For
  severe operations (deleting infrastructure), require typing the resource name.
- **Provide `--dry-run`.** For any state-modifying command, let users preview what would happen without executing it.
- **Don't echo passwords.** Disable terminal echo when accepting secret input. Provide `--password-file` as a
  non-interactive alternative.

## Signal Handling

- **Respond to SIGINT immediately.** Print "Shutting down..." before starting cleanup. Add a timeout so cleanup can't
  hang forever.
- **Second Ctrl-C skips cleanup.** Tell the user: "press Ctrl+C again to force." Then exit immediately.
- **Handle SIGTERM like SIGINT.** Process managers (systemd, Docker, K8s) send SIGTERM before SIGKILL. Complete cleanup
  within the grace period.
- **Handle SIGPIPE silently.** When the user pipes your output to `head`, don't print an error when the pipe closes.
  Exit quietly with code 141 or 0.
- **Design for crash recovery.** Use atomic file operations (write to temp, rename). Check for incomplete state on
  startup. Don't require cleanup to complete for correctness.

## Help Text

- **Support `-h` and `--help`.** Both must show help. Don't overload `-h` for anything else.
- **Show concise help with no arguments.** When a command requires arguments and gets none, show a brief description,
  one or two examples, and a pointer to `--help` for the full listing.
- **Lead with examples.** Users read examples first. Show common invocations before the flag catalog.
- **Suggest corrections.** When the user types a close misspelling, suggest the correct command. Don't auto-execute the
  suggestion.
- **Support `--version`.** Print the version and exit. Format: program name and version, optionally with build metadata.

## Error Messages

- **Structure errors consistently.** Use a format like: `error: <what went wrong>` followed by `hint: <how to fix it>`.
- **Be actionable.** Don't say "permission denied" -- say "permission denied; run with sudo or use --config-dir for a
  writable location."
- **Put important information last.** The eye lands at the bottom of output. Put the error summary and fix there, not
  the stack trace.
- **No stack traces by default.** Put them behind `--verbose` or write to a debug log file. Signal-to-noise ratio
  matters.
- **Make bug reporting easy.** For unexpected errors, provide a URL or command to file a bug, pre-populated with
  diagnostic information.

## Structured Output

- **Support `--json` for machine-readable output.** Output well-formed JSON to stdout. Use consistent field names across
  commands.
- **Support `--plain` for scriptable tabular output.** One record per line, no color, no decorations. Useful for `grep`
  and `awk` pipelines.
- **Use a pager for large output.** Pipe through `less -FIRX` when stdout is a TTY. Respect the `PAGER` environment
  variable. Don't page when output fits one screen.

## Robustness

- **Validate input early.** Check arguments and flags before starting work. Report all validation errors at once, not
  one at a time.
- **Make operations idempotent where possible.** Running the same command twice should produce the same result, not an
  error or doubled state.
- **Make operations recoverable.** If the program fails partway through, the user can hit up-arrow and enter to retry
  from where it left off.
- **Set network timeouts.** Allow timeout configuration and have a reasonable default. Never hang indefinitely on a
  network call.

## Naming

- **Lowercase, short, memorable.** `curl` not `DownloadURL`. Use only lowercase letters and hyphens. Keep it easy to
  type.
- **Avoid ambiguous subcommand names.** Don't have both "update" and "upgrade". Use distinct verbs or disambiguate with
  extra words.

## Future-Proofing

- **Keep changes additive.** Add new flags rather than changing existing behavior. If you must break compatibility, warn
  in advance.
- **Warn before deprecation.** When a user invokes a deprecated flag, tell them what to use instead and when the old
  form will be removed.
- **Changing human-readable output is OK.** Encourage `--json` or `--plain` for scripts. Human-readable output is not a
  stable interface.

## Application

When **writing** CLI code:

- Apply all conventions silently. Don't narrate each rule.
- Use an argument parsing library (clap, cobra, argparse, commander).
- Wire up stdout/stderr correctly from the start. Retrofitting is painful.
- Handle SIGINT/SIGTERM from day one. Don't defer signal handling.

When **reviewing** CLI code:

- Check stdout vs stderr usage first. This is the most common mistake.
- Verify exit codes match actual success/failure.
- Confirm `--help`, `--version`, and `--no-color` are supported.
- Look for secret leaks in flags and env vars.

## Integration

This skill covers CLI platform concerns -- the interface between a program and the terminal/shell/pipeline.
Language-specific implementation details (argument parsing libraries, terminal I/O APIs) come from language skills
(golang, javascript, etc.). The coding discipline skill governs general workflow.

**Programs are composable when they respect boundaries.**
Pliki w paczce (8)
  • SKILL.md 12 KB
  • .dev/reference-inventory.json 1 KB
  • references/arguments.md 5 KB
  • references/configuration.md 5 KB
  • references/exit-codes.md 2 KB
  • references/interaction.md 5 KB
  • references/output.md 5 KB
  • references/signals.md 4 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · xobotyi/cc-foundry100MIT
sparq-org/sparq100MIT
bendrucker/claude100MIT
yuri-xyz/skills100MIT
appwrite/claude-plugin95BSD-3-Clause
zzstoatzz/plyr-python-client95MIT
Tyler-R-Kendrick/agent-skills93MIT
Tyler-R-Kendrick/agent-skills91MIT
Esposter/Esposter90Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 7d4eb4ce562f (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-development
    Pomaga budować narzędzia wiersza poleceń: projekt argumentów, kody wyjścia, strumienie i potoki, wyjście postępu, kolejność konfiguracji i zachowanie zgodne z powłoką.
  • 100cli-tool-design
    Projektuje interfejsy wiersza poleceń z czytelnym parsowaniem argumentów, podkomendami, tekstem pomocy, formatowaniem wyjścia i kodami wyjścia, z użyciem Click, Typer i argparse.
  • 100audit-agentic-cli
    Ocenia lub projektuje narzędzie CLI do użycia przez agentów i modele: wyjście JSON, kody wyjścia i tryb nieinteraktywny.
  • 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.
  • 100creating-cli-tools
    Projektuje interfejs wiersza poleceń: argumenty, flagi, podkomendy, pomoc, formaty wyjścia, błędy, kody wyjścia, konfigurację i tryb dry-run.
  • 100cli-design
    Projektuje CLI dla ludzi i agentów LLM: kształt podkomend, strumienie wyjścia, kody wyjścia, tryby JSON, kolor zależny od TTY, ustrukturyzowane błędy i bezpieczeństwo modyfikacji.

Uwagi i zgłoszenia

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