Installation

🌐 English · 한국어

CLITrigger runs on Windows · macOS · Linux — all core code is cross-platform.

Prerequisites: Node.js 20+, Git, and at least one AI CLI (Claude / Gemini / Codex). On macOS you may need xcode-select --install for native module compilation.

Quick Start

Option A — Desktop App (recommended for end users)

Download the installer for your platform from the latest GitHub release:

Windows — CLITrigger-Setup-<version>.exe (NSIS installer) or the portable .exe
macOS — CLITrigger-<version>.dmg (Apple Silicon & Intel)
Linux — CLITrigger-<version>.AppImage

The desktop app bundles Node.js and the native modules (better-sqlite3, node-pty, cloudflared), so no separate runtime install is needed. On first launch a setup screen appears in the embedded browser — pick a password there and you're in. External sharing (Cloudflare tunnel) stays paused until setup completes, so the first user is guaranteed to be you.

Option B — npm (recommended for developers)

# Install
npm i -g clitrigger
clitrigger

# Upgrade to the latest version
npm i -g clitrigger@latest
# Check current version: clitrigger --version

On first run the server starts immediately. Open http://localhost:3000 → set a password on the welcome screen → register a project → write TODOs → click Start. Change the password later via Settings → Account in the web UI.

CLITrigger also prints a one-line Update available hint at startup whenever a newer version is on npm — no auto-update, you decide when to upgrade.

# Change settings
clitrigger config port 8080    # Change port
clitrigger config tunnel on    # Enable Cloudflare tunnel for external sharing

Run from Source (for development)

# 1. Clone & install
git clone https://github.com/HyperAITeam/CLITrigger.git
cd CLITrigger
npm install
cd src/client && npm install && cd ../..

# 2. Configure environment
cp .env.example .env
# AUTH_PASSWORD is optional — leave it blank and the dev server will show the
# setup screen on first browser load. Set it only if you want to skip setup.

# 3. Run
npm run dev

Open http://localhost:5173.

Windows One-Click Scripts

Double-click any bat file in scripts/ — no terminal needed.

File	Action
`install.bat`	Install dependencies (first time)
`dev.bat`	Start development mode
`build.bat`	Build project
`start.bat`	Start production server
`start-tunnel.bat`	Start with Cloudflare Tunnel
`test.bat`	Run all tests

macOS / Linux

npm run commands work identically on all platforms. Use the terminal instead of .bat scripts.

npm run dev        # Development mode
npm run build      # Build
npm run start      # Production server
npm test           # Run tests

Data Locations

File	Path
Config	`~/.clitrigger/config.json`
DB	`~/.clitrigger/clitrigger.db`
Worktrees	`.worktrees/` inside each project folder
Debug logs	`.debug-logs/` inside each project folder

Environment Variables

Config via .env, ~/.clitrigger/config.json, or Electron userData/config.json.

Var	Default	Purpose
`PORT`	`3000`	Server port
`DB_PATH`	`~/.clitrigger/clitrigger.db`	SQLite database path
`AUTH_PASSWORD`	(empty)	Optional — leave blank for the web setup screen
`TUNNEL_ENABLED`	`false`	Enable Cloudflare Tunnel
`TUNNEL_NAME`	(empty)	Named tunnel name (optional)
`TUNNEL_HOSTNAME`	(empty)	Named tunnel custom domain (requires `TUNNEL_NAME`)
`LOG_RETENTION_DAYS`	`30`	Debug log retention
`HEADLESS`	`false`	Disable static file serving (API-only, for plugins)
`DISABLE_AUTH`	`false`	Disable auth (local plugin use only)