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駆動のシェルコマンドセットに変換します。