CLI 사용하기

reopt-data는 사람, CI, 에이전트가 같은 계약으로 리옵트 데이터를 다룰 수 있게 하는 CLI예요. 브라우저에서 개인 세션을 승인해 내 계정을 조회할 수도 있고, 배포 자격증명으로 조직·프로젝트·카탈로그·쿼리·소스맵을 운영할 수도 있습니다.

설치하고 로그인하기

Node.js 22 이상에서 전역으로 설치하거나 npx로 바로 실행하세요.

npm install -g @reopt-ai/data-cli
reopt-data --help

# 설치 없이 확인
npx -y @reopt-ai/data-cli --help

개인 계정 흐름은 네 명령으로 닫힙니다.

reopt-data login
reopt-data status --format text
reopt-data account show --format table
reopt-data logout

자체 호스팅이나 로컬 서버에 로그인하려면 모든 명령에 적용되는 --api-url을 사용하세요.

reopt-data login --api-url http://localhost:4001

어떤 자격증명을 써야 하나요?

개인 로그인과 배포 자격증명은 권한도 보관 방식도 다릅니다.

개인 CLI 세션의 현재 scope는 account:read뿐입니다. 따라서 reopt-data login을 했더라도 조직 생성이나 분석 쿼리에 필요한 플랫폼·조직·클라이언트 자격증명을 대신하지 않습니다. 반대로 배포 키만 설정해도 account show는 실행할 수 없습니다.

브라우저 로그인은 어떻게 동작하나요?

1. CLI가 짧은 확인 코드와 브라우저 URL을 발급받습니다.
2. 브라우저가 열리면 로그인된 Reopt 계정으로 표시된 코드가 같은지 확인하고 승인합니다.
3. CLI가 승인 상태를 기다렸다가 한 번만 세션으로 교환합니다.
4. 세션을 ~/.reopt/data/auth.json에 원자적으로 저장합니다.

비밀번호와 브라우저 쿠키는 터미널로 전달되지 않습니다. 브라우저 URL에는 사람이 확인할 코드만 들어가고, 별도의 device secret은 CLI 메모리에만 머뭅니다. 브라우저 cookie와 CLI bearer는 서버에서 audience가 분리되어 있어 서로 대신 사용할 수 없습니다.

원격 서버나 브라우저를 열 수 없는 환경에서는 URL만 출력하세요.

reopt-data login --no-browser

이미 유효한 로그인이 있으면 login은 그 세션을 재사용합니다. 새 세션으로 바꾸려면 --force를 사용하세요. 새 세션이 안전하게 저장된 뒤 이전 서버 세션을 해제합니다.

reopt-data login --force

POSIX 환경에서 인증 디렉터리는 0700, 파일은 0600으로 유지됩니다. 테스트나 격리된 실행에서는 REOPT_DATA_AUTH_FILE로 경로를 바꿀 수 있습니다.

로그인 상태 확인하기

status는 로컬 파일 존재 여부만 보지 않고 서버에 세션을 검증합니다. 토큰 값은 출력하지 않으며, 서버가 만료 시각을 연장했다면 로컬 파일에도 새 시각을 저장합니다.

reopt-data status
reopt-data status --format text

session 필드는 다음처럼 해석하세요.

status는 플랫폼 키, 조직 키, 클라이언트 자격증명의 설정 여부만 함께 보여줍니다. 값 자체는 출력하지 않습니다.

계정과 접근 가능한 프로젝트 확인하기

reopt-data account show
reopt-data account show --format table

응답에는 로그인 사용자, CLI 세션의 scope·만료·최근 사용 시각, 사용자가 멤버인 조직과 활성 프로젝트가 들어갑니다. 조직 키, write key, client secret 같은 배포 자격증명은 반환하지 않습니다.

account show는 먼저 사용자 세션을 서버에 재검증하고 account:read scope를 확인합니다. 브라우저 세션 cookie를 bearer로 보내거나 CLI 토큰을 브라우저 cookie로 사용하면 모두 거절됩니다.

로그아웃과 세션 폐기

reopt-data logout

logout은 저장된 서버 세션을 폐기한 뒤 로컬 인증 파일을 지웁니다. 서버에 연결하지 못해 폐기를 확인하지 못해도 로컬 파일은 제거하고 경고를 출력합니다.

REOPT_DATA_USER_TOKEN으로 주입한 세션은 실행 환경이 소유하므로 CLI가 폐기하거나 지우지 않습니다. 로그아웃 뒤에도 이 변수가 설정되어 있으면 계속 사용되므로 secret manager나 셸 환경에서 직접 제거하세요.

배포 자격증명 설정하기

반복 실행과 CI에서는 플래그보다 환경변수를 사용하세요. 플래그 값은 셸 히스토리와 프로세스 목록에 남을 수 있습니다.

export REOPT_DATA_API_URL="https://data.reopt.ai"
export REOPT_DATA_PLATFORM_KEY="..."
export REOPT_DATA_ORG_KEY="..."
export REOPT_DATA_CLIENT_ID="..."
export REOPT_DATA_CLIENT_SECRET="..."

필요한 자격증명이 없으면 CLI는 네트워크 요청 전에 종료 코드 2로 실패하고 설정할 변수 이름을 알려줍니다. CI secret store에는 실제 값만 넣고 로그, 저장소, reopt-data.config.*에는 기록하지 마세요.

출력과 자동화 계약

기본 출력은 JSON입니다. stdout에는 결과만, 진행 상황과 오류 envelope는 stderr에 기록됩니다.

reopt-data project list --format json
reopt-data project list --format table
reopt-data project list --format csv
reopt-data account show --format yaml

필드 선택과 cursor 전체 순회를 조합할 수 있습니다.

reopt-data project list --fields id,name --page-all --page-limit 20

JSON에서 --page-all을 쓰면 배열 하나가 아니라 레코드당 한 줄인 NDJSON을 출력합니다. 다음 cursor가 남아 있는데 --page-limit에 도달하면 종료 코드 6으로 끝나므로, 잘린 결과를 성공으로 오해하지 않습니다.

login --format json도 진행 중 결과를 전달해야 하므로 verification_uri, polling, success 이벤트를 NDJSON으로 출력합니다. 세션 토큰과 device secret은 포함하지 않습니다.

입력은 플래그, JSON 문자열, 파일, stdin 중에서 고를 수 있고 나중 입력이 앞의 값을 덮어씁니다.

reopt-data query funnel --input @funnel.json
echo '{"projectId":"prj_123"}' | reopt-data project get --input @-

모든 옵션은 실행 코드와 같은 schema에서 생성되는 help로 확인하세요.

reopt-data project create --help
reopt-data query funnel --help

안전한 변경 명령

삭제와 키·secret 회전 같은 파괴적 명령은 --yes가 없으면 요청을 보내지 않고 종료 코드 7로 멈춥니다.

reopt-data project delete prj_123 --yes
reopt-data project rotate-secret prj_123 --yes

소스맵 명령은 --dry-run으로 파일 탐색과 계획을 먼저 확인할 수 있습니다. 지원하지 않는 명령에 --dry-run을 주면 조용히 무시하지 않고 종료 코드 3으로 실패합니다.

이벤트 카탈로그를 코드로 관리하기

프로젝트 저장소의 reopt-data.events.json을 기준으로 서버 카탈로그를 동기화할 수 있습니다.

reopt-data event init --project-id prj_123
reopt-data event pull
reopt-data event diff --format text
reopt-data event push                 # 계획만 출력
reopt-data event push --apply --yes   # 실제 반영
reopt-data event verify               # drift가 있으면 exit 8
reopt-data event types --out src/reopt-events.d.ts

파일에서 필드를 생략하면 "기존 값 유지"가 아니라 계약의 기본값을 뜻합니다. event push는 마지막 동기화 시각으로 전체 배치를 비교해 콘솔 변경과 충돌하면 일부만 반영하지 않고 모두 거절합니다.

version: 2 파일은 properties 절로 속성의 의미(타입·설명·숨김)도 함께 씁니다. 이벤트와 달리 파일에 없는 속성은 관측된 그대로 둡니다 — 속성을 존재하게 만드는 건 수집이라 파일이 은퇴시킬 수 없습니다.

그래서 verify는 기본적으로 미선언 속성을 지적하지 않습니다. 저장소가 카탈로그를 소유한다면 둘 중 골라 켜세요.

reopt-data event verify --strict-properties   # 콘솔에서 손댔는데 파일에 없는 속성
reopt-data event verify --strict-observed     # 수집이 관측만 했는데 파일에 없는 속성

서로를 포함하지 않고 보고 대상이 겹치지 않으므로, 둘 다 원하면 둘 다 주면 됩니다. --strict-observed는 SDK 소유 키($ 예약 키와 자동 이벤트 속성)를 제외합니다.

--strict-observed에는 함정이 하나 있습니다. 속성을 추가한 PR에서는 잡히지 않습니다 — 그 시점엔 서버가 그 키를 본 적이 없기 때문입니다. 배포 후 첫 이벤트로 행이 생기고, 실패는 무관한 다음 PR에 떨어집니다. 이 비용을 받아들일 저장소에서만 켜세요.

프로젝트 설정·룰·알림을 코드로 관리하기

카탈로그와 같은 규칙으로 프로젝트 설정, 에러 트래킹 룰, 알림도 저장소의 reopt-data/ 디렉터리에 선언할 수 있어요. 여섯 동사가 top-level 명령이고, 표를 만드는 명령은 status가 아니라 diff입니다(status는 로그인 상태).

reopt-data pull                          # 서버 → reopt-data/*.json + reopt-data.lock.json
reopt-data diff --format text            # 종류 / key / 작업 / 등급
reopt-data verify                        # CI 게이트. 어긋나면 exit 8
reopt-data push --apply --yes            # 반영. destructive(보존 기간 축소)는 --yes 없이는 요청 전에 exit 7
reopt-data import error-rule <id> --key ignore-vendor
reopt-data unlink alert purchase-drop
reopt-data --env staging pull            # config `environments`로 프로젝트를 고르고 lock을 환경별로

key가 있는 룰·알림만 파일이 다스리고, 콘솔이 만든 항목은 건드리지 않아요. 웹훅 URL은 "${env:SLACK_ALERTS_URL}"처럼 이름으로 적으면 push 시점에 치환됩니다. 파일 형식, 등급, 충돌 해결, 환경 설정은 프로젝트를 코드로 관리하기에서 자세히 다룹니다.

소스맵을 CI에서 업로드하기

reopt-data sourcemap inject --dir .next/static
reopt-data sourcemap upload \
  --dir .next/static \
  --url-prefix https://shop.example.com/_next/static \
  --project-id "$REOPT_DATA_PROJECT_ID" \
  --release "$GIT_SHA" \
  --delete-after-upload

먼저 --dry-run으로 대상 파일과 업로드 계획을 확인하세요. 프로젝트·조직 host app·플랫폼 범위의 symbol set은 sourcemap list*와 delete* 명령으로 조회하고 폐기할 수 있습니다.

셸 completion과 에이전트 연동

현재 셸에 completion을 적용할 수 있습니다.

# bash / zsh
source <(reopt-data completion bash)
source <(reopt-data completion zsh)

# fish
reopt-data completion fish | source

에이전트가 명령 계약을 탐색해야 하면 실행 가능한 schema catalog를 사용하세요.

reopt-data tools --json

MCP client에는 같은 도구 registry를 stdio 서버로 연결할 수 있습니다.

{
  "mcpServers": {
    "reopt-data": {
      "command": "npx",
      "args": ["-y", "@reopt-ai/data-cli", "mcp"],
      "env": {
        "REOPT_DATA_ORG_KEY": "..."
      }
    }
  }
}

account show MCP 도구는 저장된 사용자 로그인 또는 REOPT_DATA_USER_TOKEN을 사용합니다. 배포 도구는 MCP process에 주입한 환경변수와 repository config를 사용합니다. 파괴적 도구는 CLI의 --yes 대신 confirmed: true가 필요합니다.

종료 코드

자주 막히는 지점

다음 단계

• 프로젝트에 첫 이벤트를 붙이려면 빠른 연동
• 카탈로그 의미와 변경 등급은 이벤트 카탈로그
• 설정·룰·알림을 파일로 두는 흐름은 프로젝트를 코드로 관리하기
• API endpoint 경계는 서비스 Plane과 엔드포인트