🐍

Go CLI 프레임워크 cobra 기본기

최민석·2026-04-22

Go CLI 프레임워크 cobra 기본기

Go에서 CLI 도구를 만들 때 os.Args를 직접 파싱해본 뒤, 서브커맨드 분기나 플래그 처리가 반복되는 순간 무언가 잘못됐다는 생각이 듭니다. kubectl, gh, docker, hugo 같은 도구들이 사용하는 cobra는 이런 반복을 걷어내 주는 Go의 표준적인 CLI 프레임워크입니다. 이번 글에서는 cobra의 핵심 개념과 실전에서 자주 쓰는 기능들을 정리합니다.


왜 cobra인가

os.Args로 직접 파싱한 CLI와 비교하면 차이가 명확합니다.

os.Args cobra
서브커맨드 switch로 직접 분기 트리 구조로 자동 분기
플래그 파싱 (--name=foo) 직접 구현 자동
help 메시지 직접 작성 자동 생성
입력 검증 직접 선언적
자동완성 없음 bash/zsh/fish 지원

특히 커맨드가 늘어날수록 직접 구현한 CLI는 유지보수가 어려워집니다. cobra는 커맨드를 트리 구조로 관리하여 kubectl get pods 같은 깊은 커맨드도 자연스럽게 표현할 수 있습니다.


설치

go get github.com/spf13/cobra

cobra-cli라는 코드 생성기도 있지만, 학습 목적으로는 직접 구조를 익히는 편이 낫습니다.


가장 작은 cobra 프로그램

package main

import (
    "fmt"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "cli",
    Short: "간단 CLI 도구",
}

var helloCmd = &cobra.Command{
    Use:   "hello",
    Short: "Hello 출력",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Hello!")
    },
}

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

func main() {
    rootCmd.Execute()
}

실행 결과:

$ go run . hello
Hello!

$ go run . --help
간단 CLI 도구

Usage:
  cli [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  hello       Hello 출력
  help        Help about any command

Flags:
  -h, --help   help for cli

커맨드를 등록했을 뿐인데 help가 자동으로 생성되고, completion 서브커맨드도 기본 제공됩니다.


Command 구조체의 주요 필드

var cmd = &cobra.Command{
    Use:     "greet [name]",        // 커맨드 이름과 인자 힌트
    Short:   "이름으로 인사",         // 짧은 설명 (help 목록용)
    Long:    "주어진 이름으로 인사말을 출력합니다.",  // 긴 설명 (상세 help용)
    Example: "  cli greet 철수",     // 사용 예시
    Aliases: []string{"hi", "hey"},  // 별칭
    Run:     func(cmd *cobra.Command, args []string) { ... },
}
  • Use: 도움말에 표시되는 사용법. 실제 바이너리 이름과 무관합니다. 관례상 바이너리 이름과 맞춥니다.
  • Short: 부모 커맨드의 help 목록에 표시됩니다.
  • Long: cli greet --help로 상세 help를 볼 때 표시됩니다.
  • Example: help 하단에 사용 예시로 표시됩니다.
  • Aliases: 같은 커맨드를 다른 이름으로도 호출 가능하게 합니다.

플래그

로컬 플래그

해당 커맨드에만 적용되는 플래그입니다.

var name string

func init() {
    greetCmd.Flags().StringVarP(&name, "name", "n", "world", "인사할 대상")
}

StringVarP의 인자:

  1. 바인딩할 변수 주소
  2. 긴 이름 (--name)
  3. 짧은 이름 (-n)
  4. 기본값
  5. 설명

타입별 메서드:

메서드 타입
StringVarP string
IntVarP int
BoolVarP bool
StringSliceVarP []string (쉼표 구분)
DurationVarP time.Duration

짧은 이름이 필요 없으면 P를 뺀 StringVar를 씁니다.

전역 플래그 (PersistentFlags)

루트에 선언하면 모든 하위 커맨드에서 사용 가능합니다.

var verbose bool

func init() {
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "상세 로그")
}

이제 cli hello --verbose, cli greet --verbose 모두 동작합니다. 로그 레벨이나 설정 파일 경로처럼 전역적으로 적용되는 옵션에 적합합니다.

필수 플래그

cmd.MarkFlagRequired("name")

플래그를 빠뜨리면 에러 메시지와 함께 실행이 중단됩니다.


인자 검증

플래그가 아닌 위치 인자(positional arguments)의 개수와 형식을 선언적으로 검증할 수 있습니다.

var cmd = &cobra.Command{
    Use:  "add [a] [b]",
    Args: cobra.ExactArgs(2),      // 정확히 2개
    Run: func(cmd *cobra.Command, args []string) {
        // args[0], args[1]
    },
}

자주 쓰는 Args 검증자:

검증자 의미
cobra.NoArgs 인자 없음
cobra.ExactArgs(n) 정확히 n개
cobra.MinimumNArgs(n) 최소 n개
cobra.MaximumNArgs(n) 최대 n개
cobra.RangeArgs(min, max) min~max개
cobra.OnlyValidArgs ValidArgs에 정의된 값만 허용

ValidArgs와 조합하면 자동완성까지 제공됩니다:

var cmd = &cobra.Command{
    Use:       "status [state]",
    ValidArgs: []string{"open", "closed", "all"},
    Args:      cobra.OnlyValidArgs,
    Run:       func(cmd *cobra.Command, args []string) { ... },
}

에러를 반환하는 RunE

Run은 error를 반환하지 않아 에러 처리가 번거롭습니다. 에러를 cobra에 위임하려면 RunE 를 사용합니다.

var cmd = &cobra.Command{
    Use: "parse",
    RunE: func(cmd *cobra.Command, args []string) error {
        if err := doSomething(); err != nil {
            return fmt.Errorf("처리 실패: %w", err)
        }
        return nil
    },
}

RunE가 에러를 반환하면:

  • cobra가 표준 에러 출력으로 에러 메시지를 출력
  • 종료 코드 1로 프로그램 종료
  • 자동으로 사용법(Usage)을 함께 표시 (설정으로 끌 수 있음)

실무에서는 Run보다 RunE를 쓰는 편이 안전합니다.


실행 훅 — PreRun / PostRun

커맨드 실행 전후에 공통 로직을 넣고 싶을 때 사용합니다.

var cmd = &cobra.Command{
    Use: "deploy",
    PreRunE: func(cmd *cobra.Command, args []string) error {
        // 인증 체크, 설정 로드 등
        return checkAuth()
    },
    RunE: func(cmd *cobra.Command, args []string) error {
        return deploy()
    },
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("완료")
    },
}

훅의 종류:

훅 실행 시점
PersistentPreRun(E) 루트부터 순차적으로, 자식의 Run 이전
PreRun(E) 해당 커맨드의 Run 직전
Run(E) 메인 로직
PostRun(E) 해당 커맨드의 Run 직후
PersistentPostRun(E) 자식의 Run 이후, 루트까지 순차적

공통 로직(DB 커넥션, 로거 초기화 등)을 PersistentPreRun에 두면 모든 서브커맨드에서 자동으로 실행됩니다.


자동완성

cobra는 bash/zsh/fish/powershell 자동완성 스크립트를 자동 생성합니다.

# zsh에서
$ source <(./mytool completion zsh)
$ ./mytool gr<TAB>
greet    # 자동완성됨

설정은 completion 서브커맨드의 help에 안내됩니다.


파일 구조 분리

커맨드가 늘어나면 하나의 파일로는 관리가 어렵습니다. cobra 프로젝트에서 일반적인 구조:

mytool/
├── main.go           # main 함수만
└── cmd/
    ├── root.go       # rootCmd + Execute()
    ├── hello.go      # helloCmd + init()
    ├── greet.go      # greetCmd + init()
    └── ...

각 커맨드 파일은 자신의 init()에서 루트에 등록합니다:

// cmd/hello.go
package cmd

import "github.com/spf13/cobra"

var helloCmd = &cobra.Command{...}

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

Go의 init() 함수는 파일별로 자동 호출되므로, 파일을 추가하는 것만으로 커맨드가 등록됩니다. 커맨드 간 의존성이 없다면 이 구조가 가장 깔끔합니다.


viper와의 조합

환경 변수, 설정 파일, 플래그를 통합 관리하려면 같은 저자(spf13)의 viper와 조합합니다.

import "github.com/spf13/viper"

func init() {
    viper.SetConfigName("config")
    viper.AddConfigPath(".")
    viper.AutomaticEnv()

    // 플래그를 viper에 바인딩
    viper.BindPFlag("name", greetCmd.Flags().Lookup("name"))
}

// 런타임에
name := viper.GetString("name")
// 우선순위: 플래그 > 환경변수 > 설정파일 > 기본값

실무에서 흔한 패턴입니다. 학습 단계에서는 cobra만으로도 충분합니다.


정리

cobra의 핵심은 커맨드 트리 + 선언적 플래그/검증 + 자동화된 help입니다.

  • 단순한 Run 대신 RunE로 에러 처리를 일관되게
  • 공통 로직은 PersistentPreRun과 PersistentFlags에
  • 위치 인자는 Args 검증자로 선언적으로
  • 커맨드가 늘어나면 cmd/ 디렉토리로 파일 분리

os.Args로 직접 파싱하던 CLI를 cobra로 옮기면, 비즈니스 로직에만 집중할 수 있습니다. Go로 실용적인 CLI 도구를 만들 때의 표준적인 선택지로 자리잡은 이유가 여기에 있습니다.