Skip to Content

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.ps1PowerShell 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 --version

Windows (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.1 loopback). 브라우저가 안 열리면 출력된 URL 을 수동으로 열거나, 헤드리스는 axe login --token "<TOKEN>" / $env:AXE_TOKEN="<TOKEN>".
  • 토큰 저장처: Keychain 이 없으므로 %USERPROFILE%\.axe-cli\token (현재 사용자 ACL 로 제한 — CLI 가 icacls 로 상속 차단). 우선순위는 동일: AXE_TOKEN env > 파일.
  • 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_TOKEN env / 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외부/원격
--local127.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\"}"; done

Codex·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 는 .cmd shim → python 구조라, 자동 업데이트 후 os.execv 대신 새 프로세스로 재실행한다(axe-cli 0.1.1+). 토큰 파일은 icacls 로 현재 사용자에 한정.
  • axe login 출력에서 크래시처럼 보임 (UnicodeEncodeError, cp949/cp932 콘솔): 토큰은 배너 출력 전에 저장되므로 인증은 이미 성공한 상태였다 — axe whoami 로 확인. 0.1.2+ 에서 해결(CLI 가 stdout/stderr 를 UTF-8 로 reconfigure + cli.ps1 shim 이 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 로 바꿔도 된다.

Last updated on