AXE CLI (axe)
셸을 가진 에이전트·사람·cron·CI 어디서나 AXE 플랫폼 서비스를 쓰는 단일 명령줄 도구. MCP 커넥터를 서비스마다 따로 등록할 필요 없이, 로그인 1회로 받은 토큰 하나로 frame·hive·index·cortex·matrix·blueprint 를 모두 호출한다.
- 에이전트 무관: Claude Code · Codex · Cursor · Gemini CLI · 사람 터미널 · cron · CI — 셸만 있으면 동작.
- 토큰 인증: 브라우저 SSO 1회 또는 헤드리스 토큰. 권한은 토큰 스코프가 결정(중앙 관장).
- 플랫폼 SSO (D-axe-idp-1):
axe login→ Microsoft SSO 1회 → Blueprint 가 발행한 플랫폼 토큰 → 전 서비스. 신원·스코프·취소는 Blueprint 한 곳에서 관장.
근거/설계: D-axe-cli-1 (CLI = 외부 표준 접근) · /architecture/platform-identity (Blueprint = OIDC Provider).
에이전트에 붙여넣기 (copy-paste)
당신의 AI 에이전트(Claude Code CLAUDE.md · Codex AGENTS.md · Cursor rules · 또는 그냥 채팅창)에 아래 블록을 그대로 복붙하면, 그 에이전트는 즉시 AXE 전 서비스를 쓸 수 있다. (사람은 바로 아래 빠른 시작 블록 참고.)
너는 AXE 플랫폼 CLI `axe` 를 쓸 수 있다 — 셸 명령 하나로 모든 AXE 서비스를 호출한다 (MCP 커넥터 불요).
위치: `axe` (PATH) 또는 `~/axe-cli/axe`.
없으면 설치: macOS/Linux = `curl -fsSL https://axe.axelabs.ai/cli -o ~/axe-cli/axe && chmod +x ~/axe-cli/axe` (PATH 에 추가) · Windows(PowerShell) = `irm https://axe.axelabs.ai/cli.ps1 | iex`.
인증은 1회만: `axe login` (브라우저 SSO). 브라우저 없는 환경이면 `AXE_TOKEN` env 로 토큰 주입.
확인: `axe whoami` → iss=blueprint.axellc.com, email, scope, exp 가 보이면 OK.
서비스 사용법 — 항상 (1) 도구 조회 후 (2) 호출:
axe <service> tools # 그 서비스의 도구 목록 (이름 + 설명)
axe <service> call <tool> --args '<json>' # 도구 1개 실행 (JSON 인자)
axe teams chats [검색어] [--limit N] # (편의 v0.1.4) Teams 채팅 목록 — chat_id 탐색
axe teams send <chat_id> --text "..." # (편의 v0.1.4) Teams 채팅에 AXE 봇으로 발송 (admin)
# --dry-run 미리보기 · --text - (stdin) · --html
# ↑ blueprint MCP send_teams_message/list_teams_chats 의 1급 래퍼 (verbose call 대체).
# v0.1.4 = axe.axelabs.ai/cli 서빙 LIVE (2026-06-06, docker-cp bridge; image bake = 다음 클린 리빌드 대기 = B-axe-cli-edge-bake). 전 사용자 auto-update 0.1.2 -> 0.1.4.
서비스:
frame = 회계/ERP (분개·재무제표·마감)
hive = HR/급여 (직원·휴가·명세서)
index = 투자 (딜·펀드·IRR·재무모델)
cortex = CRM/인맥 그래프
matrix = 인프라 모니터링
blueprint = 플랫폼 (신원·캘린더·Teams·메일)
규칙:
- 도구 이름과 인자 스키마는 *기억하지 말고* 매번 `axe <service> tools` 결과에서 가져와라.
- 순수 셸이라 조합이 그대로 된다: `axe frame tools | grep balance`, for-loop, `| jq` 파이프.
- 기본 엔드포인트는 https://axe.axelabs.ai. 운영 호스트 안에서 돌면 `--local` 로 저지연.
- 호출이 401/403 이면 먼저 `axe refresh`, 그래도 안 되면 `axe login` 을 다시 안내해라.
- 너는 만능 권한이 아니다 — 가능한 동작은 토큰 scope 가 정한다 (`axe whoami` 의 scope).빠른 시작 (사람)
복붙 한 덩어리로 설치 확인 → 로그인 → 첫 호출:
axe --help # 또는 ~/axe-cli/axe --help
axe login # 브라우저 SSO 1회 (→ Keychain)
axe whoami # 토큰 확인
axe frame tools | head # 첫 호출 (frame 도구 목록)설치 / 위치
CLI 는 각 테넌트가 자기 도메인에서 서빙한다 (per-tenant — 그 테넌트의 엔드포인트가 baked):
| 자원 | URL (AXE) | 용도 |
|---|---|---|
| CLI 본체 | https://axe.axelabs.ai/cli | 다운로드 + axe self-update 소스 |
| Windows 설치기 | https://axe.axelabs.ai/cli.ps1 | PowerShell 1-라인 설치 |
다른 테넌트는 https://<tenant>.axelabs.ai/cli · /cli.ps1 (예: realchoice.axelabs.ai/cli).
macOS / Linux
운영 머신엔 이미 ~/axe-cli/axe (stdlib Python 단일 파일, 의존성 0). 직접 받으려면:
mkdir -p ~/axe-cli && curl -fsSL https://axe.axelabs.ai/cli -o ~/axe-cli/axe && chmod +x ~/axe-cli/axe
alias axe="~/axe-cli/axe" # 셸 rc 에 추가
axe --versionWindows (PowerShell)
한 줄이면 다운로드 + axe 명령 등록 + PATH 까지 자동 (macOS alias 와 대등):
irm https://axe.axelabs.ai/cli.ps1 | iex설치 후 새 PowerShell 창에서 axe --version. 내부 동작: %USERPROFILE%\axe-cli\axe 다운로드 → axe.cmd shim 생성 → 사용자 PATH 등록. Python 3 필요 (py -3 또는 python 자동 감지 — 없으면 python.org 또는 MS Store 설치 후 재실행).
- 로그인:
axe login브라우저 SSO 는 Windows 에서도 동작(기본 브라우저 +127.0.0.1loopback). 브라우저가 안 열리면 출력된 URL 을 수동으로 열거나, 헤드리스는axe login --token "<TOKEN>"/$env:AXE_TOKEN="<TOKEN>". - 토큰 저장처: Keychain 이 없으므로
%USERPROFILE%\.axe-cli\token(현재 사용자 ACL 로 제한 — CLI 가icacls로 상속 차단). 우선순위는 동일:AXE_TOKENenv > 파일. irm | iex가 실행 정책에 막히면(Set-ExecutionPolicy불가 환경) 맨 아래 부록: Windows 수동 설치 의 단계별 스니펫을 쓴다.
AI 에이전트에게 시키기 — 직접 안 치고 싶으면 Claude Code · Codex · Cursor · 채팅창에 아래를 복붙:
내 Windows PowerShell 에 AXE 플랫폼 CLI 를 설치하고 동작까지 확인해줘.
참고: https://docs.axelabs.ai/services/cli (Windows 섹션).
1. PowerShell 에서: irm https://axe.axelabs.ai/cli.ps1 | iex
- "실행이 사용되지 않도록 설정" 오류면 먼저: Set-ExecutionPolicy -Scope Process Bypass -Force
- "Python 3 not found" 면 python.org 또는 MS Store 에서 Python 3 설치 후 재실행
2. 새 PowerShell 창을 열고 axe --version 으로 PATH 등록 확인
3. 로그인: axe login (브라우저 SSO. 안 열리면 출력된 URL 수동 오픈, 또는 $env:AXE_TOKEN = "<토큰>" )
4. 검증: axe whoami 그다음 axe frame tools
각 단계 결과를 확인하고, 막히면 멈춰서 무엇이 어떻게 틀렸는지 알려줘. 토큰 값은 절대 출력하지 마.로그인
1) 브라우저 SSO (기본 — 사람/대화형)
axe login브라우저가 열리고 Microsoft 로그인 1회 → 자동으로 토큰을 받아 macOS Keychain 에 저장한다. (내부: loopback PKCE → Blueprint /oauth/authorize → Entra → 토큰 교환.) 끝나면:
axe whoami
# {
# "iss": "https://blueprint.axellc.com", ← Blueprint 발행
# "email": "[email protected]",
# "scope": "openid profile email frame hive index cortex matrix blueprint",
# "aud": "https://axe.axelabs.ai", "exp": ...
# }2) 헤드리스 토큰 (Codex / CI / cron / 브라우저 없는 환경)
브라우저를 못 여는 환경은 토큰을 직접 준다 (gh auth login --with-token 모델):
axe login --token "<TOKEN>" # 키체인 저장
axe login --token - # stdin 으로 (echo 회피)
export AXE_TOKEN="<TOKEN>" # env 가 키체인보다 우선 (CI/샌드박스)토큰 해석 우선순위: AXE_TOKEN env > macOS Keychain > ~/.axe-cli/token (0600). AXE_TOKEN env override 가 헤드리스(CI·Codex·샌드박스)의 표준 경로 — 키체인 없이 동작하고 셸 세션에만 살아 디스크에 남지 않는다.
device-code grant (RFC 8628) 은 계획 단계 (
B-axe-cli-device-code, D-axe-idp-1 Phase 3). 브라우저는 못 열지만 다른 기기로 코드 입력은 가능한 환경(예: 원격 SSH 셸)을 위한 흐름 — 아직 미구현. 그때까지 헤드리스는 위의AXE_TOKENenv /axe login --token -(stdin) 을 쓴다.
토큰 갱신 / 로그아웃
axe refresh # 저장된 refresh 토큰으로 access 토큰 무중단 갱신
axe logout # 저장 토큰 제거 (서버측 취소는 Blueprint 에서)서비스 호출
axe <service> tools # 도구 목록
axe <service> call <tool> --args '<json>' # 도구 실행서비스: frame (회계) · hive (HR) · index (투자) · cortex (CRM) · matrix (인프라) · blueprint (플랫폼).
예시:
axe frame tools # frame 54 도구
axe frame call query_balance --args '{"entity":"axec","account":"1101"}'
axe hive call employee_search --args '{"query":"강"}'엔드포인트 선택
| 플래그 | 대상 | 용도 |
|---|---|---|
| (기본) | public https://axe.axelabs.ai/<svc>/mcp | 외부/원격 |
--local | 127.0.0.1 (호스트 내) | 운영 머신 로컬 (저지연) |
--endpoint <URL> | 임의 | 디버그 |
axe login --local 로 기본 모드를 로컬로 고정 가능. local 호출은 DNS-rebinding 가드 통과를 위해 public Host 헤더를 자동 첨부한다.
토큰에 뭐가 들었나
Blueprint 발행 플랫폼 토큰(RS256)은 iss=https://blueprint.axellc.com, email(→ 각 서비스가 entity 권한으로 매핑), aud=https://axe.axelabs.ai(전 서비스 공통), scope(서비스 grant), exp(1h, refresh 로 갱신). 각 서비스는 Blueprint JWKS(/.well-known/jwks.json)로 서명을 검증한다. axe whoami 로 언제든 확인.
에이전트에서 쓰기 (조합성)
CLI 는 syscall 층이라 셸 조합이 그대로 통한다 — 모델 왕복 없이 pipe·loop·jq:
# frame 모든 도구 이름만
axe frame tools | awk '{print $1}'
# 여러 entity 잔액을 한 번에
for e in axec axev; do axe frame call query_balance --args "{\"entity\":\"$e\",\"account\":\"1101\"}"; doneCodex·CI 에선 AXE_TOKEN env + 아웃바운드 HTTPS 허용만 있으면 동작 (브라우저 불요).
거버넌스
권한은 토큰 스코프가 결정하고, 발행·스코프·취소·감사는 Blueprint 중앙에서 관리한다. 토큰 유출 시: 짧은 exp(1h) + refresh 취소 + 스코프로 blast radius 제한. 운영자 axe(vault/deploy)와 고객 CLI(업무 명령)는 스코프 분리 — 만능 바이너리를 고객에 주지 않는다.
문제 해결
axe login 은 됐는데 서비스 호출이 401/403 이면 → /onboard/troubleshooting 의 “Blueprint 플랫폼 토큰” 섹션 (서비스가 BLUEPRINT_ISSUER 미설정 / aud 불일치 / email 미매핑 등). public 호출이 403 이면 CLI 가 구버전일 수 있음 — User-Agent 헤더가 있어야 Cloudflare 봇 차단을 통과한다(axe-cli 0880417+).
Windows 특이사항
irm | iex가 막힘 (스크립트 실행이 사용되지 않도록 설정): 현재 세션만 허용 후 재실행 —Set-ExecutionPolicy -Scope Process Bypass -Force; irm https://axe.axelabs.ai/cli.ps1 | iex. 또는 아래 수동 설치.axe명령 인식 안 됨: PATH 는 새 터미널부터 적용된다 — 새 PowerShell 창에서 재시도.python을 못 찾음:py -3또는python이 PATH 에 있어야 한다. (MS Store Python 은py런처가 없을 수 있어 설치기가python으로 폴백한다.)- self-update 거동: Windows 는
.cmdshim → python 구조라, 자동 업데이트 후os.execv대신 새 프로세스로 재실행한다(axe-cli0.1.1+). 토큰 파일은icacls로 현재 사용자에 한정. axe login이✓출력에서 크래시처럼 보임 (UnicodeEncodeError, cp949/cp932 콘솔): 토큰은 배너 출력 전에 저장되므로 인증은 이미 성공한 상태였다 —axe whoami로 확인. 0.1.2+ 에서 해결(CLI 가 stdout/stderr 를 UTF-8 로 reconfigure +cli.ps1shim 이set PYTHONUTF8=1). 구버전이면axe self-update한 번. 헤드리스/CI 는 애초에 브라우저 SSO 대신$env:AXE_TOKEN권장.
부록: Windows 수동 설치
irm | iex 대신 단계별로 (실행 정책 제약 환경):
$dir = "$env:USERPROFILE\axe-cli"
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest https://axe.axelabs.ai/cli -OutFile "$dir\axe" -UseBasicParsing -Headers @{'User-Agent'='axe-cli/setup'}
@"
@echo off
set PYTHONUTF8=1
python "%USERPROFILE%\axe-cli\axe" %*
"@ | Set-Content "$dir\axe.cmd" -Encoding ASCII
$p = [Environment]::GetEnvironmentVariable('Path','User')
if (($p -split ';') -notcontains $dir) { [Environment]::SetEnvironmentVariable('Path', "$p;$dir", 'User') }
# 새 PowerShell 창에서:
# axe --version
# axe login # 브라우저 SSO
# $env:AXE_TOKEN="<TOKEN>"; axe whoami; axe frame tools # 또는 헤드리스shim 의 python 은 본인 환경에 맞게 py -3 로 바꿔도 된다.