npm package: @solapi/crm-cli
Description: SOLAPI CRM CLI - 터미널에서 CRM을 관리하고, AI Agent와 연동하세요
Latest version: 0.0.2

# SOLAPI CRM CLI

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

## 핵심 특징

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


## Quick Start

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

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

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


## 설치

### npm (권장)

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

### npx (설치 없이 즉시 실행)

```bash
npx @solapi/crm-cli --help
```

### Node.js 요구사항

- Node.js 18.0 이상


## 인증 설정

### 대화형 로그인

```bash
solcrm auth login
```

다음 두 가지를 입력합니다:
- **API Key**: `NCS...` (SOLAPI 콘솔 → API Key 관리에서 발급)
- **API Secret**: `***` (마스킹 입력)

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

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

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

### 환경변수 설정 (Docker/CI)

```bash
export SOLAPI_API_KEY=NCSXXX
export SOLAPI_API_SECRET=XXX

solcrm records list --entityId ENxxx
```

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

### 프로필 관리

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

```bash
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 패턴

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

### 사용 예시

```bash
# 개체 목록
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).

```bash
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시간 동안 로컬 캐시합니다.

```bash
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):

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

### Claude Code 설정

```bash
claude mcp add solapi-crm -- solcrm --mcp
```

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

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

### npx로 설치 없이 MCP 연동

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

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

```json
{
  "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 스펙에서 자동 생성)


## 문제 해결

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

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

### "API 오류 (401/403)"

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

### "OpenAPI spec 로딩 실패"

```bash
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