@apptrace/cli

IMQA 프론트엔드 관찰가능성(frontend observability) 데이터를 위한 AI CLI. apptrace 명령 하나로 두 가지를 한다.

• AI 를 호출하는 도구 — apptrace ask "<질문>" 으로 자연어 질문을 던지면, AI 가 IMQA 관찰가능성 도구를 호출해 실제 데이터를 보고 답한다.
• AI 에게 호출당하는 도구 — apptrace mcp serve 로 stdio MCP 서버를 띄우면, Claude Code / Claude Desktop / Cursor 같은 에이전트가 IMQA 관찰가능성 데이터를 도구로 쓸 수 있다.

AI 프로바이더는 Anthropic Claude 와 OpenAI 를 지원하며, baseURL 설정으로 엔터프라이즈 게이트웨이나 OpenAI 호환 엔드포인트로 돌릴 수 있다.

실행에는 Bun 이 필요하다. 배포 산출물은 bun 타깃으로 번들되며 #!/usr/bin/env bun 으로 실행된다.

설치

npm 전역 설치:

npm install -g @apptrace/cli
apptrace --help

모노레포 내부에서 직접 실행:

bun run packages/cli/src/index.ts --help

로그인

apptrace login 은 브라우저로 aiqops 포털(apptrace.live)을 열어 Keycloak 로그인을 거친 뒤, IMQA MCP 접근 토큰(PAT)을 발급받아 ~/.imqa/config.json 의 mcp.serviceToken 에 저장한다.

apptrace login                       # 브라우저 로그인 → 토큰 자동 저장
apptrace login --no-browser          # 브라우저 자동 실행 없이 URL 만 출력 (헤드리스)
apptrace login --portal https://...  # 포털 base URL override
apptrace logout                      # 저장된 토큰 삭제

흐름: CLI 가 로컬 루프백 서버를 띄우고 브라우저로 포털의 /cli-login 페이지를 연다. 포털에서 로그인·승인하면 90일짜리 읽기 전용 토큰이 발급되어 루프백으로 전달된다. MCP URL 만 따로 설정하면 된다.

apptrace config set mcp.url https://mcp.apptrace.live/mcp
apptrace login

설정

설정은 ~/.imqa/config.json 에 저장된다(0600 권한). 환경변수가 파일보다 우선한다. 토큰은 apptrace login 으로 받는 것을 권장하며, 아래처럼 수동 설정도 가능하다.

apptrace config set mcp.url https://mcp.apptrace.live/mcp
apptrace config set mcp.serviceToken <SERVICE_TOKEN>
apptrace config set providers.anthropic.apiKey <ANTHROPIC_API_KEY>
apptrace config set context.serviceNamespace 사랑ON
apptrace config show

설정 키

| 키 | 설명 | | --- | --- | | portal.url | aiqops 포털 base URL (apptrace login 대상, 기본 https://apptrace.live) | | provider | 기본 AI 프로바이더 (anthropic | openai) | | providers.<id>.apiKey | 프로바이더 API 키 | | providers.<id>.model | 모델명 (미지정 시 claude-sonnet-4-6 / gpt-4o) | | providers.<id>.baseURL | 게이트웨이/프록시 base URL | | mcp.url | IMQA MCP 엔드포인트 URL | | mcp.serviceToken | IMQA MCP 서비스 토큰 | | context.serviceNamespace | 기본 ServiceNamespace | | context.serviceName | 기본 Service 이름 | | context.serviceKey | 서비스 키 |

환경변수

IMQAX_PROVIDER, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, OPENAI_API_KEY, OPENAI_BASE_URL, IMQA_MCP_URL, IMQA_MCP_SERVICE_TOKEN, IMQA_PORTAL_URL, IMQA_SERVICE_NAMESPACE, IMQA_SERVICE_NAME, IMQA_SERVICE_KEY

사용법

자연어 질문

apptrace ask "최근 24시간 동안 가장 많이 난 에러 5개 알려줘"
apptrace ask "사랑ON 에서 오늘 FATAL 로그 있었어?" --namespace 사랑ON
apptrace ask "5xx 추세 요약해줘" --provider openai --max-iter 8

답변은 stdout 으로, 진행 로그와 메타데이터(반복 N회, 도구 호출 M회)는 stderr 로 출력된다.

MCP 서버

apptrace mcp serve

Claude Desktop / Claude Code 의 MCP 설정에 등록:

{
  "mcpServers": {
    "imqa": {
      "command": "apptrace",
      "args": ["mcp", "serve"]
    }
  }
}

노출되는 도구: list_service_namespaces, get_errors, query_logs.

명령

| 명령 | 설명 | | --- | --- | | apptrace login | 브라우저로 포털 로그인 → MCP 토큰 발급/저장 | | apptrace logout | 저장된 MCP 토큰 삭제 | | apptrace ask <질문> | 자연어로 관찰가능성 데이터에 질문 | | apptrace mcp serve | stdio MCP 서버 실행 | | apptrace config show | 현재 설정 출력 (자격증명 마스킹) | | apptrace config set <키> <값> | 설정 값 변경 | | apptrace config path | 설정 파일 경로 출력 |

개발

nx run apptrace-cli:typecheck
nx run apptrace-cli:test
nx run apptrace-cli:build

빌드 산출물은 dist/index.js 단일 파일이며, 워크스페이스 의존성(@imqa/imqax-mcp-client)은 번들에 인라인된다. npm 배포 시에는 @anthropic-ai/sdk, @modelcontextprotocol/sdk, zod 만 런타임 의존성으로 남는다.