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

지원

• GitHub Issues: https://github.com/nurigo/solapi-crm-core/issues
• SOLAPI 지원: https://solapi.com/support
• 문서: https://developers.solapi.com/crm/cli