About-Intelligence/soku-cli

Soku CLI – AI 에이전트를 위한 안전한 명령줄 브리지

개요

• Node 기반 명령줄 도구 (@soku-ai/cli)로, 대규모 언어 모델 에이전트(Claude, Codex, Cursor 등)가 Soku 워크스페이스 내의 서비스(광고 플랫폼, 분석, SEO 호스팅, 자동화 등)와 직접 대화할 수 있도록 합니다.
• 이 CLI는 Soku 백엔드가 노출하는 기능을 타입이 지정되고 탐색 가능한 셸 명령으로 변환하며, 에이전트가 사람의 개입 없이 구문 분석할 수 있는 안정적인 JSON 봉투를 반환합니다.

중요성

• 통합 인터페이스: Google Ads, Meta Ads, TikTok, GA4, PostHog, SEO 호스팅 등 성장 스택을 모두 동일한 soku … 명령으로 액세스할 수 있습니다.
• 에이전트 우선 설계 – 명령은 자체 문서화되어 있고 비대화형이며 JSON ({"ok":true,"data":…})을 출력하므로, LLM이 프로그래밍 방식으로 호출하고 오류를 안정적으로 처리할 수 있습니다.
• 자격 증명 안전성 – 인증은 Soku가 처리하며, API 키가 프롬프트에 노출되지 않습니다.
• 사람이 개입하는 쓰기 작업 – 광고 게재를 변경하는 모든 작업은 검토 요청을 생성하며, 실행 전에 수동으로 승인해야 합니다.

시작하기

1. npm install -g @soku-ai/cli로 전역 설치(Node 20+ 필요)하거나 npx를 통해 실행합니다.
2. soku auth login을 사용하여 로그인합니다(브라우저 기반 장치 흐름).
3. 워크스페이스를 선택합니다 (soku workspace resolve <brand> → soku workspace use-brand <brand>).
4. 필요한 "스킬"(비즈니스별 명령 세트)을 soku skill install <slug> 또는 soku skill install --all --global로 설치합니다.
5. soku --help를 실행하여 전체 명령 트리를 확인합니다.

일반적인 사용 사례

목표	명령 예시	기능
광고 성과 쿼리	soku ads query-single-dimension --platform google --account-id 123 --dimension campaign --date-start 2026-06-01 --date-end 2026-06-30	Google Ads에서 캠페인 수준 지표를 검색하고 JSON을 반환합니다.
획득 및 제품 데이터 결합	soku ga4 list-properties → soku posthog query --project-id xyz --tool execute-sql --arguments '{"query":"SELECT count() FROM events WHERE event = \"$pageview\""}'	GA4 속성 정보를 가져오고 PostHog 이벤트에서 SQL 쿼리를 실행하여 지출 → 트래픽 → 제품 내 행동을 추적할 수 있게 합니다.
새 광고 캠페인 생성(사람 승인 필요)	soku ads meta campaign create --account-id 456 --name "Launch Test" --objective OUTCOME_TRAFFIC --summary "Create paused Meta traffic campaign Launch Test"	검토 ID를 생성합니다. 에이전트가 계획을 제시하고, 나중에 사람이 soku review approve <id>를 실행합니다.
SEO 콘텐츠 게시	soku seo-hosting pages put --section blog --slug launch-notes --title "Launch notes" --html-file page.html 후 soku seo-hosting pages publish --section blog --slug launch-notes	Soku의 SEO 호스팅 서비스를 통해 정적 HTML 페이지를 스테이징하고 게시합니다.
반복적인 에이전트 작업 예약	soku automation create --name "Weekly account health" --prompt "Review paid acquisition performance and flag anomalies" --cron "0 9 * * 1" --timezone America/Los_Angeles	LLM이 매주 실행할 cron 스타일의 자동화를 설정합니다.
컨텍스트 파일 제공	soku context upload ./campaign-brief.pdf --dir research	PDF를 워크스페이스의 Context Hub에 업로드하여 에이전트가 질문에 답할 때 참조할 수 있도록 합니다.

작동 원리

• CLI는 Soku의 /api/cli/* 엔드포인트를 호출하며, 별도의 MCP 호스트가 필요하지 않습니다.
• 타입이 지정된 명령은 src/generated/capabilities.json에서 자동으로 생성되며, 이는 백엔드 기능 레지스트리를 반영합니다.
• 적절한 타입 명령이 없는 기능의 경우, 일반적인 soku call <namespace> <action> … 구문을 사용할 수 있습니다.
• 자격 증명 저장은 선택적 keytar 라이브러리를 사용하며, 사용할 수 없는 경우 파일 기반 저장소로 대체됩니다.

개발 및 기여

• TypeScript, ESM, NodeNext 모듈 해석을 사용하여 구축되었습니다.
• 표준 스크립트: pnpm install, pnpm typecheck, pnpm test, pnpm build.
• 테스트는 소스 파일과 함께 위치하며 (*.test.ts) Node의 내장 테스트 러너로 실행됩니다.
• GitHub 워크플로우를 통한 기여를 환영합니다. 가이드라인은 CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md를 참조하세요.

결론 Soku CLI는 AI 에이전트가 실제 마케팅 및 분석 도구를 안전하고 투명하게 조작할 수 있도록 하는 실용적인 브리지이며, 복잡한 성장 스택을 예측 가능하고 JSON 기반의 셸 명령 세트로 변환합니다.