[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ASR0WKZYM3RY05YAH7WVVT":3,"skill-same:01M7ASR0WKZYM3RY05YAH7WVVT":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7ASR0WKZYM3RY05YAH7WVVT","modern-cli-design",null,"Principles for building Unix-composable command-line tools in Go: stdout\u002Fstderr discipline, JSON and plain output modes, semantic exit codes, noun-verb commands, structured errors. Use when designing, building, or reviewing CLIs.","saski\u002Farnesto","saski","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F140356?v=4","01M7ASBDSNXTRYDYB4K1PEA1RV","01M7ASBDTAKBDAAV99S1GE7HK6",6,"Unlicense","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmodern-cli-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: modern-cli-design\ndescription: \"Principles for building Unix-composable command-line tools in Go: stdout\u002Fstderr discipline, JSON and plain output modes, semantic exit codes, noun-verb commands, structured errors. Use when designing, building, or reviewing CLIs.\"\n---\n\nSTARTER_CHARACTER = 🔧⚡\n\n# Modern CLI Design\n\nSpecialized concerns (long-running operations, credentials, testing) live in `references\u002F` — see the loading guidance at the end of this file.\n\n---\n\n## Core principle: stdout is for data, stderr is for everything else\n\nstdout carries the product the user asked for — results, JSON, records. stderr carries everything else — progress, spinners, warnings, errors, debug, prompts.\n\nA single spinner character on stdout breaks every downstream pipe. `mycli list | jq .` must never see a progress indicator on stdout.\n\nBuffering matters. stdout is line-buffered on a TTY and block-buffered when piped (~2x faster than stderr due to fewer write syscalls). stderr is unbuffered — every write is a syscall, but error messages appear immediately even on crash.\n\nCheck TTY on stdout and stderr independently. A user running `mycli run 2>\u002Fdev\u002Ftty | jq .` has stdout piped and stderr on a terminal — spinners on stderr are correct in that case.\n\nIn Go, write data with `os.Stdout.Write` \u002F `fmt.Fprintln(os.Stdout, ...)` and diagnostics with `fmt.Fprintln(os.Stderr, ...)`. Use `github.com\u002Fmattn\u002Fgo-isatty` to detect TTY per file descriptor.\n\n---\n\n## Format flag hierarchy\n\nFour output modes with different contracts:\n\n- **Default (human)**: colors, tables, formatted text, progress on stderr. Not a contract — may change between versions.\n- **`--plain`**: one record per line, no colors, flat rows with no borders. Stable across minor versions. Enables `mycli list --plain | grep error | wc -l`.\n- **`--json`**: structured JSON on stdout. stdout contains ONLY valid JSON — zero spinners, zero colors, zero progress. Schema is versioned. `--json` implies non-interactive regardless of TTY.\n- **`--format ndjson`**: newline-delimited JSON for streaming. Each line is one parseable object. Include a `type` field per record to multiplex events. Final line may be a summary record.\n\nJSON envelope is consistent across every command:\n\n```json\n{\"ok\": true, \"data\": {...}}\n{\"ok\": false, \"error\": {\"code\": \"...\", \"message\": \"...\", \"fix\": \"...\", \"transient\": false}}\n```\n\nThe `transient` flag tells retry logic whether the failure may resolve on its own.\n\n---\n\n## Exit codes\n\nMap to the most important failure modes for the tool. Document them in `--help`.\n\n- `0` success\n- `1` domain failure — expected failure mode (threshold not met, validation rejected, resource missing)\n- `2` invalid usage — bad flags, missing required args, type errors on input\n- `75` temporary failure — network timeout, 503, rate limit. Retry may help. Mirrors `transient: true` in JSON output.\n- `78` config error — invalid or missing config file\n- `130` SIGINT (128+2) — user pressed Ctrl-C\n- `141` SIGPIPE (128+13) — pipe consumer closed early. Exit silently.\n- `143` SIGTERM (128+15) — process was terminated\n\nNon-zero exit codes always accompanied by a stderr explanation. Never use codes above 125 for application errors — those are reserved for signals (128 + signal number).\n\nIn Go, prefer `os.Exit(code)` from `main` only. Handlers return errors; the CLI adapter translates to exit codes.\n\n---\n\n## TTY detection and color\n\nDecision priority (first match wins):\n\n1. `--format json` \u002F `--json` \u002F `--format ndjson` — non-interactive, no color\n2. `--no-color` flag — disable color\n3. `NO_COLOR` env var non-empty — disable color. This is a de facto standard across the ecosystem.\n4. `FORCE_COLOR` env var — enable color regardless of TTY\n5. `TERM=dumb` — disable color and animations\n6. `CI=true` — no interactive prompts\n7. stdout is not a TTY — plain output, no spinners on stdout\n8. Default — full interactive with colors\n\nSpinners on stderr remain valid when stdout is piped.\n\n---\n\n## Output stability — stdout is a public API\n\nChanges to the shape of machine-readable output (`--plain`, `--json`) are breaking changes to the CLI contract. Scripts and automation depend on them.\n\nAdditive is safe: new subcommands, new flags with preserving defaults, new optional JSON fields.\n\nBreaking: removing or renaming flags, removing or renaming JSON fields, changing exit codes, changing default behavior.\n\nHuman-readable default output is not a contract — it can change freely.\n\nWhen in doubt, add alongside — never modify. Deprecate with stderr warnings before removing.\n\n---\n\n## Noun-verb architecture\n\nStructure commands as `cli \u003Cresource> \u003Caction>`: `mycli config set`, `mycli issue create`, `mycli cluster delete`. Global flags apply across subcommands. Predictability lets users guess future commands from existing patterns.\n\nAnti-pattern: flag-heavy single commands like `tool --action=list --resource=plugins`. These fight the shell, prevent composition, and collapse as soon as two resources share a verb.\n\nIn Go, `github.com\u002Fspf13\u002Fcobra` implements this natively. Each command is a `*cobra.Command` with `Use`, `Short`, `Long`, `RunE`. Persistent flags on the root command apply everywhere.\n\nKeep handlers pure: the business logic returns data, it does not print. The CLI adapter (typically in `cmd\u002Fmycli\u002F`) parses args, calls the handler, picks the formatter, writes to the correct stream, sets the exit code. Handlers do not call `fmt.Println`, do not know about JSON vs text, do not call `os.Exit`.\n\nThis separation pays off concretely: handlers become testable without subprocess spawning, the same logic can back an HTTP server or MCP adapter, and format changes touch one file.\n\n---\n\n## Input design\n\nFlags over positional arguments. One positional arg is fine (the \"main thing\"). Two is suspicious — prefer `--from` and `--to` over ordered positionals. Three or more positionals is never right.\n\n`mycli copy myapp backup` is ambiguous. `mycli copy --from myapp --to backup` is self-documenting and order-independent.\n\nStandard flags, with long form always available:\n\n- `-h` \u002F `--help` — show help, and only show help\n- `--version` — print version to stdout\n- `-q` \u002F `--quiet` — suppress non-essential output\n- `-v` \u002F `--verbose` — more detail in human output\n- `-d` \u002F `--debug` — diagnostic output to stderr\n- `-f` \u002F `--force` — skip confirmation prompts\n- `-n` \u002F `--dry-run` — preview what would happen\n- `--json` \u002F `--plain` — machine-readable output modes\n- `--no-color` \u002F `--no-input` — disable color \u002F disable all prompts\n- `-o` \u002F `--output` — output file\n- `--fields` — select columns (critical for agent efficiency on large output)\n\nConventions:\n\n- Accept `--flag=value` and `--flag value` equivalently\n- `--` stops flag parsing: `mycli exec -- --flag-for-child`\n- `-` means stdin or stdout: `cat data | mycli process -`\n- If stdin is expected but connected to an interactive terminal, show help immediately — do not block waiting for input\n\nEvery prompt must be bypassable for scriptability:\n\n- Confirmation → `--yes` or `--force`\n- Selection → `--type=value`\n- Text input → `--name=value`\n- Passwords → `--password-file` or stdin\n\nSecrets never via flag values. Flag values leak to `ps` output and shell history. Accept secrets through env vars, files, or stdin only.\n\nGo: `github.com\u002Fspf13\u002Fpflag` (which Cobra uses) handles POSIX\u002FGNU flag conventions including `--` and `=` syntax.\n\n---\n\n## Error design\n\nEvery error carries: a machine-readable code, a human message, a fix suggestion, and a transient flag.\n\nIn Go:\n\n```go\ntype CLIError struct {\n    Code      string \u002F\u002F UPPER_SNAKE_CASE, e.g. \"CONFIG_MISSING\"\n    Message   string \u002F\u002F what went wrong, in human terms\n    Fix       string \u002F\u002F what the user should do\n    Transient bool   \u002F\u002F retrying might succeed\n}\n```\n\nHuman mode puts the most important information last — the eye lands at the end:\n\n```\nError: CONFIG_MISSING — No config file found at .\u002Fmycli.yaml\nFix: Run `mycli init` to create a default config\n```\n\nJSON mode formats errors with the same structure:\n\n```json\n{\"ok\": false, \"error\": {\"code\": \"CONFIG_MISSING\", \"message\": \"No config file found\", \"fix\": \"Run `mycli init`\", \"transient\": false}}\n```\n\nExit code 75 mirrors `transient: true` for non-JSON consumers that drive retries from exit codes.\n\nSuggest corrections for typos where the set is small: `Did you mean 'deploy'?`. Group similar errors under one header — repeating 50 near-identical lines buries the signal. Write debug logs to a file by default, not to the terminal.\n\nAnti-pattern: generic errors like `Operation failed` with no code, no reason, no action.\n\n---\n\n## Config precedence\n\nHighest priority wins:\n\n1. Flags — per-invocation override\n2. Environment variables — `MYCLI_*` prefix, per-session\n3. Project config — `.\u002Fmycli.yaml`, `.\u002F.myclirc`, or embedded in `package.json`-equivalent\n4. User config — `$XDG_CONFIG_HOME\u002Fmycli\u002F` (fallback to `~\u002F.config\u002Fmycli\u002F`)\n5. Built-in defaults\n\nFollow the XDG Base Directory Specification for user config location. Env var naming: tool prefix, uppercase, underscore-separated (`MYCLI_THRESHOLD`, `MYCLI_API_URL`).\n\nNever accept secrets via flags. Env vars, files, or stdin only.\n\nGo: `github.com\u002Fspf13\u002Fviper` combined with Cobra implements this precedence. `github.com\u002Fadrg\u002Fxdg` provides XDG path helpers.\n\nIf the tool modifies configuration that belongs to another program, ask consent first.\n\n---\n\n## Composability patterns\n\nDesign for real-world pipes. A well-behaved CLI chains cleanly:\n\n- Filter structured output: `mycli list --json | jq '.data[] | select(.status == \"failed\")'`\n- Stream large datasets: `mycli run --format ndjson | while read -r line; do echo \"$line\" | jq '.file'; done`\n- Feed stdin: `cat previous.json | mycli report -`\n- Chain identifiers: `mycli create --json | jq -r '.data.id' | xargs mycli deploy --id`\n- Parallel processing: `mycli list --json --fields id | jq -r '.data[].id' | xargs -P4 mycli process --id`\n- CI exit-code-only: `mycli check --quiet || echo \"Check failed\"`\n- Structured dry-run: `mycli apply --dry-run --json` outputs planned changes as data\n\nKey patterns:\n\n- `create` commands output the new identifier so the next command can consume it\n- `list` commands support `--fields` for column selection — reduces output size, critical when an agent reads the response\n- NDJSON avoids buffering the whole result in memory\n- `--dry-run` paired with `--json` makes planned changes inspectable\n\n---\n\n## Anti-patterns\n\n- Mixing data and diagnostics on stdout — breaks every pipe the user ever builds\n- ANSI escape codes in piped output — check `isatty(stdout)` and `NO_COLOR`\n- Interactive prompts with no flag bypass — agents and scripts cannot type 'y', and non-TTY without bypass hangs\n- Printing nothing on success — silence is ambiguous; show brief confirmation, offer `-q` for scripts\n- Designing for humans OR machines, not both — detect context, adapt automatically\n- Output that does not guide the next action — every output is a signpost: success points to the next command, failure points to the fix\n- Breaking existing CLI contracts — flag names, exit codes, JSON fields are promises\n- Handlers that write directly to stdout\u002Fstderr or call `os.Exit` — let the adapter decide\n- Non-zero exit without stderr explanation — scripts need both the code and the reason\n- Verbose default output — a single run can easily produce hundreds of KB; support `--fields`, `--quiet`, `--json`\n- Assuming required tools are installed — check and fail with a helpful message\n- Inconsistent terminology across commands — same flag name for the same concept everywhere\n\n---\n\n## Verification checklist\n\nAfter designing or reviewing a CLI:\n\n- stdout has ONLY data; stderr has everything else\n- Every command supports `--json` with the consistent envelope\n- Exit codes are semantic and documented in `--help`\n- Every prompt has a `--yes` \u002F `--force` \u002F flag bypass\n- Errors include code, message, fix suggestion, and transient flag\n- `--dry-run` available for mutating commands\n- Progress and spinners go to stderr, never stdout\n- `NO_COLOR`, `TERM=dumb`, and `--no-color` are all respected\n- Piped output contains zero ANSI escape codes\n- Success output includes next-action guidance\n- Existing flags, exit codes, JSON fields never removed or renamed — only added\n- JSON schema is versioned; additions safe, removals breaking\n- Config follows flags > env > project > user > defaults\n- Secrets accepted only via files \u002F stdin \u002F env, never flag values\n- Startup under 500ms; something printed within 100ms of invocation\n- Ctrl-C exits fast with bounded cleanup\n- `--help` includes 2-3 realistic examples\n- `--plain` output is grep-parseable (flat rows, no table borders)\n\n---\n\n## Load references on demand\n\nLoad the relevant file when the task matches.\n\n- `references\u002Flong-running-operations.md` — concurrency and chunking, parallel processing patterns, rsync-style resume with checkpointing, signal handling (SIGINT \u002F SIGTERM \u002F SIGPIPE), crash-only design with atomic writes and stale lock recovery, state management with embedded SQLite. Load when the CLI runs for minutes to hours, streams large datasets, processes many items in parallel, or manages persistent state across invocations.\n- `references\u002Fcredentials-and-security.md` — OS keychain integration, short-lived session token patterns, secret input through stdin \u002F files \u002F env, authentication command design. Load when the CLI handles API tokens, logs users in, or otherwise touches secrets.\n- `references\u002Ftesting-cli.md` — subprocess integration tests that capture stdout \u002F stderr \u002F exit code, handler isolation with in-memory fakes, JSON contract tests that guard the schema, help text snapshots. Load when writing or reviewing tests for a CLI.\n","STARTER_CHARACTER = 🔧⚡\n\n# Modern CLI Design\n\nSpecialized concerns (long-running operations, credentials, testing) live in `references\u002F` — see the loading guidance at the end of this file.\n\n---\n\n## Core principle: stdout is for data, stderr is for everything else\n\nstdout carries the product the user asked for — results, JSON, records. stderr carries everything else — progress, spinners, warnings, errors, debug, prompts.\n\nA single spinner character on stdout breaks every downstream pipe. `mycli list | jq .` must never see a progress indicator on stdout.\n\nBuffering matters. stdout is line-buffered on a TTY and block-buffered when piped (~2x faster than stderr due to fewer write syscalls). stderr is unbuffered — every write is a syscall, but error messages appear immediately even on crash.\n\nCheck TTY on stdout and stderr independently. A user running `mycli run 2>\u002Fdev\u002Ftty | jq .` has stdout piped and stderr on a terminal — spinners on stderr are correct in that case.\n\nIn Go, write data with `os.Stdout.Write` \u002F `fmt.Fprintln(os.Stdout, ...)` and diagnostics with `fmt.Fprintln(os.Stderr, ...)`. Use `github.com\u002Fmattn\u002Fgo-isatty` to detect TTY per file descriptor.\n\n---\n\n## Format flag hierarchy\n\nFour output modes with different contracts:\n\n- **Default (human)**: colors, tables, formatted text, progress on stderr. Not a contract — may change between versions.\n- **`--plain`**: one record per line, no colors, flat rows with no borders. Stable across minor versions. Enables `mycli list --plain | grep error | wc -l`.\n- **`--json`**: structured JSON on stdout. stdout contains ONLY valid JSON — zero spinners, zero colors, zero progress. Schema is versioned. `--json` implies non-interactive regardless of TTY.\n- **`--format ndjson`**: newline-delimited JSON for streaming. Each line is one parseable object. Include a `type` field per record to multiplex events. Final line may be a summary record.\n\nJSON envelope is consistent across every command:\n\n```json\n{\"ok\": true, \"data\": {...}}\n{\"ok\": false, \"error\": {\"code\": \"...\", \"message\": \"...\", \"fix\": \"...\", \"transient\": false}}\n```\n\nThe `transient` flag tells retry logic whether the failure may resolve on its own.\n\n---\n\n## Exit codes\n\nMap to the most important failure modes for the tool. Document them in `--help`.\n\n- `0` success\n- `1` domain failure — expected failure mode (threshold not met, validation rejected, resource missing)\n- `2` invalid usage — bad flags, missing required args, type errors on input\n- `75` temporary failure — network timeout, 503, rate limit. Retry may help. Mirrors `transient: true` in JSON output.\n- `78` config error — invalid or missing config file\n- `130` SIGINT (128+2) — user pressed Ctrl-C\n- `141` SIGPIPE (128+13) — pipe consumer closed early. Exit silently.\n- `143` SIGTERM (128+15) — process was terminated\n\nNon-zero exit codes always accompanied by a stderr explanation. Never use codes above 125 for application errors — those are reserved for signals (128 + signal number).\n\nIn Go, prefer `os.Exit(code)` from `main` only. Handlers return errors; the CLI adapter translates to exit codes.\n\n---\n\n## TTY detection and color\n\nDecision priority (first match wins):\n\n1. `--format json` \u002F `--json` \u002F `--format ndjson` — non-interactive, no color\n2. `--no-color` flag — disable color\n3. `NO_COLOR` env var non-empty — disable color. This is a de facto standard across the ecosystem.\n4. `FORCE_COLOR` env var — enable color regardless of TTY\n5. `TERM=dumb` — disable color and animations\n6. `CI=true` — no interactive prompts\n7. stdout is not a TTY — plain output, no spinners on stdout\n8. Default — full interactive with colors\n\nSpinners on stderr remain valid when stdout is piped.\n\n---\n\n## Output stability — stdout is a public API\n\nChanges to the shape of machine-readable output (`--plain`, `--json`) are breaking changes to the CLI contract. Scripts and automation depend on them.\n\nAdditive is safe: new subcommands, new flags with preserving defaults, new optional JSON fields.\n\nBreaking: removing or renaming flags, removing or renaming JSON fields, changing exit codes, changing default behavior.\n\nHuman-readable default output is not a contract — it can change freely.\n\nWhen in doubt, add alongside — never modify. Deprecate with stderr warnings before removing.\n\n---\n\n## Noun-verb architecture\n\nStructure commands as `cli \u003Cresource> \u003Caction>`: `mycli config set`, `mycli issue create`, `mycli cluster delete`. Global flags apply across subcommands. Predictability lets users guess future commands from existing patterns.\n\nAnti-pattern: flag-heavy single commands like `tool --action=list --resource=plugins`. These fight the shell, prevent composition, and collapse as soon as two resources share a verb.\n\nIn Go, `github.com\u002Fspf13\u002Fcobra` implements this natively. Each command is a `*cobra.Command` with `Use`, `Short`, `Long`, `RunE`. Persistent flags on the root command apply everywhere.\n\nKeep handlers pure: the business logic returns data, it does not print. The CLI adapter (typically in `cmd\u002Fmycli\u002F`) parses args, calls the handler, picks the formatter, writes to the correct stream, sets the exit code. Handlers do not call `fmt.Println`, do not know about JSON vs text, do not call `os.Exit`.\n\nThis separation pays off concretely: handlers become testable without subprocess spawning, the same logic can back an HTTP server or MCP adapter, and format changes touch one file.\n\n---\n\n## Input design\n\nFlags over positional arguments. One positional arg is fine (the \"main thing\"). Two is suspicious — prefer `--from` and `--to` over ordered positionals. Three or more positionals is never right.\n\n`mycli copy myapp backup` is ambiguous. `mycli copy --from myapp --to backup` is self-documenting and order-independent.\n\nStandard flags, with long form always available:\n\n- `-h` \u002F `--help` — show help, and only show help\n- `--version` — print version to stdout\n- `-q` \u002F `--quiet` — suppress non-essential output\n- `-v` \u002F `--verbose` — more detail in human output\n- `-d` \u002F `--debug` — diagnostic output to stderr\n- `-f` \u002F `--force` — skip confirmation prompts\n- `-n` \u002F `--dry-run` — preview what would happen\n- `--json` \u002F `--plain` — machine-readable output modes\n- `--no-color` \u002F `--no-input` — disable color \u002F disable all prompts\n- `-o` \u002F `--output` — output file\n- `--fields` — select columns (critical for agent efficiency on large output)\n\nConventions:\n\n- Accept `--flag=value` and `--flag value` equivalently\n- `--` stops flag parsing: `mycli exec -- --flag-for-child`\n- `-` means stdin or stdout: `cat data | mycli process -`\n- If stdin is expected but connected to an interactive terminal, show help immediately — do not block waiting for input\n\nEvery prompt must be bypassable for scriptability:\n\n- Confirmation → `--yes` or `--force`\n- Selection → `--type=value`\n- Text input → `--name=value`\n- Passwords → `--password-file` or stdin\n\nSecrets never via flag values. Flag values leak to `ps` output and shell history. Accept secrets through env vars, files, or stdin only.\n\nGo: `github.com\u002Fspf13\u002Fpflag` (which Cobra uses) handles POSIX\u002FGNU flag conventions including `--` and `=` syntax.\n\n---\n\n## Error design\n\nEvery error carries: a machine-readable code, a human message, a fix suggestion, and a transient flag.\n\nIn Go:\n\n```go\ntype CLIError struct {\n    Code      string \u002F\u002F UPPER_SNAKE_CASE, e.g. \"CONFIG_MISSING\"\n    Message   string \u002F\u002F what went wrong, in human terms\n    Fix       string \u002F\u002F what the user should do\n    Transient bool   \u002F\u002F retrying might succeed\n}\n```\n\nHuman mode puts the most important information last — the eye lands at the end:\n\n```\nError: CONFIG_MISSING — No config file found at .\u002Fmycli.yaml\nFix: Run `mycli init` to create a default config\n```\n\nJSON mode formats errors with the same structure:\n\n```json\n{\"ok\": false, \"error\": {\"code\": \"CONFIG_MISSING\", \"message\": \"No config file found\", \"fix\": \"Run `mycli init`\", \"transient\": false}}\n```\n\nExit code 75 mirrors `transient: true` for non-JSON consumers that drive retries from exit codes.\n\nSuggest corrections for typos where the set is small: `Did you mean 'deploy'?`. Group similar errors under one header — repeating 50 near-identical lines buries the signal. Write debug logs to a file by default, not to the terminal.\n\nAnti-pattern: generic errors like `Operation failed` with no code, no reason, no action.\n\n---\n\n## Config precedence\n\nHighest priority wins:\n\n1. Flags — per-invocation override\n2. Environment variables — `MYCLI_*` prefix, per-session\n3. Project config — `.\u002Fmycli.yaml`, `.\u002F.myclirc`, or embedded in `package.json`-equivalent\n4. User config — `$XDG_CONFIG_HOME\u002Fmycli\u002F` (fallback to `~\u002F.config\u002Fmycli\u002F`)\n5. Built-in defaults\n\nFollow the XDG Base Directory Specification for user config location. Env var naming: tool prefix, uppercase, underscore-separated (`MYCLI_THRESHOLD`, `MYCLI_API_URL`).\n\nNever accept secrets via flags. Env vars, files, or stdin only.\n\nGo: `github.com\u002Fspf13\u002Fviper` combined with Cobra implements this precedence. `github.com\u002Fadrg\u002Fxdg` provides XDG path helpers.\n\nIf the tool modifies configuration that belongs to another program, ask consent first.\n\n---\n\n## Composability patterns\n\nDesign for real-world pipes. A well-behaved CLI chains cleanly:\n\n- Filter structured output: `mycli list --json | jq '.data[] | select(.status == \"failed\")'`\n- Stream large datasets: `mycli run --format ndjson | while read -r line; do echo \"$line\" | jq '.file'; done`\n- Feed stdin: `cat previous.json | mycli report -`\n- Chain identifiers: `mycli create --json | jq -r '.data.id' | xargs mycli deploy --id`\n- Parallel processing: `mycli list --json --fields id | jq -r '.data[].id' | xargs -P4 mycli process --id`\n- CI exit-code-only: `mycli check --quiet || echo \"Check failed\"`\n- Structured dry-run: `mycli apply --dry-run --json` outputs planned changes as data\n\nKey patterns:\n\n- `create` commands output the new identifier so the next command can consume it\n- `list` commands support `--fields` for column selection — reduces output size, critical when an agent reads the response\n- NDJSON avoids buffering the whole result in memory\n- `--dry-run` paired with `--json` makes planned changes inspectable\n\n---\n\n## Anti-patterns\n\n- Mixing data and diagnostics on stdout — breaks every pipe the user ever builds\n- ANSI escape codes in piped output — check `isatty(stdout)` and `NO_COLOR`\n- Interactive prompts with no flag bypass — agents and scripts cannot type 'y', and non-TTY without bypass hangs\n- Printing nothing on success — silence is ambiguous; show brief confirmation, offer `-q` for scripts\n- Designing for humans OR machines, not both — detect context, adapt automatically\n- Output that does not guide the next action — every output is a signpost: success points to the next command, failure points to the fix\n- Breaking existing CLI contracts — flag names, exit codes, JSON fields are promises\n- Handlers that write directly to stdout\u002Fstderr or call `os.Exit` — let the adapter decide\n- Non-zero exit without stderr explanation — scripts need both the code and the reason\n- Verbose default output — a single run can easily produce hundreds of KB; support `--fields`, `--quiet`, `--json`\n- Assuming required tools are installed — check and fail with a helpful message\n- Inconsistent terminology across commands — same flag name for the same concept everywhere\n\n---\n\n## Verification checklist\n\nAfter designing or reviewing a CLI:\n\n- stdout has ONLY data; stderr has everything else\n- Every command supports `--json` with the consistent envelope\n- Exit codes are semantic and documented in `--help`\n- Every prompt has a `--yes` \u002F `--force` \u002F flag bypass\n- Errors include code, message, fix suggestion, and transient flag\n- `--dry-run` available for mutating commands\n- Progress and spinners go to stderr, never stdout\n- `NO_COLOR`, `TERM=dumb`, and `--no-color` are all respected\n- Piped output contains zero ANSI escape codes\n- Success output includes next-action guidance\n- Existing flags, exit codes, JSON fields never removed or renamed — only added\n- JSON schema is versioned; additions safe, removals breaking\n- Config follows flags > env > project > user > defaults\n- Secrets accepted only via files \u002F stdin \u002F env, never flag values\n- Startup under 500ms; something printed within 100ms of invocation\n- Ctrl-C exits fast with bounded cleanup\n- `--help` includes 2-3 realistic examples\n- `--plain` output is grep-parseable (flat rows, no table borders)\n\n---\n\n## Load references on demand\n\nLoad the relevant file when the task matches.\n\n- `references\u002Flong-running-operations.md` — concurrency and chunking, parallel processing patterns, rsync-style resume with checkpointing, signal handling (SIGINT \u002F SIGTERM \u002F SIGPIPE), crash-only design with atomic writes and stale lock recovery, state management with embedded SQLite. Load when the CLI runs for minutes to hours, streams large datasets, processes many items in parallel, or manages persistent state across invocations.\n- `references\u002Fcredentials-and-security.md` — OS keychain integration, short-lived session token patterns, secret input through stdin \u002F files \u002F env, authentication command design. Load when the CLI handles API tokens, logs users in, or otherwise touches secrets.\n- `references\u002Ftesting-cli.md` — subprocess integration tests that capture stdout \u002F stderr \u002F exit code, handler isolation with in-memory fakes, JSON contract tests that guard the schema, help text snapshots. Load when writing or reviewing tests for a CLI.\n",{"name":5,"description":7},"main","3c24fc2c035029b08c7326774bee3fef8fb95566",".agents\u002Fskills\u002Fmodern-cli-design",0,"https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto","https:\u002F\u002Fgithub.com\u002Fsaski","http:\u002F\u002Fsaski.com","2026-11-12 20:09:16",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add saski\u002Farnesto --skill modern-cli-design",{"tool":37,"command":38},"bunx","bunx skills add saski\u002Farnesto --skill modern-cli-design",{"tool":40,"command":41},"pnpm","pnpm dlx skills add saski\u002Farnesto --skill modern-cli-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmodern-cli-design\u002FSKILL.md",true,[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fcredentials-and-security.md","REFERENCE","参考文档",7791,"https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmodern-cli-design\u002Freferences\u002Fcredentials-and-security.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Flong-running-operations.md",12423,"https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmodern-cli-design\u002Freferences\u002Flong-running-operations.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Ftesting-cli.md",15116,"https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmodern-cli-design\u002Freferences\u002Ftesting-cli.md",[60,67,74,81,88,95],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M7AT7F5FSHNAMFMF01N0QA1X","visualize","Use \u002Fvisualize for creating compact charts, diagrams, or other visuals inline as part of the conversation itself. It chooses among Markdown tables, Mermaid, inline HTML, and other supported in-transcript forms. Use Canvas for durable artifacts outside the transcript that users may revisit, refine, or share.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fvisualize\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M7AT79MHSAR3JDDMP7DGERM9","update-cursor-settings","Modify Cursor\u002FVSCode user settings in settings.json. Use when you want to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fupdate-cursor-settings\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":18},"01M7AT73WF3Y22E0FKYAMCCJES","update-cli-config","View and modify Cursor CLI configuration settings in ~\u002F.cursor\u002Fcli-config.json. Use when the user wants to change CLI settings, configure permissions, switch approval mode, enable vim mode, toggle display options, configure sandbox, or manage any CLI preferences.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fupdate-cli-config\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M7AT6F3FBP85AJJ5BJNR8B5W","statusline","Configure a custom status line in the CLI. Use when the user mentions status line, statusline, statusLine, CLI status bar, prompt footer customization, or wants to add session context above the prompt.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fstatusline\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":18},"01M7AT6D24QFS5XRAFN8S5XJ7W","split-to-prs","Split current work into small reviewable PRs. Use when the user asks to split a chat, set of changes, branch, or PR.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fsplit-to-prs\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":18},"01M7AT69FYFN84XZKW452JV5DF","shell","Runs the rest of a \u002Fshell request as a literal shell command. Use only when the user explicitly invokes \u002Fshell and wants the following text executed directly in the terminal.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fshell\u002FSKILL.md",[],[]]