Preview — 이 프로젝트는 현재 프리뷰 단계입니다. API와 CLI 인터페이스가 변경될 수 있습니다.
SOLAPI 메시징 플랫폼을 위한 CLI 도구입니다.
Linux와 macOS를 우선 지원합니다.
| 플랫폼 | 아키텍처 | 지원 |
|---|---|---|
| Linux | amd64, arm64 | 우선 지원 |
| macOS | amd64 (Intel), arm64 (Apple Silicon) | 우선 지원 |
| Windows | amd64, arm64 | 바이너리 제공 (제한적 테스트) |
모든 설치 방법은 관리자 권한 없이 사용자 영역에 설치됩니다.
curl -fsSL https://raw.githubusercontent.com/solapi/solactl/main/scripts/install.sh | bash- 설치 경로:
~/.local/bin/solactl - 체크섬(SHA256) 검증 후 압축 해제
PATH에 포함되어 있지 않으면 셸 설정 파일(~/.zshrc/~/.bashrc) 등록 안내 출력
winget처럼 사용자 영역에만 설치되며 관리자 권한이 필요하지 않습니다. PowerShell 5.1 이상(또는 PowerShell 7+) 에서 실행하세요.
irm https://raw.githubusercontent.com/solapi/solactl/main/scripts/install.ps1 | iex- 설치 경로:
%LOCALAPPDATA%\Programs\solactl\solactl.exe - 체크섬(SHA256) 검증 후 zip 압축 해제
- 사용자
PATH(HKCU\Environment\Path) 에 설치 디렉터리를 자동 추가 — 새 터미널부터 적용 - 실행 중인
solactl.exe가 잠겨 있으면 기존 파일을solactl.exe.old로 옮긴 뒤 교체
특정 버전 고정 / 설치 경로 지정이 필요하면 스크립트를 로컬에 받아 인자로 실행합니다.
# 스크립트 다운로드 후 실행
Invoke-WebRequest -UseBasicParsing `
-Uri https://raw.githubusercontent.com/solapi/solactl/main/scripts/install.ps1 `
-OutFile $env:TEMP\install.ps1
# 특정 버전 설치
powershell -ExecutionPolicy Bypass -File $env:TEMP\install.ps1 -Version v0.1.6
# 설치 경로 변경
powershell -ExecutionPolicy Bypass -File $env:TEMP\install.ps1 -InstallDir D:\tools\solactl
irm | iex한 줄 설치는 메모리에서 실행되므로 별도의 ExecutionPolicy 설정이 필요하지 않습니다.
git clone https://github.com/solapi/solactl.git
cd solactl
make build # bin/solactl 생성
make install # $GOPATH/bin에 설치설치된 solactl 자체에서 업그레이드할 수 있습니다. 모든 플랫폼 공통입니다.
solactl upgrade또는 위의 설치 스크립트를 다시 실행해도 됩니다.
릴리스의 checksums.txt 는 cosign keyless 로 서명됩니다. 일반 설치 경로는 SHA256 체크섬만 검증하지만, 추가 보증이 필요하면 cosign 으로 서명을 검증할 수 있습니다.
검증 절차와 신뢰 모델은 VERIFYING.md 를 참고하세요.
# 초기 설정 (API Key / Secret)
solactl configure
# SMS 발송
solactl send sms --to 01012345678 --text "안녕하세요"
# 발신번호 목록
solactl senderid list
# 발송 내역 조회
solactl messages list
# 발송 내역 export (CSV/JSON/JSONL)
solactl messages export --output messages.csv
# 일별 통계 export (CSV/JSON/JSONL)
solactl statistics export-daily --output stats.csv \
--start-date 2026-05-04 --end-date 2026-05-11
# 잔액 조회
solactl balance
# 발송 한도 조회 / 증가 요청
solactl quota get
solactl quota request --target 5000 --reason "..."
solactl quota list-requests자세한 사용법은 solactl --help 또는 각 서브커맨드의 --help를 참조하세요.
solactl quota request 로 발송 한도 증가를 요청할 수 있습니다. 요청은 SOLAPI 운영팀의 검토를 거쳐 승인 또는 반려됩니다.
요청 사유에 실제 발송할 메시지 본문을 그대로 적으세요. 검토자가 발송 의도와 컨텍스트를 즉시 확인할 수 있어 승인이 가장 빨라집니다.
--reason 에 다음 정보를 가능한 한 구체적으로 포함하세요.
- 수신자 — 누구에게 보내는지, 수신 동의를 어떻게 확보했는지
- 메시지 본문 — 실제로 발송할 내용 전문 또는 핵심 예시 (광고성 메시지면 광고 표기 포함 여부)
- 발송 일정 / 규모 — 캠페인 일자, 1일 / 1회 예상 발송 건수
- 비즈니스 사유 — 한도 증액이 필요한 이유 (이벤트, 정기 알림 등)
잘 작성된 사유 (승인 빠름)
solactl quota request --target 5000 --reason "$(cat <<EOF
대상: 자사몰 회원 4,800명 (가입 시 마케팅 수신 동의 보유)
내용: '[OO몰] 5월 단독 세일 안내. 회원 한정 30% 쿠폰: <링크>'
발송 시점: 2026-05-15 14:00 일회성, 약 4,800건
사유: 정기 캠페인 발송으로 일일 한도 초과 예상
EOF
)"부족한 사유 (반려되거나 추가 확인 필요)
solactl quota request --target 5000 --reason "이벤트 발송"→ 수신자 / 메시지 본문 / 발송 시점이 모두 누락되어 검토자가 판단하기 어렵습니다.
solactl quota get # 현재 한도 확인
solactl quota list-requests # 모든 요청 이력
solactl quota list-requests --status PENDING # 검토 대기 중인 요청만상태값은 PENDING (검토 대기) → APPROVED (승인) 또는 REJECTED (반려) 로 변경됩니다.
주의 — 동일 계정에 PENDING 요청이 이미 있을 때 새 요청을 제출하면 이전 요청은 자동으로 REJECTED 처리됩니다.
대량 export는 messages-v4 부하를 줄이기 위해 다음 가드를 자동 적용합니다.
- 6개월(180일) 이전 데이터는 조회 불가 — 사내 DB에서 자동 삭제됩니다.
- 7일 초과 범위는 1일 단위 윈도우로 자동 분할 — UTC 자정 기준으로 잘게 호출.
--throttle(기본 500ms) — 페이지/윈도우 호출 사이 sleep. 최소 100ms 강제.--page-size강제 상한 —messages export200,statistics export-daily100.- Ctrl+C 시 부분 결과 보존 — stderr에
--resume-token안내. 다음 명령에--append --resume-token <토큰>을 붙여 이어받을 수 있습니다.
# 기본: 최근 7일, CSV, page-size 50, throttle 500ms
solactl messages export --output messages.csv
# 31일 범위 — 자동으로 31개 1일 윈도우로 분할
solactl messages export --output messages.csv \
--start-date 2026-04-02 --end-date 2026-05-03
# JSONL 포맷 + 필터
solactl messages export --output messages.jsonl --format jsonl \
--type SMS --status-code 4000 --from 029302266
# 중단 후 재개
solactl messages export --output messages.csv --append \
--resume-token eyJ2IjoxLCJ3IjoiMjAyNi0wNS0wMSJ9CSV 컬럼: messageId, type, status, statusCode, to, from, country, subject, dateCreated, dateUpdated, groupId, accountId, text, customFields.
# 7일 범위
solactl statistics export-daily --output stats.csv \
--start-date 2026-05-04 --end-date 2026-05-11
# 31일 범위 — 자동 일별 분할
solactl statistics export-daily --output stats.csv \
--start-date 2026-04-02 --end-date 2026-05-03
# Windows Excel 한글 호환 (UTF-8 BOM)
solactl statistics export-daily --output stats.csv \
--start-date 2026-05-04 --end-date 2026-05-11 --bomCSV는 고정 prefix (date, accountId, prepaid, balance, point, profit, refundBalance, refundPoint) + 응답에서 발견된 모든 count.* 키를 정렬해 컬럼화 (count_SMS, count_LMS, count_MMS, ...).