Package Exports

@solapi/crm-cli
@solapi/crm-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@solapi/crm-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

SOLAPI CRM CLI

SOLAPI CRM을 터미널에서 직접 관리하고, AI Agent와 연동하세요.

핵심 특징

OpenAPI 기반 동적 명령어: 백엔드 API 추가 시 CLI 재배포 없이 자동 반영
다양한 출력 형식: JSON, 테이블, CSV로 유연한 출력
MCP 서버 모드: Claude Desktop / Claude Code와 직접 연동
프로필 기반 인증: 여러 계정 정보 저장 및 관리

Quick Start

# 1. 설치
npm install -g @solapi/crm-cli

# 2. 인증 (SOLAPI 콘솔 → API Key 발급 → 입력)
solcrm auth login

# 3. 사용
solcrm entities list          # 개체 목록
solcrm records list --entityId ENxxx  # 레코드 목록

설치

npm (권장)

npm install -g @solapi/crm-cli
solcrm --help

npx (설치 없이 즉시 실행)

npx @solapi/crm-cli --help

Node.js 요구사항

Node.js 18.0 이상

인증 설정

대화형 로그인

solcrm auth login

다음 두 가지를 입력합니다:

API Key: NCS... (SOLAPI 콘솔 → API Key 관리에서 발급)
API Secret: *** (마스킹 입력)

비대화형 로그인 (CI/스크립트 자동화)

solcrm auth login --api-key NCSXXX --api-secret XXX

옵션:

--api-key <key> — API Key
--api-secret <secret> — API Secret
--profile <name> — 프로필 이름 (기본: default)

환경변수 설정 (Docker/CI)

export SOLAPI_API_KEY=NCSXXX
export SOLAPI_API_SECRET=XXX

solcrm records list --entityId ENxxx

환경변수가 있으면 저장된 프로필보다 우선됩니다.

프로필 관리

여러 계정을 동시에 관리하고 필요할 때마다 전환할 수 있습니다.

solcrm auth list       # 저장된 프로필 목록
solcrm auth use work   # 활성 프로필 전환
solcrm auth whoami     # 현재 인증 정보 확인 (Secret은 마스킹)
solcrm auth logout     # 프로필 삭제

저장 위치: ~/.solapi/credentials.json (Git에 추가하지 마세요)

사용 가능한 리소스

로그인 후 CRM API의 OpenAPI 스펙에서 명령어가 자동 생성됩니다. 주요 리소스:

리소스	설명	예시
`entities`	개체(고객, 회사 등) 스키마 관리	`solcrm entities list`
`records`	개체에 속한 데이터 레코드 CRUD	`solcrm records list --entityId ENxxx`
`properties`	개체의 속성(필드) 정의 관리	`solcrm properties list --entityId ENxxx`
`segments`	조건 기반 레코드 그룹	`solcrm segments list --entityId ENxxx`
`automations`	자동화 워크플로우 관리	`solcrm automations list`
`dashboards`	대시보드 및 위젯 관리	`solcrm dashboards list`
`activities`	레코드 활동 이력 조회	`solcrm activities list --recordId RECxxx`
`relationships`	레코드 간 관계 관리	`solcrm relationships list`
`documents`	문서/양식 관리	`solcrm documents list`
`events`	이벤트 추적 데이터 조회	`solcrm events list`

새 API가 백엔드에 추가되면 solcrm config clear-cache 후 자동 반영됩니다.

명령어 구조

solcrm <리소스> <액션> [경로_파라미터] [옵션]

기본 CRUD 패턴

solcrm <리소스> list [--옵션]         # 목록 조회
solcrm <리소스> get <id>             # 상세 조회
solcrm <리소스> create --data '{}'   # 생성
solcrm <리소스> update <id> --data '{}'  # 수정
solcrm <리소스> delete <id>          # 삭제

사용 예시

# 개체 목록
solcrm entities list

# 레코드 생성
solcrm records create --data '{"entityId":"ENxxx","name":"홍길동"}'

# 레코드 수정
solcrm records update RECxxx --data '{"name":"김철수"}'

# 세그먼트 미리보기
solcrm segments preview SEGxxx

# 파일에서 요청 본문 로드
solcrm records create --data-file customer.json

출력 형식

--format 옵션으로 출력 형식을 지정합니다 (기본: table).

solcrm records list --entityId ENxxx                   # 테이블 (기본)
solcrm records list --entityId ENxxx --format json      # JSON
solcrm records list --entityId ENxxx --format csv       # CSV (파일 export용)
solcrm records list --entityId ENxxx --format csv > export.csv

설정 관리

OpenAPI 스펙 캐시

CLI는 OpenAPI 스펙을 1시간 동안 로컬 캐시합니다.

solcrm config clear-cache    # 캐시 삭제, 다음 실행 시 최신 스펙 로드

캐시 위치: ~/.solapi/cache/

MCP 서버 모드 (AI Agent 연동)

solcrm --mcp로 MCP(Model Context Protocol) 서버를 실행하면, AI Agent가 CRM API를 직접 호출할 수 있습니다.

Claude Desktop 설정

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "solapi-crm": {
      "command": "solcrm",
      "args": ["--mcp"]
    }
  }
}

Claude Code 설정

claude mcp add solapi-crm -- solcrm --mcp

또는 프로젝트 루트에 .mcp.json 생성:

{
  "mcpServers": {
    "solapi-crm": {
      "command": "solcrm",
      "args": ["--mcp"]
    }
  }
}

npx로 설치 없이 MCP 연동

{
  "mcpServers": {
    "solapi-crm": {
      "command": "npx",
      "args": ["-y", "@solapi/crm-cli", "--mcp"]
    }
  }
}

환경변수로 인증 (MCP 설정에서)

{
  "mcpServers": {
    "solapi-crm": {
      "command": "solcrm",
      "args": ["--mcp"],
      "env": {
        "SOLAPI_API_KEY": "NCSXXX",
        "SOLAPI_API_SECRET": "XXX"
      }
    }
  }
}

MCP로 제공되는 tool

MCP 서버는 CLI와 동일한 CRM API를 crm_{리소스}_{액션} 이름의 tool로 노출합니다:

crm_records_list — 레코드 목록 조회
crm_records_create — 레코드 생성
crm_entities_list — 개체 목록 조회
crm_segments_list — 세그먼트 목록 조회
crm_automations_list — 자동화 목록 조회
... (OpenAPI 스펙에서 자동 생성)

문제 해결

"인증되지 않았습니다" 오류

solcrm auth list     # 프로필 확인
solcrm auth login    # 없으면 로그인
solcrm auth whoami   # 있으면 활성 프로필 확인

"API 오류 (401/403)"

API Key/Secret이 만료되었을 수 있습니다. SOLAPI 콘솔에서 새로 발급 후 solcrm auth login으로 재설정하세요.

"OpenAPI spec 로딩 실패"

solcrm config clear-cache    # 캐시 삭제 후 재실행
ping api.solapi.com          # 네트워크 확인

오프라인 환경에서는 캐시된 스펙(1시간 유효)을 자동으로 사용합니다.

동적 명령어가 보이지 않음

solcrm auth login으로 먼저 로그인하세요. 동적 명령어(records, entities 등)는 인증 후 활성화됩니다.

FAQ

Q: 여러 SOLAPI 계정을 동시에 관리할 수 있나요? 네, 프로필을 사용하세요. solcrm auth login --profile work로 추가, solcrm auth use work로 전환합니다.

Q: 환경변수와 저장된 프로필 중 어느 것이 우선인가요? 환경변수(SOLAPI_API_KEY 등)가 우선입니다. 환경변수가 있으면 저장된 프로필을 무시합니다.

Q: 오프라인에서 사용 가능한가요? OpenAPI 스펙 캐시(1시간 TTL)가 있으면 가능합니다. 새 API는 인터넷 연결 후 캐시 갱신이 필요합니다.

라이선스

MIT