Caffeine CLI 사용자 매뉴얼

📖 목차

개요
설치 및 설정
명령어 참조
- setup
- doctor
- init
- version
- package
- events
- benchmark
- docker
- demo
- edge
템플릿 시스템
사용 예시
트러블슈팅
FAQ

개요

Caffeine CLI는 Caffeine IoT 플랫폼 기반 프로젝트를 빠르고 쉽게 생성, 관리, 배포할 수 있는 명령줄 도구입니다.

주요 기능

🚀 배포 환경 구성: cafe setup 대화형 위자드로 Docker 환경 원클릭 구성
✅ 환경 진단: 개발 환경의 필수 요소 (SDK, Docker, 포트) 검증
🏗️ 프로젝트 생성: 템플릿 기반 드라이버 및 앱 프로젝트 생성
📦 패키징: NuGet 패키지 빌드 및 배포
📊 벤치마크: BenchmarkDotNet 실행, 결과 조회, 성능 비교
🐳 Docker: Docker Compose 설정 파일 자동 생성
🔧 버전 관리: CLI 및 런타임 버전 정보 확인

지원 환경

.NET SDK: 10.0 이상
OS: Windows, Linux, macOS
PowerShell: 5.1 이상 (Windows)

설치 및 설정

전제 조건

Caffeine CLI를 사용하기 전에 다음 도구가 설치되어 있어야 합니다:

.NET 10.0 SDK
```
dotnet --version
# 출력 예: 10.0.102
```

Docker (선택사항, doctor 명령어 사용 시)

docker --version
# 출력 예: Docker version 24.0.7

Git (선택사항, --git 옵션 사용 시)

git --version
# 출력 예: git version 2.42.0

CLI 설치

# NuGet에서 글로벌 도구 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 사용
cafe --help

# 업데이트
dotnet tool update -g NEXCODE.Caffeine.Cli

명령어 참조

전체 명령어 구조

`doctor` 명령어

목적: 개발 환경의 상태를 진단하고 필수 요소가 올바르게 설치되었는지 확인합니다.

사용법

cafe doctor

검사 항목

항목	검사 내용	기대 결과
.NET SDK	`dotnet --version` 실행	버전 10.0 이상
Docker	`docker --version` 실행	Docker가 설치 및 실행 중
Redis 포트	TCP 6379 포트 확인	사용 가능 또는 이미 사용 중
MQTT 포트	TCP 1883 포트 확인	사용 가능 또는 이미 사용 중
Kafka 포트	TCP 9092 포트 확인	사용 가능 또는 이미 사용 중

출력 예시

  ____   ___   ____ _____ ___  ____  
 |  _ \ / _ \ / ___|_   _/ _ \|  _ \ 
 | | | | | | | |     | || | | | |_) |
 | |_| | |_| | |___  | || |_| |  _ < 
 |____/ \___/ \____| |_| \___/|_| \_\

Diagnosing your development environment...

┌────────────────┬─────────────────────────┬────────┐
│ Component      │ Version/Status          │ Status │
├────────────────┼─────────────────────────┼────────┤
│ .NET SDK       │ 10.0.102                │ ✓ OK   │
│ Docker         │ 24.0.7                  │ ✓ OK   │
│ Redis (6379)   │ Available               │ ✓ OK   │
│ MQTT (1883)    │ In Use                  │ ⚠ WARN │
│ Kafka (9092)   │ Available               │ ✓ OK   │
└────────────────┴─────────────────────────┴────────┘

System is ready for Caffeine development!

트러블슈팅

Docker 없음: Docker Desktop 설치 또는 Linux에서 Docker Engine 설치
포트 사용 중: 해당 서비스가 이미 실행 중이므로 정상입니다
.NET SDK 버전 오류: dotnet --list-sdks로 설치된 버전 확인 후 업그레이드

`init` 명령어

목적: 템플릿 기반으로 새로운 Caffeine 프로젝트를 생성합니다.

사용법

# 대화형 모드
cafe init

# 비대화형 모드
cafe init --name <프로젝트명> --template <템플릿> [옵션]

옵션

옵션	축약형	설명	기본값	필수
`--name`	`-n`	프로젝트 이름	-	❌ (대화형)
`--template`	`-t`	템플릿 유형 (`driver`, `app`, `driver-full`, `solution`)	-	❌ (대화형)
`--output`	`-o`	출력 디렉토리	현재 디렉토리	❌
`--git`	`-g`	Git 저장소 초기화	`false`	❌

템플릿 종류

템플릿	설명	생성 파일
driver	기본 드라이버 프로젝트	`.csproj`, `DriverService.cs`, `README.md`
app	Caffeine 클라이언트 앱	`.csproj`, `Program.cs`, `README.md`
driver-full	드라이버 + 테스트 프로젝트	`src/`, `tests/` (완전한 구조)
solution	솔루션 템플릿	`.gitignore`

프로젝트 이름 규칙

프로젝트 이름은 다음 규칙을 준수해야 합니다:

✅ 영문자로 시작
✅ 영문자, 숫자, 하이픈(-), 밑줄(_) 사용 가능
❌ 숫자로 시작 불가
❌ 특수문자 (!@#$%^&*() 등) 사용 불가
❌ Windows 예약어 (CON, PRN, AUX, NUL 등) 사용 불가
❌ 공백 포함 불가

유효한 이름 예시: ModbusDriver, OpcUa-Client, My_Driver_2024
유효하지 않은 이름 예시: 123Driver, My Driver!, CON

워크플로우

사용 예시

예시 1: 대화형 모드

$ cafe init

   ____       __        ___       _ __ 
  / ___|__ _ / _| ___  |_ _|_ __ (_) __|
 | |   / _` | |_ / _ \  | || '_ \| | __| 
 | |__| (_| |  _|  __/  | || | | | | |_ 
  \____\__,_|_|  \___| |___|_| |_|_|\__|

What is the name of your project?
> ModbusDriver

Choose a template:
  driver
  app
> driver-full
  solution

Creating driver-full project: ModbusDriver

✅ Successfully created ModbusDriver!

Generated files:
  • src\ModbusDriver.csproj
  • src\ModbusDriver.cs
  • tests\ModbusDriver.Tests.csproj
  • tests\ModbusDriverTests.cs

Next steps:
  cd ModbusDriver
  dotnet restore
  dotnet build
  dotnet test

예시 2: 비대화형 모드

$ cafe init --name OpcUaDriver --template driver --output ./projects --git

Creating driver project: OpcUaDriver

✅ Successfully created OpcUaDriver!

Generated files:
  • OpcUaDriver.csproj
  • OpcUaDriver.cs
  • README.md

Initializing Git repository...
✅ Git repository initialized successfully

Next steps:
  cd OpcUaDriver
  dotnet restore
  dotnet build

생성된 프로젝트 구조

driver 템플릿

MyDriver/
├── MyDriver.csproj
├── MyDriver.cs
└── README.md

driver-full 템플릿

MyDriver/
├── src/
│   ├── MyDriver.csproj
│   └── MyDriver.cs
└── tests/
    ├── MyDriver.Tests.csproj
    └── MyDriverTests.cs

`version` 명령어

목적: Caffeine CLI 및 런타임 버전 정보를 표시합니다.

사용법

cafe version

출력 예시

__     __            _             
\ \   / /__ _ __ ___(_) ___  _ __  
 \ \ / / _ \ '__/ __| |/ _ \| '_ \ 
  \ V /  __/ |  \__ \ | (_) | | | |
   \_/ \___|_|  |___/_|\___/|_| |_|

┌──────────────────┬──────────────────────┐
│ Property         │ Value                │
├──────────────────┼──────────────────────┤
│ CLI Version      │ 0.9.0-prototype      │
│ Assembly Version │ 0.9.0                │
│ .NET Runtime     │ .NET 10.0.2          │
│ Operating System │ Microsoft Windows 11 │
│ Architecture     │ X64                  │
└──────────────────┴──────────────────────┘

For more information, visit: https://www.nexcode.co.kr/caffeine

정보 설명

CLI Version: 사용자에게 표시되는 버전 (InformationalVersion)
Assembly Version: 어셈블리 파일 버전
.NET Runtime: 현재 실행 중인 .NET 런타임 버전
Operating System: 운영 체제 정보
Architecture: CPU 아키텍처 (X64, ARM64 등)

`package` 명령어

목적: 현재 프로젝트를 NuGet 패키지로 빌드하고 NuGet 피드에 배포합니다.

사용법

# 프로젝트 디렉토리에서 실행
cd src/MyDriver
cafe package

전제 조건

현재 디렉토리가 Caffeine 프로젝트 (.csproj 파일에 Caffeine.Core 또는 Caffeine.Client 참조 포함)
publish_local.ps1 스크립트가 scripts/ 디렉토리에 존재

워크플로우

출력 예시

 ____            _                    
|  _ \ __ _  ___| | ____ _  __ _  ___ 
| |_) / _` |/ __| |/ / _` |/ _` |/ _ \
|  __/ (_| | (__|   < (_| | (_| |  __/
|_|   \__,_|\___|_|\_\__,_|\__, |\___|
                           |___/      

Building NuGet package...

✅ Package built successfully

Package has been published to NuGet feed.

에러 메시지

1. Caffeine 프로젝트가 아닌 경우

❌ Not a Caffeine project directory.
Please run this command in a directory containing a Caffeine project (.csproj with Caffeine references).

해결: Caffeine.Core 또는 Caffeine.Client를 참조하는 프로젝트 디렉토리에서 실행

2. 스크립트 없음

❌ publish_local.ps1 script not found. Please ensure you are in a Caffeine project directory.

💡 Tip: Ensure publish_local.ps1 exists in scripts/ directory.

해결: 프로젝트 루트에 scripts/publish_local.ps1 파일 확인

`events` 명령어

목적: 시스템에 등록된 이벤트 카탈로그를 조회합니다.

서브커맨드 구조

cafe events <서브커맨드> [옵션]

서브커맨드	설명
`list`	등록된 이벤트 전체 목록 출력
`show <eventName>`	특정 이벤트의 상세 정보 출력

`events list`

모든 등록된 이벤트를 테이블 형식으로 출력합니다.

사용법

cafe events list [옵션]

옵션

옵션	축약형	설명	기본값
`--severity`	`-s`	심각도 필터 (`Debug`, `Info`, `Warning`, `Error`, `Critical`)	전체
`--assembly`	`-a`	어셈블리 이름 필터 (부분 일치)	전체

출력 예시

 _____                 _
| ____|_   _____ _ __ | |_ ___
|  _| \ \ / / _ \ '_ \| __/ __|
| |___ \ V /  __/ | | | |_\__ \
|_____| \_/ \___|_| |_|\__|___/

╭─────────────────────────────┬──────────┬──────────────────────────────────────┬──────────────────────────────╮
│ Event Name                  │ Severity │ Description                          │ Assembly                     │
├─────────────────────────────┼──────────┼──────────────────────────────────────┼──────────────────────────────┤
│ DeviceConnected             │ Info     │ 장치 연결 성공                         │ Caffeine.Core                │
│ DeviceDisconnected          │ Warning  │ 장치 연결 해제                         │ Caffeine.Core                │
│ DataIngestionFailed         │ Error    │ 데이터 수집 실패                        │ Caffeine.Engine              │
│ AlarmTriggered              │ Critical │ 알람 발생                              │ Caffeine.Engine              │
╰─────────────────────────────┴──────────┴──────────────────────────────────────┴──────────────────────────────╯

Total: 4 event(s)

필터링 예시

# 심각도 Error 이상만 조회
cafe events list --severity Error

# 특정 어셈블리 이벤트만 조회
cafe events list --assembly Caffeine.Engine

# 심각도 + 어셈블리 복합 필터
cafe events list -s Warning -a Caffeine.Core

`events show`

특정 이벤트의 상세 정보를 출력합니다.

사용법

cafe events show <eventName>

인수

인수	설명	필수
`eventName`	조회할 이벤트 이름 (정확한 이름)	✅

출력 예시

$ cafe events show DeviceConnected

 _____                 _
| ____|_   _____ _ __ | |_
|  _| \ \ / / _ \ '_ \| __|
| |___ \ V /  __/ | | | |_
|_____| \_/ \___|_| |_|\__|

╭──────────────┬────────────────────────────────╮
│ Event Name   │ DeviceConnected                │
│ Description  │ 장치 연결 성공                  │
│ Severity     │ Info                           │
│ Type         │ Caffeine.Core.Events.DeviceConnectedEvent │
│ Assembly     │ Caffeine.Core                  │
╰──────────────┴────────────────────────────────╯

이벤트를 찾지 못한 경우

$ cafe events show UnknownEvent

❌ Event 'UnknownEvent'을 찾을 수 없습니다.

심각도(Severity) 종류

값	설명	표시 색상
`Debug`	디버그 정보	회색
`Info`	일반 정보	청록색
`Warning`	주의 필요	노란색
`Error`	오류 발생	빨간색
`Critical`	심각한 오류	자주색

`setup` 명령어

목적: Caffeine 배포 환경을 대화형 위자드로 구성합니다. Docker Compose 프로파일 선택, .env 자동 생성, Production 보안 검증, 원격 SSH 배포를 단계적으로 안내합니다.

사용법

# 대화형 위자드 (가장 일반적인 사용법)
cafe setup

# Production 모드 (보안 체크리스트 포함)
cafe setup --mode production

# 원격 SSH 배포
cafe setup --remote ssh://user@192.168.1.100

옵션

옵션	단축키	기본값	설명
`--mode`	`-m`	`development`	배포 모드 (`development` \| `production`)
`--remote`	—	—	원격 Docker SSH URL (예: `ssh://user@host`)
`--source`	`-s`	—	오프라인 배포 팩 경로 (`caffeine-pack-*.tar.gz`, `.zip`, 또는 풀린 디렉토리). 오프라인 배포 가이드 참조

지원 프로파일

프로파일	서비스	용도
`minimal`	Redis, MQTT	드라이버 개발 최소 환경
`standard`	+ InfluxDB, Kafka	표준 개발환경 (권장)
`full`	+ TypeDB, Grafana	전체 기능 개발
`full+monitoring`	+ Prometheus	운영 모니터링 포함
`app`	+ Caffeine Engine, Admin	소스 없이 앱 실행

서브커맨드

`setup status` — 서비스 상태 확인

# 실행 중인 Docker Compose 서비스 목록
cafe setup status

# HTTP /health 엔드포인트 폴링 포함
cafe setup status --health

# 원격 서버 상태 확인
cafe setup status --remote ssh://user@host

옵션	단축키	설명
`--health`	`-H`	HTTP `/health` 엔드포인트 폴링
`--remote`	—	원격 Docker SSH URL

`setup down` — 서비스 중지

cafe setup down
cafe setup down --remote ssh://user@host

`setup extract` — 배포 파일 추출

CLI에 내장된 docker-compose.yml, .env.example 등의 배포 파일을 추출합니다.

# 현재 디렉토리에 추출
cafe setup extract

# 특정 경로에 추출
cafe setup extract --output ./deploy

# 특정 프로파일 파일만 추출
cafe setup extract --profile minimal

# 내장 리소스 목록 확인
cafe setup extract --list

# 기존 파일 덮어쓰기
cafe setup extract --force

옵션	단축키	기본값	설명
`--output`	`-o`	현재 디렉토리	추출 대상 경로
`--force`	`-f`	`false`	기존 파일 덮어쓰기
`--list`	`-l`	`false`	리소스 목록만 표시
`--profile`	`-p`	—	특정 프로파일 파일만 추출

`setup clean` — 배포 환경 정리/초기화

Docker 컨테이너, 볼륨, 런타임 데이터를 정리한다. 파괴적 작업이므로 현재 상태를 표시한 뒤 사용자 확인을 받는다.

# 기본: 컨테이너 + 볼륨 + caffeine-data/ 삭제
cafe setup clean

# 전체: + .env 파일 + NuGet 소스 해제
cafe setup clean --all

# 원격 서버 대상
cafe setup clean --remote ssh://user@host --all

옵션	기본값	설명
`--all`	`false`	`.env` 파일 삭제 + NuGet CaffeineOffline 소스 해제 포함
`--remote`	—	원격 Docker context 지정

정리 단계:

단계	대상	기본	`--all`
1	Docker 컨테이너 중지 + 삭제 (`caffeine-*`)	✅	✅
2	Docker 볼륨 삭제	✅	✅
3	런타임 데이터 (`caffeine-data/`) 삭제	✅	✅
4	`.env` 파일 삭제 (시크릿 포함 — 재생성 필요)	—	✅
5	NuGet CaffeineOffline 로컬 소스 해제	—	✅

⚠️ 이 작업은 되돌릴 수 없습니다. 실행 전 현재 상태를 테이블로 보여주고, 기본값 No로 확인을 요청합니다.

출력 예시

   ____         __       ____       __
  / ___|__ _ / _| ___  / ___|  ___| |_ _   _ _ __
 | |   / _` | |_ / _ \ \___ \ / _ \ __| | | | '_ \
 | |__| (_| |  _|  __/  ___) |  __/ |_| |_| | |_) |
  \____\__,_|_|  \___| |____/ \___|\__|\__,_| .__/
                                             |_|
Caffeine 배포 환경 구성 마법사

사전 검증 중...
✅ Docker: 설치됨 (24.0.7)
✅ Docker 데몬: 실행 중
✅ Docker Compose: 사용 가능 (v2.23.0)

? 배포 프로파일을 선택하세요:
  Minimal (드라이버 개발용)
❯ Standard (표준 개발환경 — 권장)
  Full (전체 개발)
  Full + Monitoring (모니터링 포함)
  Server (중앙 서버 배포)
  Edge (엣지 게이트웨이)

자세한 내용은 배포 위자드 가이드를 참조하세요.

`benchmark` 명령어

목적: BenchmarkDotNet 벤치마크를 실행하고, 이전 결과를 조회하거나 두 결과를 비교합니다.

사용법

# 벤치마크 실행
cafe benchmark run

# 특정 벤치마크만 필터링 실행
cafe benchmark run --filter "*Serialization*"

# 결과를 특정 디렉토리에 내보내기
cafe benchmark run --export ./results

# 최근 벤치마크 결과 목록 조회
cafe benchmark list
cafe benchmark list --last 5

# 두 결과를 비교
cafe benchmark compare <baseline-id> <current-id>

서브커맨드

`benchmark run` — 벤치마크 실행

옵션	단축키	설명
`--filter`	`-f`	BenchmarkDotNet 필터 패턴 (예: `Serialization`)
`--export`	`-e`	결과 내보내기 디렉토리

`benchmark list` — 결과 목록 조회

옵션	단축키	기본값	설명
`--last`	`-l`	`10`	표시할 결과 수

`benchmark compare` — 결과 비교

인수	필수	설명
`baseline`	✅	기준(Baseline) 실행 ID
`current`	✅	비교 대상(Current) 실행 ID

비교 결과는 각 메서드별 성능 변화율(%)을 표시합니다:

▼ 개선: < -5% (빨라짐)
— 유지: -5% ~ 10%
▲ 회귀: > 10% (느려짐, 확인 필요)

벤치마크 상세 가이드는 벤치마크 테스트 & 리포팅 가이드를 참조하세요.

`docker` 명령어

목적: Caffeine 서비스용 Docker Compose 설정 파일을 자동 생성합니다.

사용법

# 전체 프로파일로 docker-compose.yml 생성
cafe docker generate

# 슬림 프로파일 (최소 서비스)
cafe docker generate --profile slim

# 하이브리드 프로파일 + 지정 디렉토리
cafe docker generate --profile hybrid --output ./deploy

서브커맨드

`docker generate` — Docker Compose 파일 생성

옵션	단축키	기본값	설명
`--profile`	`-p`	`full`	배포 프로파일 (`full` \| `slim` \| `hybrid`)
`--output`	`-o`	`.`	출력 디렉토리

프로파일별 서비스

프로파일	서비스
`full`	Engine, Admin, Bridge.Host, Redis, InfluxDB, Kafka, MQTT, TypeDB
`slim`	Engine, Bridge.Host, Redis
`hybrid`	Engine, Bridge.Host, Redis, InfluxDB, MQTT

`demo` 명령어

목적: 고객 시연용 데모 환경을 간편하게 구성·관리합니다. MQTT 브로커, Redis, 시뮬레이터 Docker 컨테이너를 위자드 형태로 시작/중지할 수 있습니다.

사용법

# 데모 인프라 시작 (MQTT + Redis)
cafe demo up

# 시뮬레이터 실행
cafe demo simulator --host 192.168.1.100

# 상태 확인
cafe demo status

# 시나리오 전환
cafe demo scenario Overheat

# 정리
cafe demo down --all

서브커맨드

`demo up` — 데모 인프라 시작

MQTT 브로커와 Redis를 Docker 컨테이너로 시작합니다. Docker preflight 검사, 포트 충돌 확인, 기존 컨테이너 감지를 자동 처리합니다.

옵션	기본값	설명
`--mqtt-port`	`1883`	MQTT 브로커 포트
`--redis-port`	`6379`	Redis 포트
`--skip-redis`	`false`	MQTT만 시작 (Redis 건너뛰기)

`demo simulator` — 시뮬레이터 실행

Edge PC 또는 Host PC에서 시뮬레이터 Docker 컨테이너를 실행합니다.

옵션	단축키	기본값	설명
`--host`	`-h`	(필수)	Host PC IP 주소 (MQTT_HOST)
`--device-id`	`-d`	`Edge-01`	장치 ID prefix
`--device-count`	`-c`	`5`	시뮬레이션 장치 수
`--scenario`	`-s`	`Normal`	초기 시나리오 (`Normal` \| `Overheat` \| `PressureDrop` \| `RandomSpike`)
`--rps`		`10`	초당 목표 전송 횟수
`--batch-size`	`-b`	`5`	배치 크기
`--image`		`caffeine-simulator:latest`	Docker 이미지
`--detach`		`false`	백그라운드 실행

`demo status` — 상태 확인

caffeine-demo- 접두사를 가진 모든 컨테이너의 상태를 테이블로 표시합니다.

`demo down` — 정리

데모 컨테이너를 중지하고 제거합니다.

옵션	단축키	기본값	설명
`--all`	`-a`	`false`	시뮬레이터 컨테이너까지 모두 정리

`demo scenario` — 시나리오 전환

실행 중인 시뮬레이터의 데이터 패턴을 런타임에 전환합니다. Engine REST API를 통해 MQTT 명령을 발행합니다.

# 직접 지정
cafe demo scenario Overheat

# 대화형 선택 (인자 생략 시)
cafe demo scenario

옵션	기본값	설명
`--engine-url`	`http://localhost:5001`	Engine API URL

edge 명령어

엣지 디바이스 생명주기 관리. Linux(systemd) 환경에서 Bridge.Host를 서비스로 설치·관리합니다.

`cafe edge install`

Bridge.Host를 systemd 서비스로 설치합니다. Root 권한 필수.

cafe edge install --source caffeine-pack-3.2.0.tar.gz

옵션	단축	기본값	설명
`--source`	`-s`	—	오프라인 배포 팩 또는 바이너리 디렉토리 경로
`--path`	—	`/opt/caffeine/bridge-host`	설치 경로
`--skip-docker`	—	`false`	외부 MQTT/Redis 사용 시 Docker 설치 건너뛰기
`--upgrade`	—	`false`	기존 설치 업그레이드 (백업 → 교체 → 재시작)

설치 과정 (6단계):

환경 검증 — Linux + systemd + Docker(선택) + root 확인
바이너리 배치 — /opt/caffeine/bridge-host/에 Bridge.Host 배치
환경 설정 — .env 파일 대화형 생성 (Driver ID, Engine URL, MQTT/Redis)
Docker 인프라 — MQTT + Redis 컨테이너 시작 (restart: always)
systemd 서비스 — caffeine-bridge.service 등록 + 활성화
서비스 시작 — 자동 시작 + 상태 확인

systemd 서비스 특성:

Restart=always — 크래시 후 5초 뒤 자동 재시작
WatchdogSec=90 — hung 프로세스 자동 감지
MemoryMax=512M, CPUQuota=80% — RPi 리소스 보호

`cafe edge status`

Edge 서비스 상태 및 Health 정보를 표시합니다.

cafe edge status

출력 예시:

┌────────────────┬───────────────────────────┐
│ 항목            │ 상태                      │
├────────────────┼───────────────────────────┤
│ 서비스          │ ● 실행 중 (PID: 1234)     │
│ 부팅 시 자동 시작│ 활성화                    │
│ 마지막 시작     │ 2026-03-28 10:00:00       │
│ 메모리 사용량   │ 128 MB                    │
├────────────────┼───────────────────────────┤
│ Health Endpoint │ Healthy                   │
└────────────────┴───────────────────────────┘

`cafe edge uninstall`

Bridge.Host 서비스와 파일을 제거합니다. Root 권한 필수.

cafe edge uninstall
cafe edge uninstall --keep-data  # 오프라인 버퍼 데이터 유지

옵션	기본값	설명
`--keep-data`	`false`	오프라인 버퍼 데이터(`data/` 디렉토리) 유지

`cafe edge logs`

Bridge.Host 서비스 로그를 표시합니다 (journalctl 래핑).

cafe edge logs           # 최근 50줄
cafe edge logs -n 100    # 최근 100줄
cafe edge logs -f        # 실시간 추적

옵션	단축	기본값	설명
`--follow`	`-f`	`false`	실시간 로그 추적
`--lines`	`-n`	`50`	표시할 로그 줄 수

템플릿 시스템

Caffeine CLI는 Embedded Resource로 템플릿을 관리하며, 프로젝트 생성 시 변수를 치환합니다.

템플릿 변수

모든 템플릿 파일(.template)에서 사용 가능한 변수:

변수	설명	예시
`{{ProjectName}}`	사용자가 입력한 프로젝트 이름	`ModbusDriver`
`{{Namespace}}`	C# 네임스페이스 (하이픈/공백 → 밑줄)	`Modbus_Driver`
`{{ClassName}}`	C# 클래스명 (하이픈/공백 제거)	`ModbusDriver`
`{{Year}}`	현재 연도	`2026`
`{{Month}}`	현재 월 (2자리)	`01`
`{{Day}}`	현재 일 (2자리)	`28`
`{{Author}}`	시스템 사용자명	`matrix`

템플릿 구조

driver 템플릿

Templates/driver/
├── Driver.csproj.template
├── DriverService.cs.template
└── README.md.template

파일 변환 예시:

Driver.csproj.template → ModbusDriver.csproj
DriverService.cs.template → ModbusDriver.cs

driver-full 템플릿

Templates/driver-full/
├── src/
│   ├── Driver.csproj.template
│   └── DriverService.cs.template
└── tests/
    ├── DriverTests.csproj.template
    └── DriverServiceTests.cs.template

디렉토리 구조 유지: src/, tests/ 디렉토리가 그대로 생성됩니다.

템플릿 예시

Driver.csproj.template

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <RootNamespace>{{Namespace}}</RootNamespace>
    <Authors>{{Author}}</Authors>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NEXCODE.Caffeine.Core" Version="2.0.*" />
  </ItemGroup>
</Project>

치환 후 (프로젝트명: ModbusDriver):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <RootNamespace>ModbusDriver</RootNamespace>
    <Authors>matrix</Authors>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NEXCODE.Caffeine.Core" Version="2.0.*" />
  </ItemGroup>
</Project>

사용 예시

시나리오 1: Modbus 드라이버 개발

요구사항: Modbus TCP 프로토콜을 지원하는 드라이버 개발

# 1. 프로젝트 생성 (테스트 포함)
cafe init --name ModbusTcpDriver --template driver-full --git

cd ModbusTcpDriver

# 2. 의존성 복원 및 빌드
dotnet restore
dotnet build

# 3. 테스트 실행
dotnet test

# 4. 구현 후 패키징
cd src
cafe package

시나리오 2: 데이터 수집 앱 개발

요구사항: Caffeine 클라이언트를 사용한 데이터 수집 앱

# 1. 프로젝트 생성
cafe init -n DataCollectorApp -t app -o ./projects

cd projects/DataCollectorApp

# 2. Program.cs 수정 (비즈니스 로직 추가)
# ... 코드 작성 ...

# 3. 실행
dotnet run

시나리오 3: CI/CD 파이프라인

GitHub Actions 예시:

name: Build and Package

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '10.0.x'
      
      - name: Install Caffeine CLI
        run: dotnet tool install -g NEXCODE.Caffeine.Cli

      - name: Diagnose Environment
        run: cafe doctor

      - name: Build Driver
        run: dotnet build MyDriver/MyDriver.csproj

      - name: Run Tests
        run: dotnet test MyDriver.Tests/MyDriver.Tests.csproj

      - name: Package
        run: cafe package
        working-directory: src/MyDriver

트러블슈팅

문제 1: "Not a valid project name" 에러

증상:

❌ Invalid project name: Names starting with a digit are not allowed.

원인: 프로젝트 이름이 숫자로 시작하거나 특수문자 포함

해결:

영문자로 시작하는 이름 사용
특수문자 대신 하이픈(-) 또는 밑줄(_) 사용

예시:

# ❌ 잘못된 이름
cafe init --name 2024Driver      # 숫자 시작
cafe init --name My Driver!      # 공백 및 특수문자

# ✅ 올바른 이름
cafe init --name Driver2024
cafe init --name My-Driver

문제 2: "Directory already exists" 에러

증상:

❌ Failed to create project: Directory 'MyDriver' already exists.

원인: 동일한 이름의 디렉토리가 이미 존재

해결:

# 방법 1: 다른 이름 사용
cafe init --name MyDriver_v2

# 방법 2: 기존 디렉토리 제거
rm -rf MyDriver
cafe init --name MyDriver

# 방법 3: 다른 출력 경로 지정
cafe init --name MyDriver --output ./new_projects

문제 3: Git 초기화 실패

증상:

⚠️  Git is not installed or not in PATH. Please install Git first.

원인: Git이 설치되지 않았거나 환경 변수 PATH에 없음

해결:

# Windows (Chocolatey)
choco install git

# Linux (Ubuntu)
sudo apt install git

# macOS (Homebrew)
brew install git

# 설치 확인
git --version

문제 4: Package 명령어가 스크립트를 찾지 못함

증상:

❌ publish_local.ps1 script not found.

원인: 프로젝트 구조가 표준과 다르거나 스크립트가 없음

해결:

# 1. 현재 위치 확인
pwd

# 2. 스크립트 존재 확인
ls scripts/publish_local.ps1

# 3. 루트 디렉토리로 이동 후 재시도
cd ../..
cd src/MyDriver
cafe package

문제 5: PowerShell Execution Policy 에러

증상 (Windows):

... cannot be loaded because running scripts is disabled on this system.

원인: PowerShell 스크립트 실행 정책 제한

해결:

# 현재 세션만 허용
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# 또는 사용자 수준으로 영구 허용 (관리자 권한)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

FAQ

Q1: CLI를 전역 도구로 설치할 수 있나요?

A: 예, NuGet에서 글로벌 도구로 설치할 수 있습니다.

# NuGet 글로벌 도구로 설치
dotnet tool install -g NEXCODE.Caffeine.Cli

# 설치 확인
cafe --version

# 업데이트
dotnet tool update -g NEXCODE.Caffeine.Cli

Q2: 커스텀 템플릿을 추가할 수 있나요?

A: 현재는 내장 템플릿만 지원합니다. 향후 버전에서 외부 커스텀 템플릿 지원이 예정되어 있습니다.

Q3: 생성된 프로젝트의 .NET 버전을 변경할 수 있나요?

A: 템플릿은 기본적으로 net10.0을 사용합니다. 변경 방법:

# 1. 프로젝트 생성
cafe init --name MyDriver --template driver

# 2. .csproj 파일 수정
cd MyDriver
# <TargetFramework>net10.0</TargetFramework>를
# <TargetFramework>net9.0</TargetFramework>로 변경

# 3. 재빌드
dotnet build

Q4: `init` 명령어가 실패했는데 롤백이 되나요?

A: 예, 실패 시 생성된 디렉토리가 자동으로 삭제됩니다. 수동 정리가 필요 없습니다.

Q5: 여러 프로젝트를 한 번에 생성할 수 있나요?

A: 현재는 스크립트로 우회 가능합니다:

# projects.txt 파일 생성
# ModbusDriver driver
# OpcUaDriver driver
# DataCollector app

# 스크립트 실행
while read name template; do
  cafe init --name $name --template $template
done < projects.txt

향후 배치 생성 기능 추가 예정입니다.

Q6: Windows에서 PowerShell 대신 CMD를 써도 되나요?

A: 기본 명령어 (doctor, init, version)는 CMD에서도 동작하지만, package 명령어는 PowerShell 스크립트를 사용하므로 PowerShell이 필요합니다.

REM CMD에서 PowerShell 호출
powershell -Command "cafe package"

Q7: 생성된 프로젝트에 라이선스를 추가할 수 있나요?

A: 현재는 수동으로 추가해야 합니다:

# 프로젝트 생성
cafe init --name MyDriver --template driver

# LICENSE 파일 추가
cd MyDriver
cat > LICENSE << EOF
Copyright ©  2026. NEXCODE. All rights reserved
...
EOF

향후 --license 옵션 추가 예정입니다.

부록

A. 명령어 치트시트

# ── 배포 ──────────────────────────────────────
# 대화형 위자드 (권장)
cafe setup

# Production 모드 배포
cafe setup --mode production

# 원격 SSH 배포
cafe setup --remote ssh://user@host

# 서비스 상태 확인
cafe setup status

# HTTP 헬스 체크 포함
cafe setup status --health

# 서비스 중지
cafe setup down

# 배포 파일 추출
cafe setup extract

# ── 환경 진단 ──────────────────────────────────
cafe doctor

# ── 프로젝트 생성 ──────────────────────────────
# 대화형
cafe init

# 비대화형
cafe init -n MyProject -t driver

# Git 포함 프로젝트 생성
cafe init -n MyProject -t driver-full -g

# 특정 경로에 생성
cafe init -n MyProject -t app -o ./projects

# ── 기타 ───────────────────────────────────────
# 버전 확인
cafe version

# NuGet 패키징
cafe package

# ── 벤치마크 ─────────────────────────────────
# 벤치마크 실행
cafe benchmark run

# 특정 벤치마크만 실행
cafe benchmark run --filter "*Serialization*"

# 최근 결과 목록
cafe benchmark list

# 두 결과 비교
cafe benchmark compare <baseline-id> <current-id>

# ── Docker ───────────────────────────────────
# Docker Compose 파일 생성
cafe docker generate

# 슬림 프로파일
cafe docker generate --profile slim

# ── 데모 (v3.2.0) ───────────────────────────
# 데모 인프라 시작
cafe demo up

# 시뮬레이터 실행
cafe demo simulator --host 192.168.1.100

# 시나리오 전환
cafe demo scenario Overheat

# 상태 확인
cafe demo status

# 정리
cafe demo down --all

# ── 이벤트 카탈로그 ──────────────────────────
# 이벤트 목록
cafe events list

# 심각도별 필터
cafe events list --severity Error

# 이벤트 상세 조회
cafe events show <이벤트명>

B. 템플릿 선택 가이드

용도	권장 템플릿	이유
간단한 드라이버	`driver`	빠른 프로토타입
프로덕션 드라이버	`driver-full`	테스트 포함
데이터 수집 앱	`app`	Caffeine 클라이언트 통합
멀티 프로젝트	`solution`	.gitignore 포함

C. 관련 링크

Caffeine 공식 문서: https://docs.nexcode.co.kr/caffeine
기술 지원: matrix@live.co.kr

작성일: 2026-01-28
버전: 1.0
작성자: Caffeine Development Team

📖 목차​

개요​

주요 기능​

지원 환경​

설치 및 설정​

전제 조건​

CLI 설치​

명령어 참조​

전체 명령어 구조​

doctor 명령어​

사용법​

검사 항목​

출력 예시​

트러블슈팅​

init 명령어​

사용법​

옵션​

템플릿 종류​

프로젝트 이름 규칙​

워크플로우​

사용 예시​

예시 1: 대화형 모드​

예시 2: 비대화형 모드​

생성된 프로젝트 구조​

driver 템플릿​

driver-full 템플릿​

version 명령어​

사용법​

출력 예시​

정보 설명​

package 명령어​

사용법​

전제 조건​

워크플로우​

출력 예시​

에러 메시지​

1. Caffeine 프로젝트가 아닌 경우​

2. 스크립트 없음​

events 명령어​

서브커맨드 구조​

events list​

사용법​

옵션​

출력 예시​

필터링 예시​

events show​

사용법​

인수​

출력 예시​

이벤트를 찾지 못한 경우​

심각도(Severity) 종류​

setup 명령어​

사용법​

옵션​

지원 프로파일​

서브커맨드​

setup status — 서비스 상태 확인​

setup down — 서비스 중지​

setup extract — 배포 파일 추출​

setup clean — 배포 환경 정리/초기화​

출력 예시​

benchmark 명령어​

사용법​

서브커맨드​

benchmark run — 벤치마크 실행​

benchmark list — 결과 목록 조회​

benchmark compare — 결과 비교​

docker 명령어​

사용법​

서브커맨드​

docker generate — Docker Compose 파일 생성​

프로파일별 서비스​

demo 명령어​

사용법​

서브커맨드​

demo up — 데모 인프라 시작​

demo simulator — 시뮬레이터 실행​

demo status — 상태 확인​

demo down — 정리​

demo scenario — 시나리오 전환​

📖 목차

개요

주요 기능

지원 환경

설치 및 설정

전제 조건

CLI 설치

명령어 참조

전체 명령어 구조

`doctor` 명령어

사용법

검사 항목

출력 예시

트러블슈팅

`init` 명령어

사용법

옵션

템플릿 종류

프로젝트 이름 규칙

워크플로우

사용 예시

예시 1: 대화형 모드

예시 2: 비대화형 모드

생성된 프로젝트 구조

driver 템플릿

driver-full 템플릿

`version` 명령어

사용법

출력 예시

정보 설명

`package` 명령어

사용법

전제 조건

워크플로우

출력 예시

에러 메시지

1. Caffeine 프로젝트가 아닌 경우

2. 스크립트 없음

`events` 명령어

서브커맨드 구조

`events list`

사용법

옵션

출력 예시

필터링 예시

`events show`

사용법

인수

출력 예시

이벤트를 찾지 못한 경우

심각도(Severity) 종류

`setup` 명령어

사용법

옵션

지원 프로파일

서브커맨드

`setup status` — 서비스 상태 확인

`setup down` — 서비스 중지

`setup extract` — 배포 파일 추출

`setup clean` — 배포 환경 정리/초기화

출력 예시

`benchmark` 명령어

사용법

서브커맨드

`benchmark run` — 벤치마크 실행

`benchmark list` — 결과 목록 조회

`benchmark compare` — 결과 비교

`docker` 명령어

사용법

서브커맨드

`docker generate` — Docker Compose 파일 생성

프로파일별 서비스

`demo` 명령어

사용법

서브커맨드

`demo up` — 데모 인프라 시작

`demo simulator` — 시뮬레이터 실행

`demo status` — 상태 확인

`demo down` — 정리

`demo scenario` — 시나리오 전환