alex — Alexandria CLI

AI 에이전트(및 사람)가 터미널에서 Alexandria 를 조작하기 위한 CLI. Front Backend REST API(/api) 를 호출하므로 인증·권한·UUIDv47 facade·비즈니스 로직을 그대로 따른다 (DB 직접 접근 없음).

설계 (AI 친화)

• 기본 출력은 JSON (stdout, 단일 객체/배열). --pretty 로 들여쓰기.
• 에러는 구조화 JSON (stderr): {"error":{"code","message","hint"}}. hint 가 다음 행동을 안내.
• Exit code: 0 성공 / 1 일반 / 2 사용법 / 3 인증 / 4 not found.
• 비대화형 기본: 프롬프트 없음(파괴적 명령만 TTY 확인). 파괴적 명령은 비-TTY 에서 --yes 필요.
• escape hatch: alex api <METHOD> <path> 로 CLI 가 감싸지 않은 엔드포인트도 직접 호출.

설치 / 환경(endpoint)

endpoint 는 빌드 시점에 baked 되고 런타임/CLI 플래그/env 로는 변경 불가 — AI 에이전트가 임의로 dev/prod 를 건드리지 못하게 하는 가드레일. alex --help 에 현재 박힌 endpoint 가 표시된다.

# 일반 사용자 — npm 발행본 (운영 endpoint baked)
npm i -g @twentyoz/alex-cli

# 로컬 개발 — 소스에서 빌드 (기본 local)
make install-cli                 # env=local — npm install + build + 글로벌 link
make install-cli env=dev         # dev 로 박아서 설치
make build-cli env=prod          # 빌드만, prod 로 박기
cd web/cli && ALEX_ENV=dev npm run dev -- --help

환경별 URL 은 .env 의 ALEX_API_BASE_{LOCAL,DEV,PROD} 에서 읽는다 (.env.template 참고). 배포 빌드는 ALEX_API_BASE_URL 직접 주입 가능(우선). local 만 미설정 시 localhost 폴백, dev/prod 는 미해결 시 빌드 실패(오발행 방지).

npm 발행

make release-cli                  # 현재 version 으로 발행 (운영 endpoint)
make release-cli version=patch    # version bump 후 발행

• 발행본은 항상 운영 endpoint baked — npm publish 는 ALEX_ENV=prod 일 때만 허용(prepublishOnly 가드).
• 발행 머신의 .env 에 ALEX_API_BASE_PROD 필요 (또는 ALEX_API_BASE_URL 주입). 사전 npm login (스코프 @twentyoz).
• 레지스트리는 public npmjs 기본(publishConfig.access=public). private/GitHub Packages 로 바꾸려면 publishConfig.registry 추가.

| 환경 | 기본 URL (.env.template) | |------|----------------------------| | local | http://localhost:30042/api | | dev | https://alexdria.twentyoz.dev/api | | prod | https://alexdria.com/api |

인증

| 항목 | 우선순위 | |------|----------| | 토큰 | --token / ALEX_TOKEN(access only, refresh 없음) > 저장 토큰(alex auth login, 401 시 자동 refresh) |

저장 위치: ${XDG_CONFIG_HOME:-~/.config}/alex/config.json (권한 0600). endpoint 는 baked 라 저장하지 않음.

로그인은 브라우저 위임만 지원한다(captcha·Google·이메일/비번 모두 브라우저에서). 비밀번호를 CLI 인자/env 로 직접 받지 않는다 — argv/ps 노출과 captcha 우회를 막기 위함. 헤드리스/CI 는 ALEX_TOKEN.

# 대화형 로그인 (브라우저 자동 오픈 → loopback 으로 토큰 수신)
alex auth login
alex auth whoami

# SSH/헤드리스: 브라우저를 띄울 수 없으면 코드 붙여넣기 (자동 감지되며, 강제하려면 --code)
alex auth login --code

# CI/에이전트(비대화형): 토큰 직접 주입 (refresh 없음)
ALEX_TOKEN=<access_jwt> alex auth whoami

워크플로 (Search → Fetch → Act)

alex rec ls --limit 10                 # 또는: alex rec search "분기 회의"
alex rec upload meeting.m4a --wait     # 완료까지 대기(진행은 stderr) 후 상세 JSON
alex rec transcript <id> --text        # 화자: 발화
alex rec summarize <id> --language ko  # AI 요약 재생성
alex rec chat <id> "핵심 결정사항만 정리해줘"

명령

| 명령 | 설명 | |------|------| | alex auth login\|logout\|whoami | 인증/토큰 | | alex rec ls [--cursor --limit --tag --all] | 목록 (alias: alex ls) | | alex rec search <query> [--limit --tag] | 전문검색 | | alex rec get <id> [--waveform] | 상세 (기본 waveform 생략, alias: alex get) | | alex rec status <id> | 경량 상태/진행률 (폴링용) | | alex rec upload <file> [--wait --skip-summary --template --timezone --force] | 업로드 (alias: alex upload) | | alex rec watch <id> | 진행률 SSE → JSON 라인 스트림 | | alex rec transcript <id> [--text] | 전사 결과 | | alex rec notes <id> [--ai] | 노트 (--ai 로 AI 요약만) | | alex rec summarize <id> [--language --template --data] | 요약 재생성 | | alex rec chat <id> <message...> [--thread --language --data] | AI 채팅 (alias: alex chat) | | alex rec retry <id> | 재시도 | | alex rec rm <id> [--yes] | 삭제 (DB+S3) | | alex templates / tags | 읽기 전용 보조 | | alex api <METHOD> <path> [--data <json\|@file> -q k=v ...] | escape hatch |

--data / api 예시

alex rec chat <id> --data '{"message":"요약","language":"en"}'
alex api POST /recs/<id>/split --data @body.json
alex api GET /recs -q limit=5 -q tag=<tagId>
alex api PATCH /recs/<id>/speakers --data '{"name_map":{"s1":"홍길동"}}'

긴 꼬리 엔드포인트(split, detect-boundaries, speakers 변경, contacts, shares, tier, note/template CRUD)는 alex api 로 호출한다.