CLI 사용 설명서

최근 업데이트 2026. 10. 06.

읽기 안내

소속 목차: 기능 센터. 검색 키워드: CLI, ae-cli, 명령줄, Coding Agent, Skill, 설치, 로그인, 권한 부여, Capability Gateway.

• Codex, Claude Code 등 Coding Agent에서 연동: Coding Agent.
• CLI로 할 수 있는 일 빠르게 알아보기: CLI 빠른 시작.
• 도구 프로토콜로 외부 서비스 연결: MCP.
• 재사용 가능한 작업 방법 축적: Skill.
• 주기적으로 실행할 작업 설정: 자동화.

노트

Agentic Engine CLI(명령명 ae-cli)는 Agentic Engine의 명령줄 클라이언트로, AI Agent와 사람의 조작에 안정적이고 구조화된 인터페이스를 제공합니다. 설치하고 권한을 부여하면 Codex, Claude Code, WorkBuddy 등 로컬 AI Agent가 사용자의 계정 권한 범위 안에서 데이터 조회, 대시보드 구성, 트래킹 관리, 운영 및 데이터 개발 작업의 후속 관리를 직접 수행할 수 있습니다. 사용자는 하고 싶은 일을 자연어로 분명히 말하기만 하면 됩니다.

작업 방식

자연어로 질문 → 로컬 AI Agent(Claude Code, Codex, WorkBuddy 등) → ae-cli → 내 Agentic Engine 프로젝트 → 검증 가능한 결과

CLI를 설치하면 관련 Agent Skills도 함께 설치됩니다. Skills는 AI Agent에게 어떤 명령이 있는지, 어떤 시나리오에서 어떤 명령을 쓰는지, 쓰기 작업 전에 무엇을 확인해야 하는지 알려 주므로 명령을 외울 필요가 없습니다.

• 권한 경계: CLI는 사용자의 계정과 프로젝트 권한을 그대로 따르며, 그 이상의 데이터를 가져오지 않습니다. 최종 권한은 서버 측에서 검증합니다.
• 자격 증명: Agentic Engine 주소별로 나누어 로컬에 암호화하여 저장하며, 환경을 전환해도 다른 환경의 자격 증명을 재사용하지 않습니다.
• 쓰기 작업: 대시보드 생성, 유저 그룹 생성, 푸시처럼 현재 상태를 바꾸는 작업은 먼저 AI에게 방안을 받고, 사용자가 확인한 뒤에 실행합니다.

CLI와 MCP의 역할 분담: Agent가 Agentic Engine의 내장 비즈니스 기능(분석, 운영, 트래킹, 데이터 개발, 지식 베이스 등)을 사용하게 하려면 CLI를 우선 사용합니다. MCP는 Agent를 외부 도구와 비즈니스 서비스에 연결하는 데 사용하며, 자세한 내용은 MCP를 참고하십시오.

시작 전 준비

• Agentic Engine이 6.x 버전으로 업그레이드되어 있어야 합니다.
• 계정에 대상 프로젝트 접근 권한이 있어야 합니다.
• Agentic Engine 주소를 알고 있어야 합니다. 평소 Agentic Engine 웹 페이지를 여는 주소로, 관리자가 제공합니다.
• 로컬에 Node.js 20 이상이 설치되어 있고 npm 저장소에 접근할 수 있어야 합니다. Skills를 처음 설치할 때는 GitHub에도 접근할 수 있어야 합니다.
• 로컬 네트워크에서 Agentic Engine 주소에 접근할 수 있어야 합니다.

설치 및 로그인

방법 1: AI Agent에게 설치 맡기기(권장)

터미널을 조작할 수 있는 AI Agent(예: Codex, Claude Code, WorkBuddy)에게 아래 문장을 보내고, 문장 속 주소를 사용자의 Agentic Engine 주소로 바꿉니다:

https://raw.githubusercontent.com/ThinkingAIAgenticEngine/ae-cli/main/cli-installation-guide.md 문서를 읽고 안내에 따라 Agentic Engine CLI(ae-cli)를 설치하거나 업그레이드해 주세요. 제 Agentic Engine 주소는 https://your-ae-host.example.com 입니다. ae-cli와 관련 Skills만 설치하고 현재 프로젝트는 수정하지 마세요. 로그인 권한 부여가 필요하거나 관리자 권한이 필요하면 멈추고 알려 주세요.

AI Agent는 다음 단계를 순서대로 수행합니다:

1. Node.js와 npm 버전을 확인합니다. 버전이 부족하면 nvm, fnm, Volta 같은 버전 관리 도구로 사용자 디렉터리에 설치하며, sudo npm install -g는 사용하지 않습니다.
2. ae-cli와 관련 Skills를 설치합니다.
3. 로그인을 시작하고 권한 부여 링크를 사용자에게 보냅니다. 사용자가 브라우저에서 권한 부여를 마치면 이어서 로그인을 완료합니다.
4. ae-cli update를 실행하여 현재 환경에서 요구하는 CLI와 Skills 버전을 설치합니다.
5. Node.js 버전, CLI 버전, Agentic Engine 주소, 로그인 상태, Skills 동기화 결과를 보고합니다.

설치가 끝나면 AI Agent를 닫았다가 다시 열거나 새 작업을 시작하여 새로 설치한 Skills를 로드하게 합니다.

방법 2: 수동 설치

먼저 Node.js 버전이 20 이상인지 확인합니다:

node --version

버전이 너무 낮으면 Skills 설치 시 EBADENGINE 또는 styleText 관련 오류가 발생할 수 있으므로 먼저 Node.js를 업그레이드하거나 전환하십시오. 그런 다음 CLI와 관련 Skills를 설치하고 버전을 확인합니다:

npm install -g @thinkingai/ae-cli
npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
ae-cli --version

로컬에서 다른 도구가 이미 ae-cli라는 명령명을 사용하고 있다면 먼저 확인한 뒤 교체하십시오.

로그인 및 권한 부여

ae-cli auth login --host https://your-ae-host.example.com
ae-cli auth status --host https://your-ae-host.example.com

로그인은 디바이스 코드 방식을 사용합니다. 브라우저에서 권한 부여 페이지가 열리면 페이지의 인증 코드가 터미널에 표시된 코드와 같은지 확인한 뒤 승인을 클릭합니다. 터미널로 돌아가 로그인 상태를 확인하고, authenticated가 true이면 로그인에 성공한 것입니다.

• 현재 환경에서 브라우저를 열 수 없으면 로그인 명령 뒤에 --no-browser를 추가합니다.
• AI Agent가 대신 로그인할 때는 두 단계로 나눌 수 있습니다. 먼저 --no-wait를 추가해 로그인 명령을 실행하여 권한 부여 링크를 받습니다. 사용자가 권한 부여를 마치면 반환된 디바이스 코드와 함께 --device-code를 추가해 한 번 더 실행합니다. 디바이스 코드가 만료되면 첫 번째 단계부터 다시 실행합니다.
• Agentic Engine의 외부 액세스 관리에서 CLI Token을 복사한 뒤 ae-cli auth set-token --host <주소>로 가져올 수도 있습니다. 입력 내용은 화면에 표시되지 않으며, 명령 출력에도 Token이 포함되지 않습니다.

환경에서 요구하는 버전으로 동기화

Agentic Engine 환경마다 정해진 CLI 버전이 있습니다. 설치하거나 업그레이드한 뒤 다음을 실행합니다:

ae-cli update --host https://your-ae-host.example.com
ae-cli --version

ae-cli update는 현재 환경의 요구에 따라 해당 버전의 CLI와 Skills를 설치하며, npm의 최신 버전에 의존하지 않습니다. 따라서 업그레이드할 때 npm으로 latest를 바로 설치하지 마십시오. 어떤 버전이 설치될지 먼저 확인하려면 --dry-run을 추가합니다.

6.0.37 및 6.1.9 유지보수 라인부터는 일반 명령이 버전 불일치를 발견하면 자동으로 동기화합니다. 동기화에 성공하면 AE_CLI_VERSION_SYNCED가 반환되며, 원래 명령을 다시 실행하면 됩니다.

엄선된 시나리오 Skill 설치

ThinkingAI는 다년간의 서비스 경험을 시나리오 Skill로 정리했으며, LTV 분석, 이상 진단 등 자주 쓰는 시나리오를 다룹니다. AI에게 바로 설치를 맡길 수 있습니다:

다음을 설치해 주세요: https://github.com/ThinkingAIAgenticEngine/scenario-skills

터미널에서 비즈니스 카테고리별로 대화형 설치를 진행할 수도 있습니다:

npx skills@latest add ThinkingAIAgenticEngine/scenario-skills

준비 상태 확인

AI에게 명확하고 위험이 낮은 질문을 합니다:

현재 제가 접근할 수 있는 프로젝트 목록을 조회하고 프로젝트 이름과 프로젝트 ID만 반환해 주세요. 지금은 보기만 하고 어떤 내용도 수정하지 마세요.

AI가 Agentic Engine의 기능을 인식하거나, 권한 부여를 안내하거나, 프로젝트 목록을 반환하면 연결이 정상입니다. AI가 질문을 일반 채팅으로 처리한다면 먼저 CLI와 Skills가 설치되었는지, 현재 AI Agent가 Skills를 다시 로드했는지 확인하십시오.

5분 만에 첫 조회 실행하기

명령을 배울 필요가 없습니다. AI에게 다음 문장을 보냅니다:

최근 7일 동안의 일별 활성 유저 수를 조회해서 일별 추세로 보여 주세요. 먼저 어떤 이벤트, 기간, 중복 제거 규칙을 사용했는지 알려 주세요.

결과를 받으면 다음 세 가지만 확인합니다:

1. 이벤트를 올바르게 선택했나요?
2. 기간이 맞나요?
3. 집계 대상이 유저 수인가요, 횟수인가요?

자주 쓰는 시나리오

아래 프롬프트는 모두 그대로 복사해 쓸 수 있습니다. 괄호 안의 자리 표시 내용을 프로젝트의 실제 대상으로 바꾼 뒤 AI에게 보내십시오. "읽기 전용"으로 표시된 것은 조회만 하고 수정하지 않습니다. "확인 후 실행"으로 표시된 것은 AI가 먼저 방안을 제시하고, 사용자가 확인한 뒤에야 생성하거나 수정합니다.

핵심 지표 조회(읽기 전용)

특정 기간의 핵심 게임 플레이를 먼저 전체적으로 파악한 뒤 어디를 깊이 파고들지 정할 때 적합합니다.

최근 7일 동안 (핵심 행동)의 전체 성과를 보여 주세요. 매일 몇 명이 트리거했는지, 총 몇 번 트리거됐는지 일별 추세로 나열해 주세요.

확인: 어느 프로젝트인지, AI가 어떤 이벤트를 선택했는지 확인합니다. 잘못 선택했다면 바로 정정하면 되며, AI가 다시 실행합니다. 다음에 물어볼 만한 질문: "어제 트리거 유저 수를 채널별로 나눠 주세요."

결과가 이상할 때: 큰 질문을 작게 나눕니다. 먼저 "최근 7일 동안 매일 로그인한 유저 수"를 묻고, 이벤트를 사용할 수 있는지 확인한 뒤 지표를 추가합니다.

퍼널로 이탈 지점 찾기(읽기 전용)

최근 7일 동안 (시작 이벤트)에서 (종료 이벤트)까지의 전환 퍼널을 보여 주세요:
(단계1) → (단계2) → (단계3) → (단계4),
1일 전환 윈도우 기준으로 단계별 유저 수와 전환율을 집계하고, 어느 단계에서 이탈이 가장 큰지 알려 주세요.

확인: 퍼널의 각 단계에 대응하는 이벤트(AI가 나열하고 확인을 기다립니다)와 전환 윈도우(일반적으로 1일, 캠페인성 퍼널은 3일까지 늘릴 수 있음)를 확인합니다. 어떤 단계의 유저 수가 0이면 먼저 이벤트를 잘못 선택했거나 해당 기간에 데이터가 없는 것은 아닌지 의심해 보십시오.

자주 쓰는 분석 모델 요약(읽기 전용)

분석 유형	답하는 질문	복사할 수 있는 프롬프트
이벤트 분석	특정 행동의 발생 횟수와 추세	최근 7일 동안 (이벤트)의 일별 트리거 유저 수와 횟수를 조회해서 일별 추세로 보여 주세요.
퍼널 분석	가장 많이 이탈하는 단계	(단계A→단계B→단계C)로 퍼널을 만들고, 1일 윈도우로 이탈이 가장 큰 단계를 찾아 주세요.
리텐션 분석	유저가 계속 돌아오는지	최근 7일 동안 (회원가입) 유저의 익일 잔존율을 집계해 주세요. 복귀 이벤트는 (로그인)을 사용해 주세요.
분포 분석	유저나 수치가 어디에 몰려 있는지	최근 7일 동안 (충전 금액)의 유저 분포를 집계해서 구간별로 보여 주세요.

대시보드로 저장(확인 후 실행)

방금 만든 (퍼널 분석)과 (이벤트 분석)으로 대시보드를 하나 구성해 주세요.
먼저 대시보드 이름, 포함할 리포트, 각 리포트의 산출 기준을 나열해 주시고, 제가 확인한 뒤에 생성해 주세요.

생성에 성공하면 AI가 대시보드 링크를 반환하며, 링크를 열면 Agentic Engine의 실제 대시보드가 표시됩니다. 계정에 리포트와 대시보드를 생성할 권한이 있어야 합니다.

연속 질문으로 원인 찾기(읽기 전용)

실제 분석은 보통 여러 차례 이어지는 질문이 필요합니다. 매번 차원을 하나만 바꾸고, 이전 차례의 "검증 필요" 항목을 다음 차례의 질문으로 삼습니다. "매출 성장 정체"를 예로 들면 다음과 같습니다:

1. 전체 현황 보기: "최근 14일 동안의 일별 결제 유저 수와 로그인 유저 수를 일별 추세로 보여 주고, 결제율이 대략 어느 수준인지 알려 주세요."
2. 채널별로 나누기: "최근 7일 동안의 결제 유저 수와 결제 금액을 유입 채널별로 나누고, 채널별 인당 결제 금액을 보여 주세요."
3. 신규/기존으로 나누기: "'첫 결제 여부'로 최근 7일 동안의 결제를 나누어, 첫 구매와 재구매가 각각 유저 수와 금액에서 얼마를 차지하는지 보여 주세요."
4. 금액별 계층화: "최근 7일 동안의 결제 유저를 누적 결제 금액별로 계층을 나누고(0–30, 30–98, 98–328, 328–648, 648 이상), 계층별 유저 비율을 보여 준 다음 결제 금액이 가장 높은 패키지를 나열해 주세요."

분석이 끝나면 AI에게 사실, 판단, 권장 조치를 구분하여 보고서로 작성하게 합니다:

방금 한 분석을 보고서로 정리해 주세요. 구성은 다음과 같이 고정해 주세요:
결론 요약, 데이터 산출 기준, 핵심 사실, 원인 판단, 검증 필요 항목, 권장 조치.
사실과 판단은 반드시 나누어 쓰고, 추측한 내용은 검증 필요로 표시하며 결론으로 쓰지 마세요.

데이터 리소스 점검 및 거버넌스

데이터 리소스의 시맨틱 품질이 AI 데이터 조회 수준의 상한을 결정합니다. 이벤트 이름이 뒤죽박죽이거나 속성에 주석이 없거나 산출 기준이 통일되지 않으면 AI는 추측할 수밖에 없습니다. 먼저 점검하고 나서 분석하는 것을 권장합니다.

시나리오	복사할 수 있는 프롬프트	읽기/쓰기
리소스 점검	현재 프로젝트의 트래킹 리소스를 점검해 주세요. 이벤트와 속성의 총수를 집계하고, 표시 이름이나 주석이 없는 이벤트와 속성, 이름 규칙에 맞지 않는 이벤트, 최근 90일 동안 데이터가 전송되지 않은 이벤트를 찾아 주세요. 먼저 점검 범위, 판정 규칙, 분류 목록을 출력하고, 어떤 리소스도 수정하지 마세요.	읽기 전용
시맨틱 정보 보완	방금 점검한 결과를 바탕으로 표시 이름이나 주석이 없는 이벤트와 속성에 대한 보완 제안을 생성해 주세요. 원래 필드 이름, 제안 표시 이름, 제안 주석, 수정 이유를 출력해 주세요. 제안 표만 주시고, 제가 검토한 뒤에 실행해 주세요.	확인 후 실행
데이터 품질 자체 점검	최근 7일 동안의 데이터 품질을 점검해 주세요. 핵심 이벤트의 전송량이 갑자기 0으로 떨어지거나 급증하지 않았는지, 주요 속성의 결측률과 비정상 열거형 값, 연결이 끊겼거나 오랫동안 데이터가 없는 리소스를 확인해 주세요. 현상, 가능한 원인, 사람이 확인해야 할 근거를 출력하고, 어떤 리소스도 수정하지 마세요.	읽기 전용

"데이터 없음"이 "쓸모없음"을 뜻하지는 않습니다. 주기적인 캠페인의 이벤트는 평소에 전송되지 않는 것이 정상이므로, 정리하기 전에 비즈니스 담당자와 먼저 확인하십시오.

트래킹 방안 설계 및 트래킹 코드 생성

비즈니스 흐름을 분명히 설명해야 AI가 실제로 적용할 수 있는 방안을 제시합니다. "트래킹을 설계해 주세요"라고 한마디만 하지 말고, 전체 유저 경로와 가장 중요하게 보는 지표를 알려 주십시오:

퀘스트 모듈의 트래킹 방안을 생성해 주세요.
비즈니스 목표: 퀘스트 단계에서 플레이어의 완료 현황과 이탈 분포를 파악하고, 막히는 퀘스트와 보상이 잔존에 미치는 영향을 찾습니다.
플레이어 행동 경로: 퀘스트 목록 열기 → 퀘스트 수락 → 퀘스트 진행 → 완료 → 보상 수령 → 나가기.
판정 기준: 완료 = 퀘스트 목표 달성이며, 보상 수령과는 다릅니다.
필요한 차원: 퀘스트 유형, 완료 소요 시간, 보상 유형, 완료 후 다음 행동; 플레이어 레벨, 계정 유형.

AI는 검토할 수 있는 방안 초안을 출력합니다. 초안에는 이벤트 이름, 표시 이름, 트리거 시점, 속성, 속성 타입, 예시 값, 검수 방법이 포함되며, 프로젝트에 이미 있는 공통 속성을 우선 재사용합니다. 방안 검토를 통과하면 이어서 코드를 생성할 수 있습니다:

트래킹 방안을 바탕으로 (Android / iOS / Web / 서버 측) 트래킹 코드를 생성해 주세요.

처음 생성할 때는 코드 스니펫 파일로 출력하고 사람이 검토한 뒤 병합하는 것을 권장합니다. 구체적인 API 파라미터는 해당 플랫폼의 SDK 문서를 기준으로 합니다.

분석부터 운영까지 연결하기

운영 모듈이 활성화되어 있어야 합니다. 푸시 채널은 먼저 Agentic Engine에서 설정하고 활성화해야 하며, 유저 그룹 조건에서 참조하는 이벤트와 속성은 이미 존재해야 합니다.

단계	복사할 수 있는 프롬프트	읽기/쓰기
운영 제안	방금 분석한 결론을 바탕으로 운영 제안을 생성해 주세요. "목표 타겟, 트리거 조건, 권장 조치, 예상 관찰 지표, 위험 및 제외 조건" 형식으로 출력해 주세요. 먼저 방안만 주시고, 유저 그룹이나 도달 작업은 생성하지 마세요.	읽기 전용
플로우 캔버스	(목표 타겟) 케어를 플로우 캔버스로 만들어 주세요. 먼저 그룹 정의, 트리거 조건, 대기 조건, 도달 채널, 빈도 제어 규칙, 종료 조건을 담은 초안을 나열해 주시고, 제가 확인한 뒤에 생성해 주세요.	확인 후 실행
성과 분석	(캔버스 이름)의 최근 7일 동안 실행 성과를 보여 주세요. 진입 유저 수, 도달 유저 수, 전환 유저 수, 노드별 종료 사유를 보여 주고, 지표마다 산출 기준을 설명해 주세요.	읽기 전용
성과 대시보드	이 캔버스의 실행 성과로 대시보드를 구성해 주세요. 목표 지표, 과정 지표, 계층 차원, 시간 필터를 포함해 주세요. 먼저 설정 초안을 주시고, 제가 확인한 뒤에 생성해 주세요.	확인 후 실행

시스템 간 연동 및 예약 작업

팁

시스템 간 연동을 하려면 먼저 AI Agent에 해당 외부 도구의 CLI나 MCP(예: Feishu는 lark-cli)를 설치해야 합니다. 그렇지 않으면 아래 프롬프트는 바로 실패합니다. 메시지 발송, 문서 생성처럼 외부로 나가는 작업은 모두 초안을 먼저 확인한 뒤 확정하십시오.

시나리오	복사할 수 있는 프롬프트
멀티 소스 데이터 통합	Agentic Engine의 결제 데이터와 (Feishu 시트)의 캠페인 데이터를 일별로 맞춘 리포트 하나로 통합해 주세요. 먼저 양쪽의 데이터 세분화 수준, 날짜 필드, 지표 산출 기준, 결측값 처리 규칙을 나열해 주시고, 제가 확인한 뒤에 병합해 주세요. 외부 파일은 수정하지 마세요.
업무 그룹 채팅으로 일일 보고서 발송	오늘의 활성 데이터를 조회해서 일일 보고서로 정리한 뒤 우리 업무 그룹 채팅에 보내 주세요. 일일 보고서에는 핵심 지표, 전기 대비 변화, 비정상 항목, 원본 분석 링크를 포함해 주세요. 먼저 초안을 만들어 보여 주시고, 제가 확인한 뒤에 보내 주세요.
주간 보고서를 온라인 문서로 생성	이번 주 데이터를 주간 보고서로 정리해서 Feishu 문서로 생성해 주세요. 구성은 지표 개요, 일별 추이, 변화 해석, 운영 조치 회고, 다음 주 할 일로 해 주세요. 먼저 초안을 만들고, 제가 확인한 뒤에 생성해 주세요.
예약 모니터링	자동화 작업을 하나 만들어 주세요. 버전 출시 후 30분마다 (프로젝트)의 핵심 지표(지표1, 지표2)를 조회하고 모니터링 카드로 정리해서 (Feishu 그룹 채팅)에 보내 주세요. 어떤 지표가 직전 7일 평균보다 10% 넘게 떨어지면 메시지에서 빨간색으로 강조해 알려 주세요. 먼저 실행 계획, 조회 기준, 푸시 형식을 나열해 주시고, 제가 확인한 뒤에 활성화해 주세요.

예약 작업은 먼저 수동으로 한 번 실행해 형식과 산출 기준에 문제가 없는지 확인한 뒤 활성화하십시오. 모니터링 작업은 30분 간격부터 시작하고, 일일 보고서는 하루 한 번이면 충분합니다. Agentic Engine에서 주기 작업을 설정하는 방법은 자동화를 참고하십시오.

분석 리소스 생성 및 재사용(확인 후 실행)

리소스	적합한 문제	생성 전 확인 사항
가상 속성	여러 원본 필드를 조합해 분석 차원 만들기	수식, 빈 값 처리, 영향 범위
유저 태그	안정적인 유저 분류 규칙 고정	계산 기간, 데이터 소스, 업데이트 주기
유저 코호트	분석하거나 운영할 유저 그룹 선택	진입 조건, 제외 조건, 유효 기간
리포트 및 대시보드	자주 보는 지표의 조회 방식 고정	지표 정의, 필터 조건, 접근 권한
프로젝트 간 재사용	공통 분석 구조를 다른 프로젝트로 이전	이벤트 매핑, 속성 매핑, 산출 기준 차이

(목표)를 위한 (가상 속성 / 태그 / 코호트 / 대시보드) 초안을 설계해 주세요.
먼저 의존하는 이벤트와 속성, 계산 또는 필터 로직, 업데이트 방식, 권한, 이전 위험을 나열해 주세요.
바로 생성하지 말고 제가 확인할 때까지 기다려 주세요.

프로젝트가 많을 때는 일괄 작업으로 시간을 가장 많이 아낄 수 있습니다. 예: "버전 모니터링 대시보드의 구조대로 프로젝트 A, B, C에 각각 하나씩 만들고, 다 만든 뒤 차이 항목을 나열해 주세요."

데이터 개발 플랫폼

데이터 개발 플랫폼이 활성화되어 있어야 합니다.

시나리오	복사할 수 있는 프롬프트
데이터베이스 테이블 및 작업 플로우 조회	현재 환경에서 접근할 수 있는 데이터베이스, 테이블, 작업 플로우를 나열하고 최근 업데이트 시간과 상태별로 정리해 주세요.
데이터 추출 및 디버깅	(비즈니스 질문)을 바탕으로 조회 방안과 SQL 초안을 생성해 주세요. 먼저 데이터 테이블, 조인 조건, 기간, 검증 방법을 설명하고, 쓰기 작업은 실행하지 마세요.
작업 플로우 구성	(비즈니스 도메인)을 위한 작업 플로우를 하나 설계해 주세요. 노드 구성, 스케줄 주기, 배포 계획을 나열하고, 바로 생성하지는 마세요.
Wide 테이블 가공	(이벤트 테이블)을 (Wide 테이블)로 가공해 주세요. 먼저 필드 목록, 집계 세분화 수준, 파티션 전략, 증분 업데이트 로직을 주시고, 제가 확인한 뒤에 테이블과 작업 플로우를 만들어 주세요.
실행 장애 해결	최근 (N)일 동안 실패한 인스턴스를 집계해서 작업 플로우와 실패 원인별로 분류하고, 수정 제안을 주세요.

더 많은 시나리오

• 로컬 데이터 연동: "이 (로컬 파일 경로)의 데이터를 Agentic Engine에 연동해 주세요. 먼저 파일 구조를 식별하고 필드 매핑과 타입을 나열해 주시고, 제가 확인한 뒤에 가져오기를 실행해 주세요."
• 커뮤니티 인사이트(옴니 인사이트 활성화 필요): "최근 일주일 동안 커뮤니티에서 (새 버전)에 관해 나온 논의를 정리하고, 인기 토픽, 긍정/부정 피드백, 우선 주의해야 할 위험을 요약해 주세요."
• 지식 베이스: "(지식 베이스 이름)에서 (주제)에 관한 페이지를 찾아 원문을 읽은 뒤 (질문)에 답하고, 출처 페이지를 첨부해 주세요."
• 플랫폼 관리(관리자 권한 필요): "시스템에 설정된 채널과 최근 30일 사용량 요약을 나열해 주세요. 읽기만 하고 수정하지 마세요."

CLI의 기능을 일일이 나열할 수는 없습니다. 요구 사항을 AI에게 바로 알려 주면 실행할 수 있는지, 어떤 설정이 더 필요한지 AI가 판단합니다.

결과 검증

어떤 숫자를 받든 먼저 네 가지를 물어보십시오. 어떤 이벤트를 썼나요? 지표 정의는 무엇인가요? 기간은 언제인가요? 필터 조건은 무엇인가요? 산출 기준이 맞지 않으면 그 자리에서 바로잡고 AI에게 다시 실행하게 합니다. 조회한 데이터와 대시보드가 맞지 않으면 AI에게 조회 조건을 하나씩 나열하게 하고, 대시보드에 있는 리포트의 설정과 항목별로 비교합니다.

계층	의미	예시
사실	데이터로 바로 재현 가능	"최근 7일 결제 전환율 30.46%."
판단	사실에 대한 해석	"이탈이 상점에서 충전 시작으로 넘어가는 단계에 몰려 있으며, 가격 노출과 관련이 있을 수 있습니다."
검증 필요	현재 데이터로는 확인하기에 부족함	"상점 노출 트래킹과 함께 검증해야 합니다."

AI가 멈추고 "이 단어는 어느 것을 가리키나요?"라고 묻는 것은 오류가 아닙니다. 한 단어가 여러 지표나 이벤트에 동시에 해당하면 AI는 산출 기준의 선택을 사용자에게 맡깁니다. 같은 모호함이 반복된다면 기본 산출 기준을 Skill이나 지식 베이스에 정리해 두십시오.

명령 빠른 참조

일상적으로 사용할 때는 명령을 외울 필요가 없으며, AI Agent가 Skills를 통해 알맞은 명령을 찾습니다. 문제를 해결하거나 스크립트를 작성할 때는 다음과 같이 도움말을 볼 수 있으며, 하위 명령에도 계속 --help를 붙일 수 있습니다:

ae-cli --help
ae-cli analysis --help
ae-cli project member --help

카테고리	루트 명령	용도
분석 및 프로젝트	analysis、analysis-meta、analysis-governance、project、metadata、personal-semantic-preference、project-semantic	리포트, 대시보드, 애드혹 분석, 알림, 태그 및 코호트; 이벤트 및 속성 카탈로그, 지표 및 트래킹 거버넌스; 데이터 리소스 검색 및 계보; 프로젝트, 멤버, 역할 및 권한; 데이터 테이블 및 차원 테이블 바인딩; 개인 시맨틱 선호; 프로젝트 리소스 패키지 내보내기
데이터 및 트래킹	tracking、data-integration	트래킹 방안, SDK 예시, 수집 진단 및 코드 생성; 로컬 CSV, JSON, Excel 데이터의 검사, 변환 및 업로드
커뮤니티 인사이트	community	커뮤니티 게시물, 댓글, 토픽, 감성, 라이브 및 보고서
운영·발송	engage-flow、engage-task、engage-setting、engage-scene、engage-activity、engage-workbench、engage-query	운영 프로세스, 작업 및 도달 콘텐츠, 채널 및 타겟 설정, 시나리오 및 전략, 캠페인 및 특집, 워크벤치 및 할 일, 운영 조회 및 비동기 내보내기
데이터 개발 플랫폼	dataops_repo、dataops_datatable、dataops_flow、dataops_ide、dataops_integration、dataops_operations	데이터 웨어하우스 및 데이터 소스, 테이블 및 뷰, 개발 프로세스 및 스케줄링, IDE 조회, 데이터 연동, 운영 관리 및 알림
Agent 플랫폼	kb、agent、context、memory、team、system	지식 베이스 및 Q&A; Agent, 자동화, 모델, MCP, Skills 및 첨부 파일; 현재 페이지 컨텍스트; 사용자 메모리; Agent Team; 멤버, 샌드박스, 사용량, 할당량, 채널 등 시스템 관리
범용 도구	capability、auth、config、sync、model、update	기능 탐색 및 범용 호출; 로그인 및 계정; 환경 관리; Skills 및 MCP 동기화; 샌드박스 모델 전환; 환경에서 요구하는 버전으로 동기화

Capability Gateway

전용 명령이 없는 롱테일 기능은 Capability Gateway로 동적으로 찾아 호출합니다:

ae-cli capability list --domain analysis
ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'

--input은 인라인 JSON, JSON 파일 경로 또는 앞에 @를 붙인 파일 경로를 지원하며, - 인수로 표준 입력에서 읽을 수도 있습니다. dry-run에는 이미 파라미터 검증이 포함되어 있고 위험 등급도 표시되므로, 문제가 없는지 확인한 뒤 run을 실행합니다.

출력 형식

명령은 기본적으로 통일된 JSON 구조(ok, data, _notice)로 출력하므로 AI Agent가 읽기 쉽습니다:

• --format table: 지원하는 목록 명령의 결과를 표로 표시하여 사람이 보기 쉽게 합니다.
• --jq <표현식>: 비즈니스 결과를 먼저 필터링한 뒤 출력합니다.
• --dry-run: 미리보기만 하고 실행하지 않습니다.
• --yes: 고위험 쓰기 작업의 대화형 확인을 건너뜁니다. 영향 범위를 확인한 뒤에만 사용하십시오.

다중 환경 및 다중 계정

자격 증명은 Agentic Engine 주소별로 나누어 저장됩니다. 테스트 환경과 프로덕션 환경을 함께 사용할 때는 config로 관리합니다:

ae-cli config list
ae-cli config add https://host-b.example.com --label staging --use
ae-cli config use staging
ae-cli config current

같은 환경에서 여러 계정이 필요하면 로그인 명령에 --add를 추가한 뒤, ae-cli auth list로 확인하고 ae-cli auth use --account <계정>로 전환합니다. ae-cli auth logout은 현재 계정에서 로그아웃합니다. 터미널에서 ae-cli config 또는 ae-cli auth를 직접 실행하면 대화형 선택기가 열립니다.

보안 및 권한

• CLI는 계정 범위를 넘는 권한을 얻지 않습니다. 회사 격리, 리소스 소유권, 최종 권한은 모두 서버 측에서 검증합니다.
• 쓰기 작업은 먼저 dry-run을 하거나, AI에게 방안, 영향 범위, 롤백 방법을 먼저 제시하게 하고 확인한 뒤 실행합니다. 삭제 등 고위험 작업은 한 번 더 확인을 요구합니다.
• 대화에 비밀번호, Token 또는 기타 자격 증명을 붙여 넣지 마십시오. CLI의 출력에도 Token은 포함되지 않습니다.
• system 아래의 관리 명령을 사용하려면 계정에 root 또는 agent_admin 역할이 있어야 합니다. 권한 오류가 발생하면 재시도하거나 우회하지 말고 관리자에게 문의하여 확인하십시오.
• 설치할 때는 Node.js, @thinkingai/ae-cli, 공식 Skills만 설치하십시오. TLS 검증을 끄지 말고, 신뢰할 수 없는 미러 소스도 사용하지 마십시오.

자주 묻는 질문

설치 및 권한 부여 문제 자가 점검

증상	일반적인 원인	해결 방법
설치할 수 없거나 다운로드 시간 초과	네트워크, npm 소스 또는 프록시 제한	네트워크와 프록시를 확인하고, 팀에서 승인한 의존성 소스를 사용하며, 전체 오류 정보를 보관
권한 부여 후에도 로그인되지 않음	브라우저 권한 부여 미완료 또는 디바이스 코드 만료	로그인 명령을 다시 실행해 권한 부여를 완료한 뒤 로그인 상태 확인
대상 프로젝트를 찾을 수 없음	계정에 권한이 없거나 잘못된 환경에 연결됨	Agentic Engine 주소, 계정, 프로젝트 ID 확인
AI가 Agentic Engine의 기능을 인식하지 못함	Skills가 설치되지 않았거나 현재 AI Agent가 다시 로드하지 않음	Skills를 다시 설치한 뒤 AI Agent 재시작
명령이 없거나 버전이 일치하지 않는다는 메시지	CLI 또는 Skills가 환경에서 요구하는 버전과 다름	ae-cli update --host <주소> 실행 후 AI Agent 재시작
프라이빗 배포 환경에 연결할 수 없음	주소, 포트, 인증서 또는 내부망 설정 불일치	배포 담당자에게 연결 파라미터를 확인한 뒤 프록시와 인증서 점검

AI의 결론을 그대로 사실로 받아들여도 되나요?

안 됩니다. 먼저 AI가 사용한 지표 정의, 기간, 필터 조건을 확인하십시오. 데이터 결과는 사실이지만 원인 설명은 판단이므로 추가 검증이 필요합니다. 중요한 경영 판단은 여전히 담당자가 다시 검토해야 합니다.

같은 질문인데 왜 답이 다를 때가 있나요?

질문에 기간, 산출 기준 또는 차원이 빠져 있을 수 있고, 프로젝트의 시맨틱 정보가 불완전할 수도 있습니다. 산출 기준이 고정된 자주 하는 작업은 Skill로 작성하고, 탐색적인 질문은 AI가 더 많이 되묻게 하십시오.

다른 사람은 쓸 수 있는 기능을 왜 저는 찾을 수 없나요?

CLI 버전, AI가 로드한 Skills 버전, 현재 환경에 해당 기능이 배포되었는지, 계정에 권한이 있는지 순서대로 확인합니다. 먼저 ae-cli capability list를 실행해 현재 환경에서 제공하는 기능을 확인할 수 있습니다.

문제가 생기면 무엇을 제공해야 하나요?

고객 성공 매니저에게 Agentic Engine 주소, ae-cli --version의 출력, 대상 프로젝트, 재현 단계, 전체 오류 정보를 알려 주십시오. 비밀번호, Token 또는 기타 자격 증명은 보내지 마십시오.

관련 링크

• ae-cli 소스 코드 및 Skills: github.com/ThinkingAIAgenticEngine/ae-cli
• 설치 및 업그레이드 안내(AI Agent용): cli-installation-guide.md
• 엄선된 시나리오 Skills: github.com/ThinkingAIAgenticEngine/scenario-skills