Installation KR

설치

🌐 English · 한국어

CLITrigger는 Windows · macOS · Linux에서 동작합니다 — 모든 핵심 코드가 크로스 플랫폼입니다.

사전 요구사항: Node.js 20+, Git, 그리고 최소 하나의 AI CLI(Claude / Gemini / Codex). macOS에서는 네이티브 모듈 컴파일을 위해 xcode-select --install이 필요할 수 있습니다.

빠른 시작

방법 A — 데스크톱 앱 (일반 사용자 추천)

최신 GitHub 릴리스에서 플랫폼별 설치 파일을 받으세요:

Windows — CLITrigger-Setup-<version>.exe (NSIS 인스톨러) 또는 포터블 .exe
macOS — CLITrigger-<version>.dmg (Apple Silicon & Intel)
Linux — CLITrigger-<version>.AppImage

데스크톱 앱은 Node.js와 네이티브 모듈(better-sqlite3, node-pty, cloudflared)을 번들로 포함하므로 별도 런타임 설치가 필요 없습니다. 첫 실행 시 내장 브라우저에 셋업 화면이 뜨고, 거기서 비밀번호를 정하면 바로 사용할 수 있습니다. 외부 공유(Cloudflare 터널)는 셋업이 끝날 때까지 시작되지 않아 첫 사용자가 본인임이 보장됩니다.

방법 B — npm (개발자 추천)

# 설치
npm i -g clitrigger
clitrigger

# 최신 버전으로 업그레이드
npm i -g clitrigger@latest
# 현재 버전 확인: clitrigger --version

첫 실행 시 서버가 바로 시작됩니다. http://localhost:3000 접속 → 환영 화면에서 비밀번호 설정 → 프로젝트 등록 → TODO 작성 → Start 클릭. 비밀번호는 이후 웹 UI의 설정 → 계정에서 변경합니다.

npm에 새 버전이 올라오면 시작 시 한 줄짜리 Update available 안내가 출력됩니다 — 자동 업데이트는 없으며 업그레이드 시점은 직접 결정합니다.

# 설정 변경
clitrigger config port 8080    # 포트 변경
clitrigger config tunnel on    # 외부 공유용 Cloudflare 터널 활성화

소스에서 실행 (개발용)

# 1. 클론 & 설치
git clone https://github.com/HyperAITeam/CLITrigger.git
cd CLITrigger
npm install
cd src/client && npm install && cd ../..

# 2. 환경 설정
cp .env.example .env
# AUTH_PASSWORD는 선택 사항 — 비워두면 첫 접속 시 셋업 화면이 뜬다.
# 셋업을 건너뛰려는 경우에만 값을 설정.

# 3. 실행
npm run dev

http://localhost:5173 접속.

Windows 원클릭 스크립트

scripts/ 폴더의 bat 파일을 더블클릭하면 터미널 없이 실행됩니다.

파일	동작
`install.bat`	의존성 설치 (최초 1회)
`dev.bat`	개발 모드 시작
`build.bat`	프로젝트 빌드
`start.bat`	프로덕션 서버 시작
`start-tunnel.bat`	Cloudflare 터널과 함께 시작
`test.bat`	전체 테스트 실행

macOS / Linux

npm run 명령은 모든 플랫폼에서 동일하게 동작합니다. .bat 대신 터미널을 사용하세요.

npm run dev        # 개발 모드
npm run build      # 빌드
npm run start      # 프로덕션 서버
npm test           # 테스트 실행

데이터 저장 위치

파일	경로
설정	`~/.clitrigger/config.json`
DB	`~/.clitrigger/clitrigger.db`
워크트리	각 프로젝트 폴더 안 `.worktrees/`
디버그 로그	각 프로젝트 폴더 안 `.debug-logs/`

환경 변수

.env, ~/.clitrigger/config.json, 또는 Electron userData/config.json으로 설정합니다.

변수	기본값	용도
`PORT`	`3000`	서버 포트
`DB_PATH`	`~/.clitrigger/clitrigger.db`	SQLite DB 경로
`AUTH_PASSWORD`	(빈 값)	선택 — 비우면 웹 셋업 화면
`TUNNEL_ENABLED`	`false`	Cloudflare 터널 활성화
`TUNNEL_NAME`	(빈 값)	Named tunnel 이름 (선택)
`TUNNEL_HOSTNAME`	(빈 값)	Named tunnel 커스텀 도메인 (`TUNNEL_NAME` 필요)
`LOG_RETENTION_DAYS`	`30`	디버그 로그 보관 일수
`HEADLESS`	`false`	true면 정적 파일 서빙 비활성화 (API 전용, 플러그인용)
`DISABLE_AUTH`	`false`	true면 인증 비활성화 (로컬 플러그인 전용)