smartstore-cli

네이버 스마트스토어 판매자센터 웹 세션을 재사용해 조회 데이터를 터미널에서 다루기 위한 비공식 CLI입니다.

실행 바이너리는 storectl입니다.

Quick Start · 지원 범위 · How It Works · Development · 문서

Warning

이 프로젝트는 네이버 공식 제품이 아닙니다. 웹 내부 API를 비공식적으로 사용하며, 네이버 이용약관(TOS) 위반에 해당할 수 있습니다. API는 예고 없이 변경될 수 있고, 사용으로 인한 계정 제한, 손실, 기타 불이익에 대해 개발자는 어떠한 책임도 지지 않습니다. 본인의 판단과 책임 하에 사용하세요.

Important

현재 버전(v0.1.x)은 읽기 전용(read-only) 입니다. 상품 등록/수정, 주문 상태 변경 등 쓰기 작업은 아직 지원하지 않습니다.

Works with

Claude Code

Codex

Cursor

Bash

HTTP

Quick Start

For AI Agent

# storectl은 AI 에이전트가 직접 실행할 수 있습니다
storectl seller info --output json    # 구조화된 JSON 출력
storectl product list --output csv    # CSV로 파이프 가능
storectl stats daily --output json    # 매출 데이터 자동 수집

Install

# macOS / Linux (원라인 설치)
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/smartstore-cli/main/install.sh | sh

# 바로 사용
storectl doctor
storectl auth login
storectl seller info --output json

Windows

irm https://raw.githubusercontent.com/JungHoonGhae/smartstore-cli/main/install.ps1 | iex

From Source

git clone https://github.com/JungHoonGhae/smartstore-cli.git
cd smartstore-cli
make build
pip3 install -e auth-helper/
bin/storectl doctor

지원 범위

조회 (Read-Only)

Command	Description	Output
storectl seller info	스토어 정보 (스토어명, URL, 대표자, 연락처, 정산계좌)	table/json/csv
storectl seller grade	판매자 등급 + 페널티 점수	table/json/csv
storectl product list	상품 목록 (--page, --size 페이지네이션)	table/json/csv
storectl product show <id>	상품 상세 (채널상품번호로 조회)	table/json
storectl product dashboard	상품 현황 카운트 (판매중/품절/수정요청)	table/json/csv
storectl order list	주문/배송 대시보드 (상태별 건수)	table/json/csv
storectl order list --detail	주문 목록 상세 (GraphQL, --page, --size)	table/json/csv
storectl stats daily	매출 통계 (일간/주간/월간 PV, 주문수, 결제금액)	table/json/csv
storectl settlement list	정산 대시보드 (오늘정산, 예정정산, 충전잔액)	table/json/csv
storectl inquiry list	고객 문의 (상품문의/고객문의/톡톡)	table/json/csv
storectl review list	리뷰 목록 (--page, --size 페이지네이션)	table/json/csv
storectl review dashboard	리뷰 대시보드 (총 리뷰수, 평균점수)	table/json/csv
storectl notification list	알림 목록 (--count N 최근 활동)	table/json/csv

시스템

Command	Description
storectl version	버전 정보
storectl doctor	시스템 건강 체크 (Python, Playwright, Chrome)
storectl config init|show	설정 파일 관리
storectl auth login	브라우저 기반 네이버 로그인
storectl auth status	세션 상태 (Last Used At 포함)
storectl auth refresh	Headless 세션 갱신
storectl auth logout	세션 삭제
storectl auth doctor	인증 요구사항 점검

How It Works

User → storectl auth login
         ↓
       Python Playwright → Opens Chrome browser
         ↓
       User completes Naver ID login → Seller center
         ↓
       Captures cookies (NID_AUT, NID_SES, kit.session, NSI, ...)
         ↓
       Saves to session.json
         ↓
User → storectl product list
         ↓
       Loads session.json → Applies cookies to HTTP request
         ↓
       POST https://sell.smartstore.naver.com/api/products/list/search
         ↓
       Parses JSON → Renders table/json/csv

Session Management

• 세션은 session.json에 저장되며 API 호출마다 자동으로 쿠키를 갱신합니다
• 세션 만료 시 자동으로 change-channel + login/init 플로우를 시도합니다
• 자동 갱신 실패 시 storectl auth login으로 재로그인이 필요합니다
• storectl auth status에서 마지막 사용 시각과 세션 상태를 확인할 수 있습니다

왜 storectl인가?

네이버는 공식 커머스 API를 제공하지만, 사용하려면 개발사 계정 가입 → 애플리케이션 등록(심사) → OAuth 2.0 인증 구현 → API 호출 코드 작성이 필요합니다. 코드를 작성할 수 있는 개발자만 사용할 수 있습니다.

# 공식 API로 매출 조회하려면:
1. 커머스API센터 가입 (개발사 계정)
2. 애플리케이션 등록 + 심사
3. OAuth 토큰 발급/갱신 코드 작성
4. API 호출 + JSON 파싱 코드 작성
→ 개발자도 반나절

# storectl로:
$ storectl auth login   ← 평소 하던 네이버 로그인
$ storectl stats daily  ← 끝
→ 개발 경험 없어도 5분

또한 공식 API에서 제공하지 않는 데이터도 있습니다:

데이터	공식 커머스 API	storectl
상품 조회	제공 (개발사 가입 + OAuth 구현)	네이버 로그인만으로 조회
주문 조회	제공 (개발사 가입 + OAuth 구현)	네이버 로그인만으로 조회
판매자 등급/페널티	미제공	제공
리뷰	미제공	제공
알림	미제공	제공
매출 대시보드/차트	브랜드스토어 전용 (유료)	무료 제공
주문/배송 대시보드 카운트	미제공	제공
AI 에이전트 연동	직접 구현 필요	--output json 즉시 연동

storectl은 코드 작성 없이, 네이버 로그인만으로 판매자센터 데이터를 CLI에서 조회합니다.

API Architecture

판매자센터는 AngularJS SPA로 구성되어 있으며, storectl은 내부 웹 API를 리버스 엔지니어링하여 사용합니다:

API Pattern	Method	Usage
/api/v1/sellers/dashboards/*	GET	대시보드 데이터 (주문, 상품, 정산, 리뷰 등)
/api/products/list/search	POST	상품 검색
/api/v3/contents/reviews/search	POST	리뷰 검색
/api/channels?_action=selectedChannel	GET	판매자/채널 정보
/o/v3/graphql	POST	주문 상세 (별도 SPA, Apollo Client)
/api/login/change-channel	POST	세션 초기화

Installation

From Source

git clone https://github.com/JungHoonGhae/smartstore-cli.git
cd smartstore-cli
make build

Auth Helper

Python 3.10+ 필요:

pip install -e auth-helper/
# playwright install chromium  ← 불필요 (시스템 Chrome 사용)

Prerequisites Check

bin/storectl doctor

정상이면:

[ok] python_binary
[ok] auth_helper_dir
[ok] playwright_module
[ok] chrome_installed

Development

make build     # → bin/storectl
make test      # go test ./...
make fmt       # gofmt
make tidy      # go mod tidy
make clean     # rm bin/ coverage.out

Project Layout

cmd/storectl/        CLI command layer (Cobra)
internal/
  auth/              Browser login orchestration
  client/            Naver Smart Store web API client
  config/            Configuration loading & paths
  doctor/            System health check
  domain/            Data models (mapped to real API responses)
  output/            Multi-format renderers (table/JSON/CSV)
  session/           Session persistence with auto-refresh
  version/           Build version info
auth-helper/         Python + Playwright login helper
docs/                API documentation & capture guides
fixtures/            Captured API response samples
schemas/             JSON Schema for config.json
scripts/             API discovery & analysis tools

문서

Reverse Engineering

API 엔드포인트는 브라우저 트래픽 캡처를 통해 리버스 엔지니어링되었습니다:

• docs/reverse-engineering/capture-guide.md — Chrome DevTools 캡처 가이드
• docs/reverse-engineering/mitmproxy-guide.md — mitmproxy 고급 가이드
• docs/api/CHANGELOG.md — API 변경 이력

Local Storage

File	Purpose
<config-dir>/config.json	설정 파일
<config-dir>/session.json	브라우저 세션 (쿠키, 헤더, localStorage)

Config directory: ~/Library/Application Support/storectl/ (macOS) or ~/.config/storectl/ (Linux)

Roadmap

v0.1.0 — Read-Only Foundation (현재)

• 브라우저 기반 로그인 (Playwright + Google Chrome)
• 실제 API 리버스 엔지니어링 (513개 엔드포인트 발견)
• 판매자 정보/등급 조회
• 상품 목록/상세/대시보드
• 주문/배송 대시보드 + GraphQL 주문 목록
• 매출 통계 (일간/주간/월간)
• 정산/문의/리뷰/알림 조회
• 페이지네이션 (--page, --size)
• 세션 자동 갱신 + 초기화 자동화
• Table/JSON/CSV 출력
• 5개 플랫폼 릴리즈 (macOS/Linux/Windows)
• 25개 유닛 테스트

v0.2.0 — Write Operations (예정)

• 상품 등록 (storectl product create)
• 상품 수정 (storectl product update)
• Safety gate: config.json으로 쓰기 기능 기본 비활성화
• 상품 등록 API 리버스 엔지니어링

v0.3.0 — Stability & DX (예정)

• Homebrew tap (brew install storectl)
• 세션 자동 재로그인 안정화
• 주문 상세 GraphQL 세션 문제 해결
• 더 많은 유닛/통합 테스트
• storectl export (CSV 일괄 내보내기)

v0.4.0 — Advanced (예정)

• 주문 상태 변경 (발송처리, 취소 등)
• 일괄 상품 등록 (storectl product bulk-create)
• 알림 실시간 모니터링
• MCP 서버 (AI 에이전트 직접 연동)

License

MIT License - see LICENSE for details.

Copyright (c) 2026 JungHoon Ghae