go-cli
/go-cli
Buduje narzędzia wiersza poleceń w Go: flagi, podkomendy, stdin i stdout, kody wyjścia, obsługa sygnałów oraz ocena, kiedy Cobra i Viper są warte użycia wobec biblioteki standardowej.
- Autor
- eduardo-sl ↗
- Repozytorium
- go-agent-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 15.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 15.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Buduje narzędzia wiersza poleceń w Go: flagi, podkomendy, stdin i stdout, kody wyjścia, obsługa sygnałów oraz ocena, kiedy Cobra i Viper są warte użycia wobec biblioteki standardowej.
Wyzwalacze z opisu
Oryginalny opis (EN)
Build command-line tools in Go: flag handling, subcommands, stdin/stdout discipline, exit codes, signal handling, and when Cobra/Viper earn their weight over the standard library. Use when: "build a CLI", "add a subcommand", "parse flags", "exit codes", "handle Ctrl+C", "cobra command", "read from stdin", "CLI UX". Not for: HTTP APIs (go-api-design), scaffolding (go-project-layout), service configuration (go-architecture-review).
Jak działa
- 1. Structure: Testable main
- 2. stdout vs stderr
- 3. Exit Codes
- 4. Flags and Arguments
- 5. Subcommands
- 6. Output for Humans and Machines
- 7. Testing
- 8. Version Information
- 9. Shell Completions
- Verification Checklist
Podgląd SKILL.md
---
name: go-cli
description: >
Build command-line tools in Go: flag handling, subcommands, stdin/stdout
discipline, exit codes, signal handling, and when Cobra/Viper earn their
weight over the standard library. Use when: "build a CLI", "add a
subcommand", "parse flags", "exit codes", "handle Ctrl+C", "cobra
command", "read from stdin", "CLI UX".
Not for: HTTP APIs (go-api-design), scaffolding (go-project-layout),
service configuration (go-architecture-review).
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain.
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(gofmt:*)
metadata:
author: eduardo-sl
version: "1.2.0"
---
# Go CLI Design
A good CLI is a well-behaved Unix citizen: flags before magic, stdout
for data, stderr for diagnostics, exit codes that scripts can trust,
and Ctrl+C that actually stops it.
Detailed reference material, loaded on demand:
- `references/testing-and-versioning.md` — exit-code mapping in `main`,
golden-file and testscript tests, version from build info, completions.
Read a reference file only when the summary below is not enough.
## 1. Structure: Testable main
```go
func main() {
ctx, stop := signal.NotifyContext(context.Background(),
os.Interrupt, syscall.SIGTERM)
defer stop()
if err := run(ctx, os.Args[1:], os.Stdin, os.Stdout, os.Stderr); err != nil {
fmt.Fprintln(os.Stderr, "error:", err)
os.Exit(1)
}
}
func run(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer) error {
fs := flag.NewFlagSet("mytool", flag.ContinueOnError)
fs.SetOutput(stderr)
verbose := fs.Bool("v", false, "verbose output")
out := fs.String("o", "-", "output file (- for stdout)")
if err := fs.Parse(args); err != nil {
return err
}
// ...
_ = verbose
_ = out
return nil
}
```
- `signal.NotifyContext` makes Ctrl+C cancel the context — every
long operation takes `ctx` and stops cleanly. Call `stop()` once the
context is done so a second Ctrl+C kills a stuck program immediately.
- `run` receives args and streams — tests call it directly with
`strings.Reader`/`bytes.Buffer`, no subprocess needed.
- `os.Exit` only in `main` (it skips defers).
## 2. stdout vs stderr
- **stdout**: the program's output — data, results, the thing you pipe.
- **stderr**: logs, progress, warnings, usage errors.
- `--json` or detecting a pipe (`!term.IsTerminal(int(os.Stdout.Fd()))`)
should silence decorations, never change the data.
```go
// ✅ Good — result to stdout, progress to stderr
fmt.Fprintf(stderr, "processed %d files\n", n)
fmt.Fprintln(stdout, result)
// ❌ Bad — mixing both into stdout breaks every pipe
fmt.Printf("processing...\ndone: %s\n", result)
```
## 3. Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic runtime failure |
| 2 | Usage error (bad flags/arguments) — flag package's convention |
| >2 | Tool-specific, documented meanings (e.g. grep's 1 = no match) |
Map errors to codes in one place (`main`), not scattered `os.Exit`
calls. With `flag.ContinueOnError`, `-h` returns `flag.ErrHelp` — exit 0
for it, and wrap parse errors in a usage error type so `main` can exit 2.
Exit 130 after Ctrl+C. If scripts will branch on distinct failures, define
sentinel errors and translate: `errors.Is(err, ErrNoMatch) → 1`.
## 4. Flags and Arguments
- Flags for options, positional args for the primary operands:
`mytool -v convert input.yaml`, not `mytool --input=input.yaml`.
- Every flag has a usage string; `-h`/`-help` output is your primary UX.
- Accept `-` as "stdin/stdout" for file arguments.
- Defaults must be safe: destructive behavior behind explicit flags
(`--force`), never default-on.
- Read secrets from env or files, never from flags (`ps` leaks argv).
## 5. Subcommands
Standard library, fine up to a handful of commands:
```go
switch fs.Arg(0) {
case "serve":
return runServe(ctx, fs.Args()[1:], stdout, stderr)
case "migrate":
return runMigrate(ctx, fs.Args()[1:], stdout, stderr)
default:
fmt.Fprintln(stderr, usage)
return fmt.Errorf("unknown command %q", fs.Arg(0))
}
```
Adopt **Cobra** when you need nested commands, generated help/completions,
and many flags — the structure pays for the dependency:
```go
var rootCmd = &cobra.Command{Use: "mytool", SilenceUsage: true}
var serveCmd = &cobra.Command{
Use: "serve",
Short: "Start the server",
RunE: func(cmd *cobra.Command, args []string) error {
return serve(cmd.Context(), addr) // RunE returns errors; no os.Exit
},
}
func init() {
serveCmd.Flags().StringVar(&addr, "addr", ":8080", "listen address")
rootCmd.AddCommand(serveCmd)
}
```
Cobra rules: always `RunE` (never `Run` + `os.Exit`), set
`SilenceUsage: true` so runtime errors don't dump help, pass
`cmd.Context()` down. Add Viper only when layered config
(flags > env > file) is a real requirement — for most tools
`flag` + `os.Getenv` is enough.
## 6. Output for Humans and Machines
- `--json` flag for machine consumption; table/text default for humans.
- Never emit ANSI colors when stdout is not a terminal or `NO_COLOR`
is set.
- Progress bars/spinners go to stderr and only when it's a terminal.
## 7. Testing
Test `run` directly with buffers, comparing stdout against golden files
regenerated with `-update`. For end-to-end behavior — real binary, exit
codes, stdin — use `testscript` (`.txtar` scripts), the format the Go
command tests itself with.
## 8. Version Information
`mytool version` reads `debug.ReadBuildInfo()`: since Go 1.24 the main
module's version comes from the VCS tag, and `vcs.revision` from the
build settings. Fall back to `-ldflags "-X main.version=..."` only when
building without VCS metadata.
## 9. Shell Completions
Cobra generates `completion bash|zsh|fish|powershell`; add
`ValidArgsFunction` for dynamic values. Without Cobra, ship a static
completion script with the release.
Examples for sections 3 and 7-9: `references/testing-and-versioning.md`.
## Verification Checklist
1. `run(ctx, args, stdin, stdout, stderr)` pattern — logic testable without subprocess
2. `signal.NotifyContext` wired; long operations respect ctx cancellation
3. Data on stdout, diagnostics on stderr — verified by piping
4. Exit codes: 0 success, 2 usage, documented codes otherwise; `os.Exit` only in main
5. Every flag has usage text; `-h` output reviewed
6. `-` accepted for stdin/stdout where files are taken
7. Destructive actions require explicit flags
8. No secrets via argv
9. Cobra (if used): RunE everywhere, SilenceUsage, context propagated
10. Colors/spinners disabled for non-TTY and NO_COLOR
11. `-h` exits 0, usage errors exit 2, Ctrl+C exits 130
12. `version` output comes from build info; golden or testscript tests cover the CLI surface
Pliki w paczce (2)
- SKILL.md 7 KB
- references/testing-and-versioning.md 3 KB
Wersje
W bazie nie ma innych skilli o nazwie go-cli.
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki 75aff56ceece (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
- 100cobra
Buduje narzędzia wiersza poleceń w Go z Cobra, biblioteką używaną w kubectl, Hugo i GitHub CLI: podkomendy, flagi, walidacja argumentów, pomoc i uzupełnianie powłoki, z Viper. - 100golang-cli
Pomaga budować i przeglądać narzędzia CLI w Go: komendy, flagi, konfigurację, kody wyjścia, sygnały i testy jednostkowe. - 100golang-cli
Wspiera tworzenie aplikacji CLI w Go: struktura poleceń, flagi, warstwy konfiguracji, wersje, kody wyjścia, sygnały, uzupełnianie w powłoce i testy, w tym cobra, viper i urfave/cli. - 100cobra-viper
Prowadzi budowę aplikacji CLI w Go z Cobra i Viper według autora obu bibliotek: architektura zorientowana na komendy, rozdzielona logika biznesowa, konfiguracja, zmienne środowiskowe i testy CLI w pamięci. - 100build-cli-project
Implementuje narzędzia wiersza poleceń w Rust po wyborze kształtu projektu: parsowanie argumentów, dyspozytor poleceń, stdin, stdout i stderr, kody wyjścia, konfiguracja, komunikaty błędów, testy i walidacja Cargo. - 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.