> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI > AgentEye CLI 문서. AgentEye CLI(`agenteye`)는 AgentEye 배포 환경을 위한 터미널 클라이언트입니다. 데이터(세션, 이벤트 로그, 평가)를 조회하고 조직을 관리(API 키, 사용자, 설정, 알림, 인시던트, 저장된 쿼리)합니다. 대시보드에서 할 수 있는 모든 작업을 스크립트나 코딩 에이전트에서도 수행할 수 있습니다. 모든 명령은 `--json` 플래그를 지원하므로, 터미널 앞의 사람에게도, 결과를 파싱하는 코딩 에이전트(Claude Code, Cursor)에게도 동일하게 활용할 수 있습니다. > 이 문서는 **`agenteye` CLI**에 관한 것으로, **컬렉터** 데몬(`agenteye-collector`)과는 별개의 도구입니다. CLI는 **대시보드**와 통신하고, 컬렉터는 서버로 이벤트를 전송합니다. 컬렉터에 대한 내용은 [컬렉터 설치](/ko/agenteye/collector-installation)를 참고하세요. *** ## 설치 CLI는 \*\*`agenteye`\*\*라는 이름으로 공개 PyPI에 게시되어 있습니다. AgentEye Python SDK도 동일한 `agenteye` 배포 이름을 사용하므로, 두 패키지가 하나의 가상 환경에서 충돌하지 않도록 **격리된** 환경(`pipx` 또는 `uv tool`)에 CLI를 설치하세요. ```bash theme={null} pipx install agenteye # 또는 uv tool install agenteye ``` Python SDK를 같은 환경에 설치하지 않는다면 `pip install agenteye`도 사용할 수 있습니다. CLI는 Python 3.10 이상이 필요하며 GitHub 토큰은 필요하지 않습니다. 공개 패키지입니다. 설치된 명령은 \*\*`agenteye`\*\*입니다: ```bash theme={null} agenteye --version agenteye --help ``` *** ## 인증 CLI는 이메일로 전송되는 일회용 코드를 사용해 **대시보드**에 인증합니다: ```bash theme={null} agenteye login --email you@example.com # 6자리 코드가 이메일로 발송됩니다. 프롬프트에 붙여넣으세요. ``` 세션 토큰은 `~/.agenteye/cli.json`에 저장됩니다(본인만 읽을 수 있도록 모드 `0600`으로 설정). 기본적으로 24시간 동안 유효하며, 만료되면 `agenteye login`을 다시 실행하세요. ```bash theme={null} agenteye whoami # 현재 사용자, 활성 조직, 권한 표시 agenteye logout # 세션을 취소하고 저장된 토큰 삭제 ``` `whoami`는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않습니다. 대신 `logged_in: false`를 반환하므로, 스크립트나 에이전트가 안전하게 인증 상태를 확인할 수 있습니다(기본 URL이 설정되지 않았거나 대시보드에 연결할 수 없는 경우에는 여전히 0이 아닌 종료 코드를 반환할 수 있습니다). **요구 사항:** 이메일이 대시보드 로그인 권한이 있어야 하며(AgentEye 관리자에게 문의), 대시보드가 기본 URL에서 접근 가능해야 합니다([구성](#구성) 참고). 코드를 요청했는데 수신되지 않는다면, 해당 이메일이 아직 대시보드 접근 권한을 부여받지 않은 것일 수 있습니다. *** ## 조직 선택 (멀티 테넌트) 계정이 둘 이상의 조직에 속해 있다면, **로그인 시** 활성 조직을 선택하세요. 선택된 조직은 저장되어 이후 모든 명령에 사용됩니다: ```bash theme={null} agenteye login --org acme # 인증하면서 활성 테넌트를 한 번에 설정 agenteye orgs list # 접근 가능한 조직 목록 (활성 조직이 표시됨) agenteye orgs switch globex # 저장된 기본값 변경 agenteye --org globex sessions # 단일 명령에 대해 재정의 ``` 정확히 하나의 조직에 속해 있다면 자동으로 선택되므로 `--org`를 신경 쓸 필요가 없습니다. 여러 조직에 속해 있으면서 선택하지 않으면, CLI가 조직 목록을 표시하고 `--org `를 사용하여 다시 실행하도록 안내합니다. 활성 조직은 모든 요청에 포함되며, 권한은 **조직별로** 결정됩니다. `agenteye whoami`는 활성 조직, 해당 조직에서의 권한, 모든 멤버십을 표시합니다. *** ## 구성 | 설정 | 플래그 | 환경 변수 | 기본값 | | ------------- | ------------------------- | ------------------------------------------------- | ------------------------------------ | | 대시보드 기본 URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **필수** (기본값 없음) | | 활성 조직/테넌트 | `--org` | `AGENTEYE_ORG` | 로그인 시 선택, `~/.agenteye/cli.json`에 저장 | | 세션 토큰 | `--token` | `AGENTEYE_CLI_TOKEN` | `~/.agenteye/cli.json`에서 읽음 | | JSON 출력 | `--json` | `AGENTEYE_CLI_JSON` | 비활성 | | TLS 검증 건너뛰기 | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | 비활성 (로그인 시 저장) | | 요청 타임아웃 (초) | `--timeout` | — | 30 | | 사용 텔레메트리 비활성화 | *(없음)* | `AGENTEYE_ANALYTICS_DISABLED` (또는 `DO_NOT_TRACK`) | 비활성 (텔레메트리 활성) | 우선순위 순서는 **플래그 → 환경 변수 → 설정 파일**입니다. 기본값이 없으므로 CLI가 대시보드를 가리키도록 명령별(`--base-url https://agenteye.example.com`) 또는 환경 변수로 한 번 설정해야 합니다(첫 `login` 이후에도 저장됩니다): ```bash theme={null} export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com ``` 설정 디렉토리는 `AGENTEYE_HOME` 환경 변수를 따릅니다(SDK 및 컬렉터와 동일한 규칙). 설정된 경우 `cli.json`은 `$AGENTEYE_HOME/cli.json`에 위치합니다. ### 자체 서명 또는 내부 TLS 대시보드가 자체 서명 또는 내부 인증서(예: 로드 밸런서 호스트명)로 HTTPS를 제공하는 경우, TLS 검증이 `CERTIFICATE_VERIFY_FAILED` 오류로 실패합니다. `--insecure`를 전달하여 인증서 검증을 건너뛰세요: ```bash theme={null} agenteye --base-url https://agenteye.internal --insecure login ``` `--insecure`는 **로그인 시 `cli.json`에 저장**되므로, 이후 명령에서 자동으로 검증을 건너뜁니다. 플래그를 반복할 필요가 없습니다. 일회성 검증 호출에는 `--secure`를 사용하거나, 다음 로그인 시 검증을 다시 활성화하려면 `--secure`를 저장하세요. CLI는 검증이 비활성화된 상태에서 대시보드에 접속하는 모든 명령 전에 stderr에 경고를 출력합니다. 검증을 건너뛰면 중간자 공격 방어가 제거됩니다. 이를 사용하기 전에 대시보드로의 네트워크 경로(VPN, 사설 서브넷 등)를 신뢰할 수 있는지 확인하세요. *** ## 텔레메트리 및 개인 정보 CLI는 Exosphere의 분석 서비스(PostHog)에 **익명 사용 분석**을 전송합니다: 실행된 명령(예: `sessions`, `keys create`), 성공 여부, 소요 시간. 이 사용 신호는 기능 우선순위 결정에 활용됩니다. * **에이전트, 세션, 이벤트 데이터는 절대 인프라 외부로 전송되지 않습니다.** CLI 사용 정보만 보고됩니다: 명령 및 서브명령 이름(예: `keys create`), 사용한 플래그의 **이름**(값은 절대 포함하지 않음), 성공/종료 상태, 소요 시간. 변경 작업에 대한 이벤트(예: `api_key_created`, `query_run`)는 정적 이름/열거형과 대략적인 수치만 포함합니다. 대시보드 URL, 세션 토큰, 이메일, 조직 슬러그, 리소스 ID, SQL, 키 시크릿, 쿼리 필터는 **절대 전송되지 않습니다.** 운영자는 불투명한 내부 ID로만 식별되며, 이메일은 사용되지 않습니다. * 텔레메트리는 **기본적으로 활성화**되어 있습니다. 비활성화하려면 CLI 환경에서 `AGENTEYE_ANALYTICS_DISABLED=1`을 설정하세요(크로스 툴 규칙인 `DO_NOT_TRACK=1`도 지원합니다). * CLI는 PostHog(`https://us.i.posthog.com`)로 직접 전송합니다. **CLI를 실행하는 머신**은 해당 호스트에 대한 아웃바운드 접근이 필요합니다. 차단된 경우 텔레메트리는 조용히 아무것도 하지 않습니다(전송은 시간 제한이 있으므로 명령을 지연시키거나 중단시키지 않습니다). CLI 동작에는 영향이 없습니다. *** ## 전역 옵션 및 규칙 한 번만 읽어두면 모든 명령에 적용됩니다. * **전역 옵션은 명령 앞에 위치합니다.** `agenteye --json sessions`는 올바른 형식이고, `agenteye sessions --json`은 사용 오류입니다. 전역 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. * **`--json`은 순수 JSON을 stdout으로 출력하며, 그 외에는 아무것도 출력하지 않습니다.** 사람용 상태 메시지, 경고, 오류는 **stderr**로 전달되므로, `--json` stdout 캡처는 상태 메시지가 표시되더라도 `jq`로 파이프하기에 깨끗한 상태를 유지합니다. `--json` 없이는 사람이 읽기 좋은 박스형 컬러 뷰가 표시됩니다. * **`--help`로 탐색하세요.** 모든 명령과 서브명령에는 `--help`(및 `-h` 별칭)가 있습니다: `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. 최상위 도움말에는 종료 코드와 전역 옵션도 나열됩니다. 전역 머신 가독형 전체 목록은 없습니다. 명령별 `--help`와, 두 레지스트리에 대한 도메인별 `agenteye query schema` 및 `agenteye settings schema`를 활용하세요. * **스크립트 및 에이전트에서는 확인 프롬프트가 자동으로 건너뜁니다.** 생성/수정/삭제 명령은 대화형 터미널에서 "확인하시겠습니까?" 메시지를 표시하지만, **`--json`이나 stdin이 TTY가 아닌 경우에는 자동으로 건너뜁니다.** 따라서 스크립트와 에이전트는 멈추지 않습니다. 명시적으로 건너뛰려면 `--yes`/`-y`를 사용하세요. 에이전트에서는 프롬프트가 실행되지 않으므로, 에이전트는 파괴적인 작업을 수행하기 전에 먼저 사람에게 확인을 받아야 합니다. * **페이지네이션:** 결과는 최신순으로 커서 페이지네이션됩니다. `--limit N`(별칭: `-n`)은 행 수를 제한하며 **기본값은 50**입니다. `--all`은 자동 페이지네이션(200행 단위)을 수행하지만 **`--limit`까지만** 가져옵니다. 따라서 `--all`만 사용하면 여전히 50개에서 멈춥니다. 전체 조회를 원하면 명시적으로 높은 값을 지정하세요: `--all --limit 1000`. `--page-size N`은 요청당 청크 크기를 제어하며(최대 200), `--cursor `는 이전 페이지의 `next_cursor`에서 재개합니다. * **시간 필터:** `--since`는 상대 시간 범위(`15m`, `1h`, `6h`, `24h`, `7d`, `30d`, `all` - 대시보드 프리셋)를 받습니다. `--from`/`--to`는 명시적 ISO-8601 UTC 타임스탬프(**`T`와 타임존 포함**, 예: `2026-06-01T00:00:00Z`)를 받아 사용자 지정 범위를 지정하며 `--since`를 재정의합니다. 공백으로 구분되거나 타임존이 없는 값은 사용 오류입니다. * **`--fields a,b,c`**(`events`, `sessions`, `evals`, `errors`에서 사용 가능)는 출력을 해당 키로 제한합니다(테이블과 `--json` 모두 해당). 알 수 없는 이름은 유효한 목록과 함께 거부됩니다. 필드 이름을 간편하게 확인하는 방법입니다. * **`--file payload.json`**(또는 stdin을 읽으려면 `--file -`)은 리소스가 복잡한 형태를 가질 때 전체 JSON 요청 본문을 제공합니다. `alerts create/update`, `settings set`, `users create/update`에서 사용합니다. 저장된 쿼리 SQL은 `--sql @file.sql`을 사용합니다. * **다중 값 필터**는 쉼표로 구분되며 집합으로 매칭됩니다(하나의 필터 내에서는 합집합, 필터 간에는 AND): `--event-type tool_use,tool_result`. Click 옵션은 가변 인수가 아니므로 `--add a b`는 오류입니다. `--add a,b`를 사용하거나 플래그를 반복(`--add a --add b`)하거나 따옴표로 묶으세요(`--add "a b"`). *** ## 명령 참조 CLI에는 **18개의 최상위 명령**이 있습니다. 모든 읽기 명령은 `--json`과 위의 전역 옵션을 지원합니다. 각 명령의 전체 플래그 목록과 JSON 형태는 `agenteye -h`(또는 ` -h`)를 실행하세요. ### 신원 — `login` · `logout` · `whoami` · `orgs` · `version` · `help` ```bash theme={null} agenteye login --email you@example.com [--org acme] # 이메일 일회용 코드; 세션 저장 agenteye logout # 이 머신에서 저장된 세션 삭제 agenteye whoami # 현재 사용자, 활성 조직, 권한 agenteye version # CLI 버전 출력 (--version과 동일) agenteye help # 최상위 도움말 (--help와 동일) ``` `orgs`는 활성 테넌트를 확인하고 전환합니다: ```bash theme={null} agenteye orgs list # 내 조직 + 각 조직에서의 역할 (활성 조직 표시) agenteye orgs switch acme # 저장된 활성 조직 변경 (슬러그 생략 시 TTY에서 목록 선택) agenteye orgs current # 활성 조직의 신원 카드 agenteye orgs perms # 활성 조직에서 내 권한 (리소스별 그룹화) ``` ### 관찰 (읽기 전용) — `events` · `sessions` · `evals` · `errors` · `list` 이 명령들은 확인이 필요하지 않습니다. 공통 필터: `--session-id`, `--agent-id`, `--env`(**`--environment`가 아님**), 시간 범위(`--since` / `--from` / `--to`). ```bash theme={null} # events (별칭: 단계별 원시 추적) — 최신순 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000 agenteye --json events --since 1h --search timeout --all | jq '.events[].payload' # sessions — 에이전트 실행별 한 행 (시간/환경/에이전트/세션/상태; 점수 필터 없음) agenteye --json sessions --since 24h --status error agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000 # evals — 평가 결과 + 점수; --score는 지표로 필터, --aggregate는 집계 agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3 agenteye --json evals --aggregate --since 7d --env prod # 상태 분포 + 키별 점수 통계 # errors — 오류 이벤트; --aggregate는 수량/세션/에이전트/마지막 발생 시간 집계 agenteye --json errors --since 24h --aggregate agenteye --json errors --since 24h --error-type timeout --all --limit 1000 # list — 필터링 전 유효한 필터 값 탐색 agenteye list envs # 또한: agents event_types score_filters models hooks triggers tools error_types ``` `--score KEY:MIN..MAX`(\*\*`evals`\*\*에서 사용 가능, `sessions`에서는 불가)는 반복 가능하며 AND로 결합됩니다. 어느 쪽 경계도 선택 사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9 의미). 요청당 최대 20개의 점수 필터. `evals --scores-full`은 요약 대신 전체 점수 객체를 반환합니다. **하나의 세션을 처음부터 끝까지 읽으려면** 이벤트 추적과 평가를 함께 사용하세요: ```bash theme={null} agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' agenteye --json evals --session-id run-001 # 점수 + 상태 ``` ### 관리 (권한 필요) — `keys` · `users` · `settings` · `alerts` · `incidents` **`keys`** — API 키. 시크릿은 로컬에서 생성되어 서버로 전송되고(서버는 해시만 저장), 생성/재생성 시 **한 번만 표시됩니다**. 그때 반드시 캡처하세요. `--json`을 사용하면 `key` 필드에만 나타납니다. **이름**으로 참조됩니다. ```bash theme={null} agenteye keys list # 활성 키 먼저, 그 다음 취소된 키 agenteye keys show ci-bot agenteye keys create ci-bot --add events:read.add # 필요한 범위만 지정; 시크릿은 한 번만 출력 agenteye keys create ops --permission-set standard --remove queries:run # 프리셋에서 시작 후 제거 agenteye keys update ci-bot --add evaluations:read --yes agenteye keys regenerate ci-bot --yes # 시크릿 교체 (이전 시크릿은 즉시 비활성화) agenteye keys disable ci-bot --yes # 취소 ``` 권한은 `(permission-set ∪ --add) − --remove` 방식으로 작동합니다. 토큰은 `slug:action`(예: `events:read`) 또는 `slug:action.action` 형태로 하나의 리소스에 여러 액션을 확장할 수 있습니다(`events:read.add` → `events:read`, `events:add`). 프리셋: `read-only`, `standard`, `admin`. 사람 전용 권한(`keys:update`)은 키에 부여할 수 없습니다. **`users`** — 조직 멤버. **이메일**로 참조됩니다(UUID id도 허용). ```bash theme={null} agenteye users list [--active-only] agenteye users show dev@corp.com agenteye users create dev@corp.com --permission-set standard agenteye users update dev@corp.com --add alerts:write --remove queries:delete # 예측 + 확인 agenteye users disable dev@corp.com --yes # 보호/자기 자신 가드 포함 agenteye users enable dev@corp.com ``` **`settings`** — 고정 레지스트리 (기존 키를 읽고 변경하는 것만 가능; 새 키 생성 불가). ```bash theme={null} agenteye settings list # 키 · 값 · 타입 · 수정 시간 (시크릿은 마스킹) agenteye settings schema # 각 키가 허용하는 값 (타입 · 범위 · 설명) agenteye settings set session_ttl_secs --value 86400 --yes ``` **`alerts`** — 알림 정의. **이름**으로 참조됩니다. `create`는 위치 인수로 NAME을 받으며, 플래그 또는 `--file`로 전체 JSON 본문을 제공할 수 있습니다. ```bash theme={null} agenteye alerts list agenteye alerts show high-errors agenteye alerts create high-errors --file alert.json # NAME 필수 (위치 인수) agenteye alerts update high-errors --severity critical --yes agenteye alerts test high-errors --yes # 테스트 알림 전송 agenteye alerts delete high-errors --yes ``` **`incidents`** — 알림 인시던트. ID로 참조됩니다(짧은 ID 허용). `show`는 전체 활동 로그를 출력합니다. 조치 전에 반드시 확인하세요. ```bash theme={null} agenteye incidents list --state firing # 또한: acknowledged, resolved agenteye incidents count agenteye incidents show agenteye incidents ack agenteye incidents assign you@corp.com # 담당자는 운영자여야 함 agenteye incidents resolve --yes agenteye incidents open --alert-id --severity critical # 알림에 대해 수동으로 생성 agenteye incidents comment-add "root cause: upstream 5xx" agenteye incidents comment-list ; agenteye incidents comment-delete agenteye incidents subscribe ; agenteye incidents unsubscribe ; agenteye incidents subscribers ``` ### 분석 및 어시스턴트 — `query` · `agent` **`query`** — 저장된 ClickHouse SQL과 임시 실행기. 저장된 쿼리는 **이름**으로 참조됩니다. SQL은 서버 측에서 검증됩니다(SELECT/WITH만 허용, 쿼리 타임아웃, 행 제한). ```bash theme={null} agenteye query schema [TABLE] # 분석 뷰의 컬럼 레이아웃 agenteye query run --sql "select count(*) from analytics.events" agenteye query run errs --arg prod --limit 100 # 저장된 쿼리 실행 + 위치 인수 $1 agenteye query list ; agenteye query show errs agenteye query create errs --sql @errs.sql --description "errored events (24h)" agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes ``` **`agent`** — 내장 대시보드 어시스턴트(대시보드에서 채팅할 수 있는 것과 동일한 읽기 전용 분석가). 채팅은 짧은 chat-id로 참조됩니다(접두사 자동 해결). ```bash theme={null} agenteye agent health # 어시스턴트 설정/접근 가능 여부 확인 agenteye agent models # --model에 전달 가능한 모델 (기본값 표시) agenteye agent ask "which agents errored most in the last day?" # 채팅 시작; 짧은 id 출력 agenteye agent ask --chat "and which tools did they call?" # 채팅 계속 agenteye agent chats ; agenteye agent show agenteye agent rename --title "error triage" ; agenteye agent delete ``` *** ## 종료 코드 | 코드 | 의미 | | -- | ------------------------------------------ | | 0 | 성공 | | 1 | 예상치 못한 오류 (예: 대시보드가 5xx를 반환) | | 2 | 사용 오류 (잘못된 인수, 알 수 없는 명령/플래그, 이름 충돌) | | 3 | 대시보드에 연결할 수 없음 | | 4 | 로그인하지 않았거나 세션이 만료됨; `agenteye login` 실행 필요 | | 5 | 인증되었지만 필요한 권한이 없음 (메시지에 권한 이름 표시) | | 6 | 요청한 리소스를 찾을 수 없음 (예: 알 수 없는 세션 또는 인시던트 ID) | 이 코드들을 통해 CLI를 안전하게 스크립트화할 수 있습니다. 코딩 에이전트는 `4`를 받으면 재인증을 요청하거나, `5`를 받으면 누락된 권한을 표시할 수 있습니다. 종료 코드 처리 패턴과 JSON 출력 형태는 [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)를 참고하세요. *** ## 관련 문서 * **[에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes)** — 코딩 에이전트를 위한 복사-붙여넣기 쿼리 패턴, `jq` 원라이너, `--fields` 프로젝션, 종료 코드 처리, JSON 출력 형태. * **[AgentEye CLI 스킬](/ko/agenteye/cli-skill)** — 이 CLI를 설치 가능한 Claude Code / Codex *스킬*로 패키징하여 코딩 에이전트가 일반 영어 요청으로 AgentEye를 구동할 수 있게 합니다. * **[API 키](/ko/agenteye/api-keys)** — `keys create --add …` 뒤의 권한 모델. * **[AI 어시스턴트](/ko/agenteye/assistant)** — `agent ask`가 대화하는 어시스턴트 활성화 방법.