1. Cobra

Go에서 CLI 애플리케이션을 만들기 위한 라이브러리. Kubernetes, Hugo, GitHub CLI 등이 Cobra로 만들어져 있다.

Cobra는 Commands, Args, Flags 세 가지 개념으로 구성된다.

APPNAME COMMAND ARG --FLAG
# 예시
git clone URL --bare

설치

go get -u github.com/spf13/cobra@latest

2. Command 구조

cobra.Command 구조체로 각 명령을 정의한다.

package cmd

import (
	"fmt"

	"github.com/spf13/cobra"
)

// Run 사용 — 에러를 직접 처리
var rootCmd = &cobra.Command{
	Use:   "myapp",
	Short: "A brief description of the app",
	Long:  "A longer description that spans multiple lines.",
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("Hello from myapp")
	},
}

// RunE 사용 — 에러를 반환하면 Cobra가 메시지 + usage 출력
// Run과 RunE는 XOR. 둘 다 설정하면 RunE가 우선.
var rootCmd = &cobra.Command{
	Use:   "myapp",
	Short: "A brief description of the app",
	RunE: func(cmd *cobra.Command, args []string) error {
		if len(args) == 0 {
			return fmt.Errorf("at least one argument is required")
		}
		fmt.Println("Hello from myapp")
		return nil
	},
}

func Execute() {
	cobra.CheckErr(rootCmd.Execute())
}

주요 필드:

Use — 명령어 이름과 사용법 (예: "serve", "get [resource]")
Short — 간단한 설명 (help 목록에 표시)
Long — 상세 설명 (help 상세에 표시)
Run — 실행될 함수
RunE — error를 반환하는 실행 함수

3. Sub-Command

AddCommand로 하위 명령어를 추가한다.

var serveCmd = &cobra.Command{
	Use:   "serve",
	Short: "Start the server",
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("Server started")
	},
}

func init() {
	rootCmd.AddCommand(serveCmd)
}

myapp serve
# Server started

서브 커맨드는 계속 중첩할 수 있다.

// myapp serve grpc
serveCmd.AddCommand(grpcCmd)

4. Flags

Flag는 두 가지 종류가 있다.

Persistent Flags

해당 커맨드와 모든 하위 커맨드에서 사용 가능.

rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")

Local Flags

해당 커맨드에서만 사용 가능.

serveCmd.Flags().IntVarP(&port, "port", "p", 8080, "port to listen on")

Required Flags

필수 플래그로 지정하면 값을 넣지 않았을 때 에러를 반환한다.

serveCmd.Flags().StringVarP(&configFile, "config", "c", "", "config file path")
cobra.CheckErr(serveCmd.MarkFlagRequired("config"))

Flag 바인딩 함수

타입별로 바인딩 함수가 존재한다. VarP 접미사의 P는 short flag를 지원한다는 뜻.

// --name, -n
cmd.Flags().StringVarP(&name, "name", "n", "default", "usage")

// --name only (short flag 없음)
cmd.Flags().StringVar(&name, "name", "default", "usage")

// 다른 타입들
cmd.Flags().IntVar(&count, "count", 0, "usage")
cmd.Flags().BoolVar(&debug, "debug", false, "usage")
cmd.Flags().StringSliceVar(&tags, "tag", []string{}, "usage")
cmd.Flags().DurationVar(&timeout, "timeout", 30*time.Second, "usage")

5. Args Validation

Cobra는 위치 인자(positional arguments)에 대한 빌트인 검증을 제공한다.

var printCmd = &cobra.Command{
	Use:   "print [message]",
	Args:  cobra.ExactArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println(args[0])
	},
}

빌트인 검증 함수:

cobra.NoArgs — 인자가 없어야 함
cobra.ExactArgs(n) — 정확히 n개
cobra.MinimumNArgs(n) — 최소 n개
cobra.MaximumNArgs(n) — 최대 n개
cobra.RangeArgs(min, max) — min~max개
cobra.ArbitraryArgs — 제한 없음 (기본값)

6. 일반적인 프로젝트 구조

Cobra 프로젝트의 관례적 디렉토리 구조:

myapp/
├── cmd/
│   ├── root.go      // rootCmd 정의, Execute()
│   ├── serve.go     // serve 서브커맨드
│   └── version.go   // version 서브커맨드
├── main.go          // cmd.Execute() 호출
├── go.mod
└── go.sum

// main.go
package main

import "myapp/cmd"

func main() {
	cmd.Execute()
}

각 서브커맨드 파일에서 init()으로 rootCmd에 등록하는 패턴을 사용한다.

7. Hooks (PreRun / PostRun)

커맨드 실행 전후에 hook을 걸 수 있다. 실행 순서는 아래와 같다.

PersistentPreRun
PreRun
Run
PostRun
PersistentPostRun

var serveCmd = &cobra.Command{
	Use: "serve",
	PreRunE: func(cmd *cobra.Command, args []string) error {
		if port < 1 || port > 65535 {
			return fmt.Errorf("invalid port: %d", port)
		}
		return nil
	},
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Printf("Listening on :%d\n", port)
	},
}

Persistent 접두사가 붙은 hook은 하위 커맨드에도 상속된다.

8. Cobra와 Viper 연동

Viper는 설정 관리 라이브러리로, Cobra의 flag와 바인딩하여 환경변수/설정파일/flag를 통합 관리할 수 있다.

func init() {
	serveCmd.Flags().IntVarP(&port, "port", "p", 8080, "port")
	viper.BindPFlag("port", serveCmd.Flags().Lookup("port"))

	// 환경변수 AAP_PORT 도 매핑
	viper.SetEnvPrefix("AAP")
	viper.AutomaticEnv()
}

우선순위: flag > 환경변수 > 설정파일 > 기본값