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

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.

Licencja
MIT
Ostatnia zmiana repozytorium
15.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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 15.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

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

build a CLIadd a subcommandparse flagsexit codeshandle Ctrl+Ccobra commandread from stdinCLI UX
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. 1. Structure: Testable main
  2. 2. stdout vs stderr
  3. 3. Exit Codes
  4. 4. Flags and Arguments
  5. 5. Subcommands
  6. 6. Output for Humans and Machines
  7. 7. Testing
  8. 8. Version Information
  9. 9. Shell Completions
  10. Verification Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 177 linii, 875 słów
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.

Uwagi i zgłoszenia

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