<!-- canonical: https://docs.axelabs.ai/services/cli -->
<!-- source: content/services/cli.mdx -->

---
title: AXE CLI (axe)
description: 토큰 인증으로 모든 AXE 서비스를 쓰는 단일 CLI. MCP 커넥터 불요. 로그인 1회 → 전 서비스.
---

# 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](/ops/decisions)): `axe login` → Microsoft SSO 1회 → **Blueprint 가 발행한 플랫폼 토큰** → 전 서비스. 신원·스코프·취소는 [Blueprint](/architecture/platform-identity) 한 곳에서 관장.

> 근거/설계: [D-axe-cli-1](/ops/decisions) (CLI = 외부 표준 접근) · [/architecture/platform-identity](/architecture/platform-identity) (Blueprint = OIDC Provider).

## 에이전트에 붙여넣기 (copy-paste)

당신의 AI 에이전트(Claude Code `CLAUDE.md` · Codex `AGENTS.md` · Cursor rules · 또는 그냥 채팅창)에 **아래 블록을 그대로 복붙**하면, 그 에이전트는 즉시 AXE 전 서비스를 쓸 수 있다. (사람은 바로 아래 **빠른 시작** 블록 참고.)

```text
너는 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).
```

### 빠른 시작 (사람)

복붙 한 덩어리로 설치 확인 → 로그인 → 첫 호출:

```bash
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). 직접 받으려면:

```bash
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` 와 대등):

```powershell
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](https://www.python.org/downloads/) 또는 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 · 채팅창에 아래를 복붙:

```text
내 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 (기본 — 사람/대화형)

```bash
axe login
```
브라우저가 열리고 **Microsoft 로그인 1회** → 자동으로 토큰을 받아 **macOS Keychain** 에 저장한다. (내부: loopback PKCE → Blueprint `/oauth/authorize` → Entra → 토큰 교환.) 끝나면:

```bash
axe whoami
# {
#   "iss": "https://blueprint.axellc.com",   ← Blueprint 발행
#   "email": "you@axellc.com",
#   "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` 모델):

```bash
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](/architecture/platform-identity) Phase 3). 브라우저는 못 열지만 다른 기기로 코드 입력은 가능한 환경(예: 원격 SSH 셸)을 위한 흐름 — **아직 미구현**. 그때까지 헤드리스는 위의 `AXE_TOKEN` env / `axe login --token -` (stdin) 을 쓴다.

### 토큰 갱신 / 로그아웃

```bash
axe refresh        # 저장된 refresh 토큰으로 access 토큰 무중단 갱신
axe logout         # 저장 토큰 제거 (서버측 취소는 Blueprint 에서)
```

## 서비스 호출

```bash
axe <service> tools                          # 도구 목록
axe <service> call <tool> --args '<json>'    # 도구 실행
```

서비스: **`frame`** (회계) · **`hive`** (HR) · **`index`** (투자) · **`cortex`** (CRM) · **`matrix`** (인프라) · **`blueprint`** (플랫폼).

예시:

```bash
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:

```bash
# 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](/architecture/platform-identity) 중앙에서 관리한다. 토큰 유출 시: 짧은 exp(1h) + refresh 취소 + 스코프로 blast radius 제한. 운영자 `axe`(vault/deploy)와 고객 CLI(업무 명령)는 **스코프 분리** — 만능 바이너리를 고객에 주지 않는다.

## 문제 해결

`axe login` 은 됐는데 서비스 호출이 401/403 이면 → [/onboard/troubleshooting](/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` 대신 단계별로 (실행 정책 제약 환경):

```powershell
$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` 로 바꿔도 된다.