UsageTrail CLI 설치 가이드

로컬 로그를 읽어(native 기본) 과거 전체 사용량을 UsageTrail로 백필하고, Claude Code 의 실제 한도까지 수집합니다. 나가는 데이터는 일·모델 단위 집계 수치뿐이며 프롬프트·코드·경로는 포함하지 않습니다.

사전 준비

Node.js 20+ (내장 fetch 사용). 설치가 안 돼 있으면 nodejs.org 에서 LTS 를 받거나 아래 명령을 쓰세요.
Claude Code 사용 기록(~/.claude/…)이 있는 컴퓨터에서 실행
Pro/Max 플랜이면 실제 5시간·주간 한도까지 수집됩니다(3단계).

# Node.js 설치 (택1)
macOS:    brew install node
Windows:  winget install OpenJS.NodeJS.LTS
Linux:    sudo apt-get install -y nodejs npm
# 설치 확인 (v20 이상)
node -v

brew가 없으면 brew.sh, 그 외에는 nodejs.org 의 설치 프로그램을 이용하세요.

1. API 토큰 발급

로그인 후 API 토큰 페이지에서 토큰을 발급합니다(한 번만 표시).

2. CLI 내려받기 & 로그인

단일 파일 스크립트입니다. 원하는 폴더에서:

curl -fsSL https://usagetrail.com/aipt.mjs -o aipt.mjs
node aipt.mjs login <API_TOKEN>

URL을 생략하면 https://usagetrail.com가 기본입니다. 로컬/QA 서버라면 --url로 지정하세요.

3. 실측 한도 수집 (statusLine) · 핵심

Claude Code 의 statusLine은 실제 5시간·주간(7일) 한도 %와 요금제를 넘겨줍니다(Pro/Max, 첫 응답 이후). 이 단계를 설치해야 실측 한도로 정확히 계산되고 요금제도 자동 감지됩니다. 가능하면 꼭 설치하세요. 한 줄이면 ~/.claude/settings.json에 자동 설정됩니다(기존 statusline 은 보존).

node aipt.mjs statusline-install            # 하단에 표시 + 수집
node aipt.mjs statusline-install --no-display   # 표시 없이 데이터만 수집

새 세션을 열면 하단에 UT · 5h 16% · wk 50%처럼 표시됩니다. 업로드는 %가 바뀌거나 5분마다 백그라운드로만 이뤄져 상태줄을 느리게 하지 않습니다. 되돌리려면 settings.json의 statusLine을 지우면 됩니다(백업: settings.json.usagetrail.bak). Pro/Max가 아니면 한도 %가 제공되지 않아 이 단계는 건너뛰어도 됩니다(요금제 크라우드 추정으로 대체).

4. 동기화 (과거 전체 백필)

node aipt.mjs sync

sync는 멱등적이라(날짜+에이전트+모델 업서트) 백필과 증분 동기화가 같은 명령입니다. 대시보드를 새로고침하면 사용량이 나타납니다. 요금제도 이때 자동 감지되어 저장됩니다.

5. 여러 기기에서 쓰기

기기마다 ~/.config/ai-price-tracker/device.json에 불투명 키(32자 16진수)가 자동 생성되어 사용량이 기기별로 정확히 합산됩니다. 토큰 파일(config.json)과 달리 다른 기기로 복사하지 마세요 — 복사하면 두 기기가 같은 키를 공유해 사용량이 한 기기 값으로 합쳐집니다.

node aipt.mjs device          # 이 기기 키(앞 6자)와 파일 경로 확인 — 이름(별칭)은 웹에서 붙입니다
node aipt.mjs device reset    # 기기 키 초기화(경고: 이전 이력과 갈라지며 되돌릴 수 없음)

컨테이너·CI 는 주의하세요 — ~/.config가 유지되지 않으면 실행마다 새 기기로 인식되어 전체 이력이 매번 다시 올라가고 총합이 실행 횟수만큼 부풀어 오릅니다. AIPT_DEVICE_ID 환경변수로 기기 키를 고정하거나(권장), ~/.config/ai-price-tracker를 볼륨으로 마운트하세요.

# 1) 컨테이너/CI 당 딱 한 번만 생성 (로컬에서 실행)
openssl rand -hex 16
# 2) 그 결과를 Secret/환경변수로 저장해 재사용 — 아래처럼 실행할 때마다 새로 생성하면 안 됨
export AIPT_DEVICE_ID=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d   # 예시 값 — 실제로는 1)에서 생성한 값을 쓰세요
node aipt.mjs sync

6. 자동 동기화 (재부팅 후에도 · 권장)

node aipt.mjs watch-install                 # 로그인 시 자동 시작 등록 (macOS)
node aipt.mjs watch-install --interval 600  # 간격 지정(초, 기본 300)
node aipt.mjs watch-uninstall               # 해제

watch-install은 macOS launchd에 등록해 로그인할 때마다 자동으로 동기화를 시작하고, 프로세스가 죽으면 되살립니다. 재부팅 후에도 끊기지 않습니다. 로그는 ~/.config/ai-price-tracker/watch.log. 상태는 launchctl list | grep com.usagetrail.sync로 확인합니다.

재부팅까지만 도는 일회성 백그라운드가 필요하면 node aipt.mjs sync --watch (종료 stop, 상태 status). 업로드 없이 미리 보려면 node aipt.mjs sync --dry-run. Linux 는 cron·systemd --user로 sync를 주기 실행하세요.

수집 방식 (기본 native)

기본은 native: 로컬 로그(~/.claude/projects)를 직접 파싱합니다. npx/네트워크가 필요 없어 오프라인·빠름이고, 비용까지 계산해 전송합니다(ccusage와 총비용 약 ±0.4% 일치). ccusage로 수집하려면:

node aipt.mjs sync --source ccusage

로컬 / QA 서버로 보낼 때

node aipt.mjs login <TOKEN> --url http://localhost:3810

기본 도메인이 아닌 곳으로 업로드할 때만 --url이 필요합니다.

개발자용 (레포에서 직접)

레포를 클론했다면 다운로드 없이 실행할 수 있습니다:

npm run cli -- login <API_TOKEN>
npm run cli -- sync

문의: 팀 관리자에게 초대·권한을 요청하세요. 토큰이 노출되면 API 토큰에서 폐기 후 재발급하면 됩니다.