CLI 명령어와 Yargs 구조 완벽 가이드

Node.js에서 전문적인 CLI 도구를 만들기 위한 Yargs 라이브러리의 핵심 개념과 실무 패턴을 다룹니다. 엔트리포인트 구성부터 커스텀 명령어 추가까지 단계별로 학습합니다.

---

목차

1. index.ts 엔트리포인트 분석
2. Yargs를 이용한 CLI 구조화
3. 주요 명령어: run, auth, agent, mcp 등
4. 미들웨어와 로깅 시스템
5. 에러 처리 패턴
6. 커스텀 명령어 추가하기

---

1. index.ts 엔트리포인트 분석

신입 개발자 김개발 씨가 처음으로 CLI 도구 개발 프로젝트에 투입되었습니다. 선배가 건네준 코드를 열어보니 index.ts 파일이 눈에 들어왔습니다.

"이게 대체 어떻게 돌아가는 거지?" 김개발 씨는 고개를 갸웃거렸습니다.

엔트리포인트는 CLI 애플리케이션의 시작점입니다. 마치 책의 목차처럼 모든 명령어와 설정이 어디로 연결되는지 정의하는 곳입니다.

이 파일을 제대로 이해하면 전체 CLI 구조를 파악할 수 있습니다.

다음 코드를 살펴봅시다.

#!/usr/bin/env node
// CLI 엔트리포인트 - 모든 명령어의 시작점
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import { runCommand } from './commands/run';
import { authCommand } from './commands/auth';

// yargs 인스턴스 생성 및 기본 설정
const cli = yargs(hideBin(process.argv))
  .scriptName('mycli')
  .usage('$0 <command> [options]')
  .command(runCommand)
  .command(authCommand)
  .demandCommand(1, '명령어를 입력해주세요')
  .strict()
  .help();

// CLI 실행
cli.parse();

김개발 씨는 입사 첫 주에 사내 CLI 도구 개선 업무를 맡게 되었습니다. 기존 코드를 열어보니 index.ts 파일 상단에 이상한 주석이 눈에 띄었습니다.

"#!/usr/bin/env node가 뭐지?" 김개발 씨가 중얼거렸습니다. 옆자리 박시니어 씨가 웃으며 대답했습니다.

"그건 셔뱅이라고 해요. 터미널에서 이 파일을 직접 실행할 때 Node.js로 실행하라고 알려주는 거예요." 셔뱅은 마치 편지 봉투에 적힌 주소와 같습니다.

우체부가 편지를 어디로 배달해야 하는지 알려주듯이, 셔뱅은 운영체제에게 이 스크립트를 어떤 프로그램으로 실행해야 하는지 알려줍니다. 그 다음 줄의 hideBin 함수도 중요합니다.

process.argv에는 Node.js 실행 경로와 스크립트 경로가 포함되어 있는데, 우리가 실제로 필요한 건 사용자가 입력한 명령어와 옵션뿐입니다. hideBin은 이 불필요한 앞부분을 잘라내는 역할을 합니다.

마치 택배 상자에서 완충재를 걷어내고 실제 물건만 꺼내는 것과 같습니다. scriptName은 도움말에 표시될 CLI 이름을 지정합니다.

usage는 사용법 안내 메시지를 설정합니다. 이 두 설정 덕분에 사용자가 --help를 입력하면 깔끔한 도움말이 표시됩니다.

command 메서드로 각 명령어를 등록합니다. runCommand, authCommand처럼 별도 파일로 분리된 명령어 객체를 불러와 연결합니다.

이렇게 분리하면 코드 관리가 훨씬 수월해집니다. demandCommand는 최소 명령어 개수를 지정합니다.

아무 명령어도 입력하지 않으면 친절한 안내 메시지가 표시됩니다. strict 옵션을 켜면 등록되지 않은 옵션이나 명령어를 사용했을 때 에러를 발생시킵니다.

오타로 인한 실수를 방지하는 안전장치입니다. 마지막으로 parse를 호출하면 실제 명령어 파싱과 실행이 시작됩니다.

이 한 줄이 모든 것을 동작하게 만드는 시동 키입니다. 김개발 씨는 고개를 끄덕였습니다.

"생각보다 체계적이네요. 각 부분이 명확한 역할을 가지고 있군요."

실전 팁

💡 - 셔뱅 라인은 반드시 파일 첫 줄에 위치해야 합니다

• package.json의 bin 필드에 엔트리포인트를 등록하면 전역 설치 시 CLI 명령어로 사용 가능합니다

---

2. Yargs를 이용한 CLI 구조화

김개발 씨가 직접 CLI 도구를 만들어보기로 했습니다. 처음에는 process.argv를 직접 파싱하려 했지만, 옵션이 늘어날수록 코드가 스파게티처럼 얽혀갔습니다.

"이걸 어떻게 정리하지?" 고민하던 그때, 박시니어 씨가 Yargs를 소개해주었습니다.

Yargs는 Node.js CLI 도구 개발을 위한 강력한 라이브러리입니다. 마치 레고 블록처럼 명령어, 옵션, 인자를 조립하여 복잡한 CLI를 체계적으로 구성할 수 있습니다.

타입 안전성과 자동 도움말 생성까지 지원합니다.

다음 코드를 살펴봅시다.

// Yargs를 활용한 명령어 정의
import type { CommandModule } from 'yargs';

interface RunOptions {
  config: string;
  verbose: boolean;
  port: number;
}

export const runCommand: CommandModule<{}, RunOptions> = {
  command: 'run [script]',
  describe: '스크립트를 실행합니다',
  builder: (yargs) => yargs
    .positional('script', { type: 'string', default: 'main' })
    .option('config', { alias: 'c', type: 'string', default: './config.json' })
    .option('verbose', { alias: 'v', type: 'boolean', default: false })
    .option('port', { alias: 'p', type: 'number', default: 3000 }),
  handler: async (argv) => {
    console.log(`실행: ${argv.script}, 포트: ${argv.port}`);
  }
};

김개발 씨가 처음 CLI를 만들 때는 이런 식으로 코드를 작성했습니다. "if문이 열 개가 넘어가니까 눈이 돌아갈 것 같아요." 김개발 씨가 한숨을 쉬었습니다.

박시니어 씨가 Yargs를 보여주었습니다. "이 라이브러리를 쓰면 명령어를 객체 형태로 깔끔하게 정의할 수 있어요." Yargs의 CommandModule은 하나의 명령어를 표현하는 타입입니다.

마치 이력서 양식처럼 명령어가 갖춰야 할 항목들이 정해져 있습니다. command 필드는 명령어의 이름과 형태를 정의합니다.

대괄호는 선택적 인자, 꺾쇠괄호는 필수 인자를 의미합니다. 'run [script]'는 run 명령어 뒤에 script라는 선택적 인자가 온다는 뜻입니다.

describe는 도움말에 표시될 명령어 설명입니다. 사용자가 이해하기 쉽게 간결하게 작성하는 것이 좋습니다.

builder는 공장과 같습니다. 이 함수 안에서 옵션들을 조립합니다.

positional은 위치 기반 인자를, option은 플래그 형태의 옵션을 정의합니다. 각 옵션에는 alias로 단축키를 지정할 수 있습니다.

-c는 --config의 축약형이 됩니다. 타이핑을 줄여주는 배려입니다.

type을 지정하면 자동으로 타입 변환이 이루어집니다. 문자열로 들어온 숫자가 실제 number 타입으로 변환됩니다.

타입스크립트와 결합하면 더욱 강력해집니다. handler는 실제 명령어가 실행될 때 호출되는 함수입니다.

파싱된 인자들이 argv 객체로 전달됩니다. 비동기 함수로 작성하면 async/await 패턴을 사용할 수 있습니다.

제네릭 타입 CommandModule<{}, RunOptions>에서 첫 번째 타입은 상위 명령어에서 상속받는 옵션, 두 번째 타입은 현재 명령어의 옵션을 의미합니다. 김개발 씨의 눈이 반짝였습니다.

"타입 안전성까지 보장되니까 오타 걱정도 없겠네요!" 이런 구조화된 접근 방식 덕분에 명령어가 수십 개로 늘어나도 코드베이스를 깔끔하게 유지할 수 있습니다.

실전 팁

💡 - 명령어 파일은 commands 폴더에 분리하여 관리하면 확장성이 좋아집니다

• builder에서 체이닝으로 옵션을 연결하면 가독성이 향상됩니다

---

3. 주요 명령어: run, auth, agent, mcp 등

CLI 도구의 뼈대를 이해한 김개발 씨는 이제 실제 명령어들을 살펴보기 시작했습니다. run, auth, agent, mcp 등 다양한 명령어가 있었습니다.

"각 명령어마다 역할이 다르네요. 어떻게 설계해야 할까요?"

CLI 도구는 여러 명령어의 집합입니다. 마치 스위스 군용 칼처럼 각 도구가 특정 목적을 수행합니다.

run은 실행, auth는 인증, agent는 에이전트 관리, mcp는 프로토콜 통신을 담당합니다. 각 명령어는 독립적이면서도 일관된 인터페이스를 제공해야 합니다.

다음 코드를 살펴봅시다.

// 다양한 명령어 구조 예시
// auth 명령어 - 서브커맨드 패턴
export const authCommand: CommandModule = {
  command: 'auth <action>',
  describe: '인증 관련 명령어',
  builder: (yargs) => yargs
    .command('login', '로그인', {}, handleLogin)
    .command('logout', '로그아웃', {}, handleLogout)
    .command('status', '인증 상태 확인', {}, handleStatus),
  handler: () => {}
};

// agent 명령어 - 복잡한 옵션 패턴
export const agentCommand: CommandModule = {
  command: 'agent',
  describe: 'AI 에이전트 실행',
  builder: (yargs) => yargs
    .option('model', { choices: ['gpt-4', 'claude'] as const })
    .option('temperature', { type: 'number', default: 0.7 })
    .option('max-tokens', { type: 'number', default: 4096 }),
  handler: async (argv) => { /* 에이전트 로직 */ }
};

박시니어 씨가 화이트보드에 그림을 그리기 시작했습니다. "CLI 명령어는 크게 두 가지 패턴으로 나눌 수 있어요." 첫 번째는 서브커맨드 패턴입니다.

auth 명령어처럼 하위에 login, logout, status 같은 세부 명령어를 두는 방식입니다. git commit, git push처럼 익숙한 구조입니다.

마치 회사 조직도와 같습니다. 인사팀 아래에 채용, 교육, 평가 담당이 있듯이, auth 명령어 아래에 관련 기능들이 모여 있습니다.

두 번째는 옵션 기반 패턴입니다. agent 명령어처럼 다양한 옵션으로 동작을 제어하는 방식입니다.

하나의 명령어가 옵션에 따라 다르게 동작합니다. choices 옵션을 사용하면 허용된 값만 입력받을 수 있습니다.

사용자가 잘못된 값을 입력하면 자동으로 에러 메시지와 함께 가능한 선택지를 보여줍니다. run 명령어는 보통 CLI의 핵심 기능을 담당합니다.

스크립트 실행, 서버 시작, 빌드 수행 등 주된 동작이 여기에 해당합니다. auth 명령어는 인증과 권한을 관리합니다.

토큰 저장, 세션 관리, 사용자 정보 조회 같은 기능을 묶어둡니다. agent 명령어는 AI 에이전트나 백그라운드 프로세스를 제어합니다.

모델 선택, 파라미터 조정 같은 세밀한 설정이 필요합니다. mcp 명령어는 Model Context Protocol 같은 특수 프로토콜 통신을 담당합니다.

서버 연결, 메시지 전송, 상태 조회 등의 기능을 포함합니다. 김개발 씨가 질문했습니다.

"명령어가 많아지면 어떻게 관리하나요?" "명령어별로 파일을 분리하고, index.ts에서 한꺼번에 등록하는 게 일반적이에요." 박시니어 씨가 답했습니다. 명령어 설계의 핵심은 일관성입니다.

모든 명령어가 비슷한 형태의 도움말, 비슷한 에러 메시지, 비슷한 출력 형식을 갖추면 사용자가 빠르게 적응할 수 있습니다.

실전 팁

💡 - 관련 기능은 서브커맨드로 묶어 계층 구조를 만드세요

• choices 옵션으로 입력값을 제한하면 실수를 방지할 수 있습니다

---

4. 미들웨어와 로깅 시스템

김개발 씨가 만든 CLI가 점점 복잡해지기 시작했습니다. 모든 명령어에서 인증을 확인하고, 실행 시간을 측정하고, 로그를 남겨야 했습니다.

"똑같은 코드를 계속 복사해야 하나요?" 김개발 씨의 질문에 박시니어 씨가 미들웨어 패턴을 알려주었습니다.

미들웨어는 명령어 실행 전후에 공통 로직을 수행하는 함수입니다. 마치 공항 보안 검색대처럼 모든 승객이 통과해야 하는 관문 역할을 합니다.

인증 확인, 로깅, 에러 추적 등 횡단 관심사를 깔끔하게 처리할 수 있습니다.

다음 코드를 살펴봅시다.

// 미들웨어 패턴 구현
import yargs from 'yargs';

// 인증 미들웨어
const authMiddleware = async (argv: any) => {
  const token = process.env.CLI_TOKEN;
  if (!token) throw new Error('인증이 필요합니다. cli auth login을 실행하세요.');
  argv.token = token;
};

// 로깅 미들웨어
const loggingMiddleware = (argv: any) => {
  const start = Date.now();
  argv._startTime = start;
  console.log(`[${new Date().toISOString()}] 명령어 시작: ${argv._[0]}`);
};

// 미들웨어 적용
yargs(process.argv.slice(2))
  .middleware([loggingMiddleware, authMiddleware])
  .command('deploy', '배포 실행', {}, async (argv) => {
    // 배포 로직
    console.log(`소요 시간: ${Date.now() - argv._startTime}ms`);
  })
  .parse();

김개발 씨가 코드를 살펴보다가 한숨을 쉬었습니다. "인증 체크 코드가 열 군데나 중복되어 있어요." 이런 상황은 흔합니다.

모든 명령어에서 인증을 확인해야 하고, 로그를 남겨야 하고, 설정 파일을 읽어야 합니다. 이런 공통 로직을 매번 복사하면 유지보수가 악몽이 됩니다.

미들웨어 패턴이 이 문제를 해결합니다. 미들웨어는 마치 호텔 로비의 안내 데스크와 같습니다.

어떤 객실로 가든 먼저 로비를 거쳐야 하고, 그곳에서 체크인이나 키 수령 같은 공통 절차를 밟습니다. Yargs의 middleware 메서드는 함수 배열을 받습니다.

배열 순서대로 미들웨어가 실행됩니다. 위 코드에서는 먼저 로깅 미들웨어가 실행되고, 그 다음 인증 미들웨어가 실행됩니다.

미들웨어 함수는 argv 객체를 받아서 수정할 수 있습니다. 인증 미들웨어가 토큰을 검증한 후 argv.token에 저장하면, 이후 명령어 핸들러에서 바로 사용할 수 있습니다.

로깅 시스템도 미들웨어로 구현하기 좋은 기능입니다. 시작 시간을 기록해두면 명령어 실행 후 소요 시간을 계산할 수 있습니다.

실무에서는 더 정교한 로깅이 필요합니다. winston이나 pino 같은 로깅 라이브러리를 연동하여 파일에 저장하거나, 로그 레벨을 조절하거나, JSON 형식으로 출력할 수 있습니다.

미들웨어에서 에러를 던지면 명령어 실행이 중단됩니다. 인증 미들웨어가 토큰 없음을 감지하면 친절한 에러 메시지와 함께 실행을 멈춥니다.

비동기 미들웨어도 지원됩니다. async 함수로 작성하면 파일 읽기나 API 호출 같은 비동기 작업을 수행할 수 있습니다.

김개발 씨가 감탄했습니다. "이제 공통 로직을 한 곳에서 관리할 수 있겠네요!" 미들웨어 패턴은 CLI뿐 아니라 Express 같은 웹 프레임워크에서도 널리 사용됩니다.

한번 익혀두면 여러 곳에서 활용할 수 있는 범용적인 설계 패턴입니다.

실전 팁

💡 - 미들웨어 순서가 중요합니다. 로깅은 앞에, 인증은 그 다음에 배치하세요

• 조건부 미들웨어가 필요하면 함수 내부에서 명령어를 확인하세요

---

5. 에러 처리 패턴

김개발 씨가 만든 CLI를 동료가 사용하다가 에러가 발생했습니다. 화면에는 길고 복잡한 스택 트레이스가 출력되었습니다.

"이게 무슨 말인지 모르겠어요." 동료의 말에 김개발 씨는 에러 처리의 중요성을 깨달았습니다.

CLI의 에러 처리는 사용자 경험을 좌우합니다. 마치 좋은 의사가 환자에게 병명을 쉽게 설명하듯이, CLI도 무엇이 잘못되었고 어떻게 해결할 수 있는지 명확하게 알려야 합니다.

적절한 에러 처리는 디버깅 시간을 크게 줄여줍니다.

다음 코드를 살펴봅시다.

// 에러 처리 패턴 구현
class CLIError extends Error {
  constructor(message: string, public code: string, public suggestion?: string) {
    super(message);
    this.name = 'CLIError';
  }
}

// 전역 에러 핸들러
const handleError = (error: unknown) => {
  if (error instanceof CLIError) {
    console.error(`오류 [${error.code}]: ${error.message}`);
    if (error.suggestion) console.error(`해결 방법: ${error.suggestion}`);
    process.exit(1);
  }
  // 예상치 못한 에러
  console.error('예기치 않은 오류가 발생했습니다.');
  console.error(error instanceof Error ? error.message : String(error));
  process.exit(1);
};

// 사용 예시
const validateConfig = (path: string) => {
  if (!fs.existsSync(path)) {
    throw new CLIError(
      `설정 파일을 찾을 수 없습니다: ${path}`,
      'CONFIG_NOT_FOUND',
      'config.json 파일을 생성하거나 --config 옵션으로 경로를 지정하세요'
    );
  }
};

박시니어 씨가 화면을 가리키며 말했습니다. "에러 메시지는 세 가지를 담아야 해요.

무엇이 잘못됐는지, 왜 잘못됐는지, 어떻게 고칠 수 있는지." 좋은 에러 메시지는 마치 친절한 안내원과 같습니다. "이 길은 막혔습니다"가 아니라 "공사 중이라 막혔습니다.

저쪽 골목으로 돌아가세요"라고 말해주는 것입니다. 커스텀 에러 클래스를 만들면 에러를 체계적으로 관리할 수 있습니다.

CLIError 클래스는 기본 Error를 확장하여 에러 코드와 해결 제안을 추가로 담습니다. 에러 코드는 문제를 빠르게 식별하는 데 도움됩니다.

CONFIG_NOT_FOUND, AUTH_REQUIRED, NETWORK_ERROR 같은 코드로 에러 유형을 분류하면 문서화나 검색이 쉬워집니다. suggestion 필드가 핵심입니다.

사용자에게 다음 행동을 안내합니다. "설정 파일이 없습니다"로 끝나면 사용자는 막막합니다.

"config init 명령어로 생성하세요"라고 알려주면 바로 해결할 수 있습니다. 전역 에러 핸들러는 모든 에러를 한 곳에서 처리합니다.

예상된 에러(CLIError)와 예상치 못한 에러를 구분하여 다르게 처리합니다. 예상된 에러는 친절한 메시지를 보여주고, 예상치 못한 에러는 간략한 안내와 함께 디버깅 정보를 출력합니다.

**process.exit(1)**로 에러 종료 코드를 반환하는 것도 중요합니다. 스크립트나 CI/CD에서 CLI를 호출할 때 성공 여부를 판단하는 기준이 됩니다.

비동기 에러도 잡아야 합니다. unhandledRejection 이벤트 핸들러를 등록하면 await 없이 호출된 Promise 에러도 처리할 수 있습니다.

김개발 씨가 코드를 수정한 후, 동료가 다시 테스트했습니다. "오, 이제 뭘 해야 하는지 바로 알겠어요!" 잘 설계된 에러 처리는 개발자의 시간을 아껴줍니다.

문제를 파악하는 데 30분 쓰던 것이 30초로 줄어들 수 있습니다.

실전 팁

💡 - 에러 코드는 대문자와 언더스코어로 작성하여 일관성을 유지하세요

• 개발 모드에서는 스택 트레이스를 표시하고, 프로덕션에서는 숨기는 것이 좋습니다

---

6. 커스텀 명령어 추가하기

CLI 도구가 완성되어 팀에서 사용하기 시작했습니다. 얼마 후 기획자가 요청했습니다.

"새로운 기능을 추가해주세요." 김개발 씨는 이제 자신 있게 대답했습니다. "네, 금방 추가하겠습니다!"

커스텀 명령어를 추가하는 것은 CLI 확장의 핵심입니다. 마치 레고 블록을 추가하듯이 기존 구조를 건드리지 않고 새 기능을 붙일 수 있어야 합니다.

잘 설계된 CLI는 새 명령어 추가가 간단하고 예측 가능합니다.

다음 코드를 살펴봅시다.

// 새로운 커스텀 명령어 추가하기
// commands/analyze.ts
import type { CommandModule } from 'yargs';

interface AnalyzeOptions {
  path: string;
  format: 'json' | 'table' | 'text';
  verbose: boolean;
}

export const analyzeCommand: CommandModule<{}, AnalyzeOptions> = {
  command: 'analyze <path>',
  describe: '프로젝트를 분석합니다',
  builder: (yargs) => yargs
    .positional('path', { type: 'string', demandOption: true })
    .option('format', {
      alias: 'f', type: 'string', choices: ['json', 'table', 'text'], default: 'table'
    })
    .option('verbose', { alias: 'v', type: 'boolean', default: false })
    .example('$0 analyze ./src', 'src 폴더 분석')
    .example('$0 analyze ./src -f json', 'JSON 형식으로 출력'),
  handler: async (argv) => {
    console.log(`분석 시작: ${argv.path}`);
    // 분석 로직 구현
  }
};

// index.ts에 등록
// .command(analyzeCommand)

김개발 씨는 이제 CLI 구조를 완전히 이해했습니다. 새 명령어를 추가하는 것은 정해진 패턴을 따르기만 하면 됩니다.

먼저 commands 폴더에 새 파일을 생성합니다. 명령어 이름과 같은 파일명을 사용하면 찾기 쉽습니다.

analyze.ts, deploy.ts, sync.ts처럼요. CommandModule 타입을 임포트하고, 제네릭으로 옵션 인터페이스를 지정합니다.

타입스크립트의 자동 완성 기능이 개발 속도를 높여줍니다. command 필드에서 꺾쇠괄호는 필수 인자를 의미합니다.

'analyze <path>'에서 path는 반드시 입력해야 합니다. 대괄호는 선택적 인자입니다.

demandOption: true를 설정하면 해당 인자가 없을 때 명확한 에러 메시지가 표시됩니다. 사용자가 실수로 인자를 빼먹어도 바로 알 수 있습니다.

example 메서드는 도움말에 사용 예시를 추가합니다. 이 작은 배려가 사용자 경험을 크게 향상시킵니다.

"이 명령어를 어떻게 쓰지?" 고민하는 시간을 줄여줍니다. 새 명령어를 만들었다면 index.ts에 등록해야 합니다.

import 문을 추가하고 .command() 체인에 연결합니다. 이 두 줄이면 충분합니다.

명령어가 많아지면 카테고리별로 그룹화할 수도 있습니다. 관리 명령어, 분석 명령어, 배포 명령어 등으로 나누어 별도 모듈로 관리합니다.

테스트도 중요합니다. 명령어별로 단위 테스트를 작성하면 리팩토링 시 안전망이 됩니다.

옵션 파싱, 유효성 검사, 핸들러 로직을 각각 테스트합니다. 박시니어 씨가 마지막으로 조언했습니다.

"명령어 추가는 쉬워졌지만, 일관성을 유지하는 게 더 중요해요. 모든 명령어가 같은 규칙을 따라야 사용자가 헷갈리지 않아요." 김개발 씨는 고개를 끄덕였습니다.

이제 어떤 기능 요청이 와도 자신 있게 CLI를 확장할 수 있게 되었습니다.

실전 팁

💡 - 명령어 파일은 한 가지 기능만 담당하도록 분리하세요

• example을 최소 2개 이상 추가하면 사용자에게 큰 도움이 됩니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!