Node.js로 CLI 도구 만들기: commander와 yargs 비교

개요

Node.js로 커맨드라인 도구(CLI)를 만들 때 선택지는 다양하다. 그중 commander와 yargs는 가장 널리 쓰이는 라이브러리다. 이 글은 두 라이브러리의 사용법을 예제 중심으로 비교하고, npm에 배포해 전역 실행 가능한 CLI로 등록하는 방법까지 다룬다.

사전 준비

프로젝트 템플릿을 만든다. Node.js와 npm이 설치되어 있어야 한다. 프로젝트 초기화는 다음과 같이 진행한다.

mkdir my-cli
cd my-cli
npm init -y

commander 사용 예제

설치와 기본 구조

commander는 선언형으로 옵션과 서브커맨드를 정의하기에 적합하다. 설치는 아래와 같다.

npm install commander

간단한 예제 파일은 다음과 같다.

// bin/cli-commander.js
#!/usr/bin/env node
const { program } = require('commander');

program
  .name('my-cli')
  .description('간단한 예제 CLI')
  .version('0.1.0');

program
  .option('-n, --name <name>', '사용자 이름')
  .option('-v, --verbose', '상세 모드');

program.parse(process.argv);

const options = program.opts();
if (options.verbose) console.log('Verbose 모드 활성화');
console.log(`안녕하세요, ${options.name || '익명'}님`);

특징

• 선언적으로 명령과 옵션을 정의
• 서브커맨드 구성 지원
• 문서화용 자동 도움말 생성

yargs 사용 예제

설치와 기본 구조

yargs는 풍부한 유효성 검사와 명령 정의 기능이 강점이다. 설치 후 다음과 같이 작성한다.

npm install yargs

간단한 yargs 예제는 아래와 같다.

// bin/cli-yargs.js
#!/usr/bin/env node
const yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers');

const argv = yargs(hideBin(process.argv))
  .scriptName('my-cli')
  .usage('$0 --name [str]')
  .option('name', {
    alias: 'n',
    describe: '사용자 이름',
    type: 'string'
  })
  .option('verbose', {
    alias: 'v',
    type: 'boolean',
    describe: '상세 모드'
  })
  .help()
  .argv;

if (argv.verbose) console.log('Verbose 모드 활성화');
console.log(`안녕하세요, ${argv.name || '익명'}님`);

특징

• 복잡한 옵션 타입과 유효성 검사에 강함
• 커맨드 체인과 서브커맨드 정의가 직관적
• 로컬화와 도움말 커스터마이징 가능

commander와 yargs 비교

두 라이브러리는 겹치는 기능이 많다. 선택은 프로젝트 성격에 따라 달라진다.

• 간결하고 선언적인 정의가 필요하면 commander가 유리
• 옵션 검증과 복잡한 커맨드 트리가 필요하면 yargs가 적합
• 학습 곡선은 비슷하지만 사용 패턴에 차이가 있다

패키지 설정과 npm bin 등록

로컬에서 전역처럼 실행하려면 package.json에 bin 필드를 추가한다. 예를 들어 commander 예제를 배포 전 테스트하려면 다음과 같이 설정한다.

{
  "name": "my-cli",
  "version": "0.1.0",
  "bin": {
    "my-cli-commander": "./bin/cli-commander.js",
    "my-cli-yargs": "./bin/cli-yargs.js"
  },
  "dependencies": {
    "commander": "^9.0.0",
    "yargs": "^17.0.0"
  }
}

설정 후 로컬에서 링크해 테스트한다.

npm link
# 이제 터미널에서 my-cli-commander 또는 my-cli-yargs로 실행 가능

배포와 주의사항

npm에 배포하려면 다음을 확인한다.

• package.json의 bin 필드가 올바른 상대경로를 가리키는지 확인
• 실행 파일에 실행 권한(Unix 계열) 부여
• 불필요한 의존성은 devDependencies로 분리
• 버전과 README로 사용법을 명확히 표기

마무리

commander와 yargs는 각각 장단점이 있다. 간단한 스크립트나 빠른 프로토타입은 commander가 편하고, 복잡한 옵션 처리와 검증이 필요하면 yargs가 더 적합하다. npm의 bin 설정으로 전역 실행 가능한 CLI로 배포하면 개발 생산성이 좋아진다. 예제를 직접 실행해 보면서 필요에 맞는 라이브러리를 선택하기를 권장한다.