LunariaJS CLI 명령어 상세 설명: init, build, preview 완벽 마스터

지난 두 편의 글에서는 LunariaJS의 핵심 개념과 설정 방법을 소개했습니다. 오늘은 LunariaJS의 명령줄 도구(CLI)를 깊이 있게 살펴보고, 각 명령어의 사용법과 모범 사례를 마스터해 보겠습니다.

💡 공식 문서: LunariaJS 한국어 문서 - CLI

CLI 개요

LunariaJS는 강력한 명령줄 도구를 제공하여 다음 작업을 수행할 수 있습니다:

프로젝트 초기화: 설정 파일을 빠르게 생성
대시보드 빌드: 현지화 상태 시각화 페이지 생성
대시보드 미리보기: 로컬에서 서버를 시작해 결과 확인

실행 방식

LunariaJS CLI를 실행하는 세 가지 방식이 있습니다:

# 방식 1: npx 사용 (추천, 설치 불필요)
npx lunaria [command]

# 방식 2: npm scripts 사용 (추천)
npm run lunaria:[command]

# 방식 3: 직접 실행 (전역 또는 프로젝트 설치 필요)
lunaria [command]

글로벌 옵션

모든 명령어는 다음 글로벌 옵션을 지원합니다:

옵션	단축	설명
`--help`	`-h`	도움말 표시
`--version`	`-v`	버전 번호 표시
`--config <path>`	`-c`	설정 파일 경로 지정

도움말 보기

# 메인 명령어 도움말 보기
npx lunaria --help

# 하위 명령어 도움말 보기
npx lunaria init --help
npx lunaria build --help
npx lunaria preview --help

lunaria init - 프로젝트 초기화

lunaria init 명령어는 LunariaJS 설정 파일을 빠르게 생성합니다.

기본 사용법

npx lunaria init

실행하면 CLI가 대화식으로 설정 정보를 요청합니다:

? What is the source language of your project? (en)
? What languages do you want to support? (comma-separated, e.g., zh-cn, ja, ko)
? Where are your source files located? (e.g., docs/{slug}.md)
? Where should localized files be stored? (e.g., i18n/{lang}/{slug}.md)
? Where should the dashboard be generated? (lunaria-dashboard)

명령어 매개변수

매개변수	설명	기본값
`--config <path>`	출력 설정 파일 경로 지정	`lunaria.config.json`
`--typescript`	TypeScript 설정 파일 생성	`false`
`--yes` / `-y`	대화형 건너뛰기, 기본값 사용	`false`
`--force` / `-f`	기존 설정 파일 강제 덮어쓰기	`false`

대화형 초기화 흐름

전체 대화형 초기화 예시를 살펴보겠습니다:

$ npx lunaria init

🌙 LunariaJS - Localization Dashboard Generator

? What is the source language of your project? en
? What languages do you want to support? zh-cn, ja, ko
? Where are your source content files? src/content/docs/{slug}.md
? Where are your localized content files? src/i18n/{lang}/docs/{slug}.md
? Where should the dashboard be output? public/lunaria
? Dashboard title My Docs Localization Status

✨ Created lunaria.config.json

Next steps:
1. Review and adjust lunaria.config.json
2. Run `npx lunaria build` to generate your dashboard
3. Run `npx lunaria preview` to preview locally

TypeScript 설정 생성

TypeScript 설정 파일을 선호한다면:

npx lunaria init --typescript

이렇게 하면 lunaria.config.ts가 생성됩니다:

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

export default defineConfig({
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'src/i18n/{lang}/docs/{slug}.md',
    },
  ],
  dashboard: {
    outputDir: 'public/lunaria',
    title: 'My Docs Localization Status',
  },
});

빠른 초기화 (대화형 건너뛰기)

--yes 옵션을 사용해 기본값으로 빠르게 설정 파일을 생성합니다:

npx lunaria init --yes

이렇게 하면 모든 기본값으로 설정 파일을 생성합니다:

{
  "sourceLanguage": "en",
  "languages": ["en"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard"
  }
}

설정 파일 경로 지정

npx lunaria init --config ./config/lunaria.json

모범 사례

처음 사용 시 대화형 추천: CLI가 설정을 안내하도록 함
이후 TypeScript 사용: 더 나은 타입 지원과 IDE 힌트
버전 관리: 설정 파일을 Git 저장소에 커밋

lunaria build - 대시보드 빌드

lunaria build 명령어는 LunariaJS의 핵심 명령어로, 현지화 대시보드를 생성합니다.

기본 사용법

npx lunaria build

명령어 매개변수

매개변수	설명	기본값
`--config <path>`	설정 파일 경로 지정	`lunaria.config.json`
`--output <dir>`	출력 디렉토리 지정 (설정 덮어쓰기)	설정의 `dashboard.outputDir`
`--silent`	무음 모드, 로그 출력 없음	`false`
`--verbose`	상세 출력 모드	`false`

빌드 과정 상세 설명

lunaria build를 실행하면 LunariaJS는 다음 단계를 수행합니다:

1. 설정 파일 로드

📄 Loading configuration from lunaria.config.json...

2. 원본 파일 스캔

🔍 Scanning source files in src/content/docs/...
   Found 42 source files

3. 번역 상태 분석

📊 Analyzing translation status...
   - en (source): 42 files
   - zh-cn: 38 done, 3 outdated, 1 missing
   - ja: 30 done, 8 outdated, 4 missing
   - ko: 25 done, 10 outdated, 7 missing

4. 대시보드 생성

🎨 Generating dashboard...
   - Creating HTML pages
   - Generating CSS styles
   - Building JavaScript bundle

5. 결과 출력

✅ Dashboard generated successfully!
   Output: public/lunaria/
   Files: 15 files, 128KB total

상세 출력 모드

--verbose를 사용해 더 많은 빌드 세부 정보를 확인합니다:

npx lunaria build --verbose

출력 예시:

📄 Loading configuration from lunaria.config.json

🔍 Scanning files...
   Pattern: src/content/docs/{slug}.md
   Files found:
   - src/content/docs/index.md
   - src/content/docs/getting-started.md
   - src/content/docs/configuration.md
   ...

📊 Analyzing translation status...

   File: index.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-27)
   - ja: outdated (modified: 2026-02-20, source newer)
   - ko: missing

   File: getting-started.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-28)
   - ja: done (modified: 2026-02-25)
   - ko: outdated (modified: 2026-02-15, source newer)
   ...

🎨 Generating dashboard...
   - Writing index.html
   - Writing styles.css
   - Writing script.js
   - Writing data/status.json

✅ Build completed in 1.2s
   Output: public/lunaria/

무음 모드

CI/CD 환경에서는 무음 모드를 사용할 수 있습니다:

npx lunaria build --silent

출력 디렉토리 사용자 정의

설정의 출력 디렉토리를 일시적으로 덮어씁니다:

npx lunaria build --output ./dist/i18n-dashboard

package.json과 통합

// package.json
{
  "scripts": {
    "build": "astro build && lunaria build",
    "lunaria:build": "lunaria build",
    "lunaria:build:verbose": "lunaria build --verbose"
  }
}

빌드 산출물

lunaria build는 출력 디렉토리에 다음 파일을 생성합니다:

lunaria-dashboard/
├── index.html          # 메인 페이지
├── assets/
│   ├── index.css       # 스타일 파일
│   └── index.js        # JavaScript 로직
├── data/
│   └── status.json     # 번역 상태 데이터
└── favicon.ico         # 사이트 아이콘

일반적인 빌드 오류

오류 1: 설정 파일을 찾을 수 없음

Error: Configuration file not found at lunaria.config.json

해결 방법:

# 먼저 init을 실행해 설정 생성
npx lunaria init
# 또는 설정 파일 경로 지정
npx lunaria build --config ./config/lunaria.json

오류 2: 원본 파일 디렉토리가 존재하지 않음

Error: Source directory "docs" does not exist

해결 방법: files.sourcePath 설정이 올바른지 확인합니다.

lunaria preview - 대시보드 미리보기

lunaria preview 명령어는 로컬 서버를 시작해 생성된 대시보드를 미리 봅니다.

기본 사용법

npx lunaria preview

명령어 매개변수

매개변수	설명	기본값
`--config <path>`	설정 파일 경로 지정	`lunaria.config.json`
`--port <number>`	서버 포트 지정	`3000`
`--open`	브라우저 자동 열기	`false`
`--host`	모든 네트워크 인터페이스 수신	`false`

미리보기 서버 시작

$ npx lunaria preview

🌙 LunariaJS Preview Server

Local:   http://localhost:3000
Network: http://192.168.1.100:3000

Press Ctrl+C to stop

포트 지정

npx lunaria preview --port 8080

브라우저 자동 열기

npx lunaria preview --open

외부 접근 허용

팀 환경에서 동료가 로컬 네트워크를 통해 접근할 수 있습니다:

npx lunaria preview --host

미리보기 주의 사항

먼저 빌드 필요: preview 명령어는 자동으로 빌드를 실행하지 않으므로 먼저 lunaria build를 실행했는지 확인
핫 리로드: 현재 핫 리로드를 지원하지 않으므로 설정 변경 후 다시 빌드 필요
포트 충돌: 기본 포트가 사용 중이면 --port로 다른 포트 지정

명령어 조합 사용 시나리오

개발 환경 워크플로우

# 1. 설정 초기화 (처음)
npx lunaria init

# 2. 대시보드 빌드
npx lunaria build

# 3. 결과 미리보기
npx lunaria preview --open

Astro Starlight와 통합

// package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build && lunaria build",
    "preview": "astro preview",
    "lunaria:preview": "lunaria preview --port 3001"
  }
}

CI/CD 파이프라인

# .github/workflows/i18n-check.yml
name: i18n Status Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Build Lunaria Dashboard
        run: npm run lunaria:build -- --silent

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: lunaria-dashboard
          path: lunaria-dashboard/

로컬 디버깅 시나리오

# 상세 출력 모드로 디버깅 지원
npx lunaria build --verbose

# 빌드에 문제가 있으면 설정 확인
npx lunaria init --force  # 설정 재생성

# 다시 빌드
npx lunaria build --verbose

CLI 고급 팁

1. 환경 변수 사용

# Node.js 환경 변수 설정
NODE_ENV=production npx lunaria build

# 사용자 정의 환경 변수
LUNARIA_OUTPUT=./dist/dashboard npx lunaria build

설정 파일에서 사용:

// lunaria.config.ts
export default defineConfig({
  dashboard: {
    outputDir: process.env.LUNARIA_OUTPUT || 'lunaria-dashboard',
  },
});

2. 여러 명령어 조합

# 한 번에 초기화와 빌드 완료
npx lunaria init --yes && npx lunaria build

# 또는 npm scripts 사용
npm run lunaria:init && npm run lunaria:build

3. 설정 문제 디버깅

# 설정 파일이 유효한지 확인
npx lunaria build --verbose 2>&1 | head -20

4. 버전 확인

# 현재 버전 확인
npx lunaria --version

# 새 버전이 있는지 확인
npm outdated @lunariajs/core

CLI 일반적인 문제 해결

Q1: 명령어를 찾을 수 없음

문제: lunaria: command not found

해결 방법:

# npx 사용
npx lunaria [command]

# 또는 전역 설치
npm install -g @lunariajs/core

Q2: 권한 거부

문제: EACCES: permission denied

해결 방법:

# 디렉토리 권한 확인
ls -la .

# 또는 sudo 사용 (비추천)
sudo npx lunaria build

Q3: 메모리 부족

문제: JavaScript heap out of memory

해결 방법:

# Node.js 메모리 제한 증가
NODE_OPTIONS="--max-old-space-size=4096" npx lunaria build

Q4: 빌드가 느림

문제: 대규모 프로젝트 빌드 시간이 긺

해결 방법:

# 파일 수 확인
npx lunaria build --verbose | grep "Files found"

# 설정 최적화, 불필요한 파일 제외

요약

이 글에서는 LunariaJS CLI의 세 가지 핵심 명령어를 자세히 소개했습니다:

명령어	기능	자주 사용하는 매개변수
`lunaria init`	설정 파일 초기화	`--typescript`, `--yes`, `--force`
`lunaria build`	현지화 대시보드 빌드	`--output`, `--silent`, `--verbose`
`lunaria preview`	대시보드 로컬 미리보기	`--port`, `--open`, `--host`

핵심 포인트:

npx lunaria init으로 빠르게 시작
lunaria build는 핵심 명령어로 시각화 대시보드 생성
lunaria preview는 로컬 디버깅과 미리보기에 편리
CLI 명령어를 package.json scripts에 통합

다음 단계

다음 글에서는 LunariaJS 현지화 대시보드의 사용 방법을 깊이 있게 살펴보겠습니다:

대시보드 인터페이스 상세 설명
번역 상태 해석
파일 상태 추적
필터링 및 검색 기능
대시보드 사용자 정의

기대해 주세요!

💡 추천 읽기:

LunariaJS 한국어 문서

LunariaJS CLI 참조

LunariaJS 영어 문서

LunariaJS 일본어 문서

LunariaJS 중국어 문서