Go에서 CLI 도구를 만들 때
os.Args를 직접 파싱해본 뒤, 서브커맨드 분기나 플래그 처리가 반복되는 순간 무언가 잘못됐다는 생각이 듭니다.kubectl,gh,docker,hugo같은 도구들이 사용하는 cobra는 이런 반복을 걷어내 주는 Go의 표준적인 CLI 프레임워크입니다. 이번 글에서는 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라는 코드 생성기도 있지만, 학습 목적으로는 직접 구조를 익히는 편이 낫습니다.
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 서브커맨드도 기본 제공됩니다.
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의 인자:
--name)-n)타입별 메서드:
| 메서드 | 타입 |
|---|---|
StringVarP |
string |
IntVarP |
int |
BoolVarP |
bool |
StringSliceVarP |
[]string (쉼표 구분) |
DurationVarP |
time.Duration |
짧은 이름이 필요 없으면 P를 뺀 StringVar를 씁니다.
루트에 선언하면 모든 하위 커맨드에서 사용 가능합니다.
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) { ... },
}
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가 에러를 반환하면:
실무에서는 Run보다 RunE를 쓰는 편이 안전합니다.
커맨드 실행 전후에 공통 로직을 넣고 싶을 때 사용합니다.
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() 함수는 파일별로 자동 호출되므로, 파일을 추가하는 것만으로 커맨드가 등록됩니다. 커맨드 간 의존성이 없다면 이 구조가 가장 깔끔합니다.
환경 변수, 설정 파일, 플래그를 통합 관리하려면 같은 저자(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 도구를 만들 때의 표준적인 선택지로 자리잡은 이유가 여기에 있습니다.