菜单
Install and use Soku CLI to give AI agents secure command-line access to marketing data, ad platforms, GA4, PostHog, and growth automation.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Aradotso/devtools-skills --skill soku-cli-integration命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | soku-cli-integration |
| description | Install and use Soku CLI to give AI agents secure command-line access to marketing data, ad platforms, GA4, PostHog, and growth automation. |
| triggers | ["install soku cli","query google ads data","access ga4 analytics","automate marketing tasks","publish seo content with soku","manage ad campaigns through soku","connect to posthog with soku","use soku for growth stack"] |
Skill by ara.so — Devtools Skills collection.
Soku CLI is a command-line interface that provides secure, typed access to your entire growth stack—Google Ads, Meta Ads, GA4, PostHog, SEO hosting, and more—without exposing API keys in prompts or requiring MCP hosts. Commands are self-documenting and return stable JSON envelopes that AI agents can parse reliably. All delivery-changing writes (like creating campaigns) go through a human review gate.
Key capabilities:
npm install -g @soku-ai/cli
npx @soku-ai/cli --help
soku --version
soku auth login
This opens a browser for OAuth authentication. The CLI stores credentials securely (using keytar when available, or encrypted file storage as fallback).
soku auth status
# Search for your brand workspace
soku workspace resolve <brand-name>
# Use the brand workspace
soku workspace use-brand <brand-name>
# Verify active workspace
soku workspace status
soku auth logout
All commands follow a consistent pattern:
soku <namespace> <action> [options]
Namespaces:
auth - Authentication managementworkspace - Organization/brand contextads - Advertising platformsga4 - Google Analytics 4posthog - PostHog analyticsseo-hosting - SEO page managementautomation - Scheduled taskscontext - Context Hub file managementegress - Third-party API callsreview - Human approval workflowskill - Agent skill managementsoku --help
soku ads --help
soku ads query-single-dimension --help
# Google Ads
soku ads list-ad-accounts --platform google
# Meta Ads
soku ads list-ad-accounts --platform meta
# All platforms
soku ads list-ad-accounts
soku ads query-single-dimension \
--platform google \
--account-id 123-456-7890 \
--dimension campaign \
--date-start 2026-06-01 \
--date-end 2026-06-30
Available dimensions: campaign, ad_group, ad, keyword
soku ads query-two-dimension \
--platform google \
--account-id 123-456-7890 \
--dimension-one campaign \
--dimension-two ad_group \
--date-start 2026-06-01 \
--date-end 2026-06-30
For custom breakdowns beyond standard dimensions:
soku ads google gaql \
--account-id 123-456-7890 \
--query "SELECT campaign.name, metrics.impressions, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS"
soku ads meta campaign create \
--account-id act_123456789 \
--name "Q3 Product Launch" \
--objective OUTCOME_TRAFFIC \
--summary "Create paused Meta traffic campaign for Q3 launch"
This returns a review ID instead of executing immediately:
{
"ok": true,
"data": {
"review_id": "rev_abc123",
"status": "pending"
}
}
# View the pending change
soku review show rev_abc123
# Approve it
soku review approve rev_abc123
# Or reject it
soku review reject rev_abc123 --reason "Budget needs adjustment"
# List all pending reviews
soku review list --status pending
# List properties
soku ga4 list-properties
# Get property overview
soku ga4 get-property-overview --property-id 123456789
# List traffic sources
soku ga4 list-traffic-sources \
--property-id 123456789 \
--start-date 2026-06-01 \
--end-date 2026-06-30
# Get conversion events
soku ga4 list-conversion-events --property-id 123456789
# List projects
soku posthog list-projects
# Execute SQL query
soku posthog query \
--project-id 12345 \
--tool execute-sql \
--arguments '{"query":"SELECT event, count() as count FROM events WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY event ORDER BY count DESC LIMIT 10"}'
# Get insights
soku posthog query \
--project-id 12345 \
--tool get-insights \
--arguments '{"filters":{"date_from":"-7d"}}'
# Stage a page
soku seo-hosting pages put \
--section blog \
--slug product-launch-2026 \
--title "Product Launch Notes" \
--html-file ./content/launch.html
# Publish it live
soku seo-hosting pages publish \
--section blog \
--slug product-launch-2026
# List all pages
soku seo-hosting pages list --section blog
# Get page details
soku seo-hosting pages get \
--section blog \
--slug product-launch-2026
# List domains
soku seo-hosting domains list
# Add a domain
soku seo-hosting domains add \
--domain blog.example.com \
--section blog
# Weekly performance review
soku automation create \
--name "Weekly ad account health check" \
--prompt "Review all active ad accounts, identify campaigns with declining performance, and flag anomalies for human review" \
--cron "0 9 * * 1" \
--timezone America/Los_Angeles
# Daily budget monitor
soku automation create \
--name "Daily budget utilization" \
--prompt "Check yesterday's spend across all platforms and alert if any account spent >110% or <70% of daily budget" \
--cron "0 8 * * *" \
--timezone America/New_York
# List all automations
soku automation list
# Get automation details
soku automation get --id auto_abc123
# Pause an automation
soku automation pause --id auto_abc123
# Resume an automation
soku automation resume --id auto_abc123
# Delete an automation
soku automation delete --id auto_abc123
Manage files that agents can use as context:
# Upload a file
soku context upload ./campaign-brief.pdf --dir research
# Upload multiple files
soku context upload ./docs/*.md --dir documentation
# List files
soku context list
# List files in specific directory
soku context list --dir research
# Download a file
soku context download campaign-brief.pdf --output ./local-copy.pdf
# Delete a file
soku context delete campaign-brief.pdf --dir research
Install workflow skills to give agents structured knowledge:
# Install all available skills globally
soku skill install --all --global
# Install specific skill
soku skill install soku-ads-reporting --global
# List installed skills
soku skill list
# Check skill status
soku skill status
# Update skills
soku skill update --all
The meta skill is available at skills/soku/SKILL.md in the installation directory.
In non-interactive environments, all commands return structured JSON:
{
"ok": true,
"data": {
"accounts": [
{
"id": "123-456-7890",
"name": "Main Account",
"platform": "google"
}
]
}
}
{
"ok": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Session expired. Run 'soku auth login'"
}
}
import { exec } from 'node:child_process';
import { promisify } from 'node:util';
const execAsync = promisify(exec);
async function getAdAccounts(platform: string) {
try {
const { stdout } = await execAsync(
`soku ads list-ad-accounts --platform ${platform}`
);
const response = JSON.parse(stdout);
if (!response.ok) {
throw new Error(response.error.message);
}
return response.data.accounts;
} catch (error) {
console.error('Failed to fetch ad accounts:', error);
throw error;
}
}
// Usage
const accounts = await getAdAccounts('google');
console.log(`Found ${accounts.length} accounts`);
#!/bin/bash
# Get accounts and extract IDs
ACCOUNTS=$(soku ads list-ad-accounts --platform google)
if [ "$(echo "$ACCOUNTS" | jq -r '.ok')" = "true" ]; then
echo "$ACCOUNTS" | jq -r '.data.accounts[].id' | while read -r account_id; do
echo "Processing account: $account_id"
soku ads query-single-dimension \
--platform google \
--account-id "$account_id" \
--dimension campaign \
--date-start "2026-06-01" \
--date-end "2026-06-30"
done
else
echo "Error: $(echo "$ACCOUNTS" | jq -r '.error.message')"
exit 1
fi
If a capability doesn't have a typed command yet, use soku call:
# Discover capabilities
soku call --help
# Call with snake_case capability name
soku call ads list_ad_accounts -p platform=google
# Multiple parameters
soku call ads query_single_dimension \
-p platform=google \
-p account_id=123-456-7890 \
-p dimension=campaign \
-p date_start=2026-06-01 \
-p date_end=2026-06-30
# Get help for specific capability
soku call ads list_ad_accounts --help
async function generateWeeklyReport() {
// Get all ad accounts
const googleAccounts = await execSoku('ads list-ad-accounts --platform google');
const metaAccounts = await execSoku('ads list-ad-accounts --platform meta');
// Query last 7 days for each account
const reports = [];
for (const account of [...googleAccounts, ...metaAccounts]) {
const data = await execSoku(`ads query-single-dimension \
--platform ${account.platform} \
--account-id ${account.id} \
--dimension campaign \
--date-start ${sevenDaysAgo()} \
--date-end ${today()}`);
reports.push({ account: account.name, data });
}
// Analyze and format
return formatReport(reports);
}
async function launchCampaign(config: CampaignConfig) {
// 1. Create campaign (returns review ID)
const createResult = await execSoku(`ads meta campaign create \
--account-id ${config.accountId} \
--name "${config.name}" \
--objective ${config.objective} \
--summary "${config.summary}"`);
const reviewId = createResult.data.review_id;
// 2. Show review to user
console.log('Campaign ready for review:');
const review = await execSoku(`review show ${reviewId}`);
console.log(JSON.stringify(review.data, null, 2));
// 3. Human approves via CLI or returns approval decision
const approved = await askHumanForApproval();
if (approved) {
await execSoku(`review approve ${reviewId}`);
console.log('Campaign launched!');
} else {
await execSoku(`review reject ${reviewId} --reason "Needs budget adjustment"`);
}
}
async function compareAdPlatforms(startDate: string, endDate: string) {
const platforms = ['google', 'meta', 'tiktok'];
const results = {};
for (const platform of platforms) {
const accounts = await execSoku(`ads list-ad-accounts --platform ${platform}`);
let totalSpend = 0;
let totalConversions = 0;
for (const account of accounts.data.accounts) {
const metrics = await execSoku(`ads query-single-dimension \
--platform ${platform} \
--account-id ${account.id} \
--dimension campaign \
--date-start ${startDate} \
--date-end ${endDate}`);
totalSpend += sumMetric(metrics.data, 'spend');
totalConversions += sumMetric(metrics.data, 'conversions');
}
results[platform] = {
spend: totalSpend,
conversions: totalConversions,
cpa: totalSpend / totalConversions
};
}
return results;
}
Problem: Session expired or UNAUTHORIZED errors
# Sign out and back in
soku auth logout
soku auth login
# Verify status
soku auth status
Problem: Browser doesn't open during login
# The CLI will display a URL to visit manually
# Copy the URL from the terminal and open it in your browser
Problem: No workspace selected
# Check current workspace
soku workspace status
# List available workspaces
soku workspace list
# Select a workspace
soku workspace use-brand <brand-name>
Problem: Typed command doesn't exist yet for new capability
# Use direct capability call instead
soku call <namespace> <action> --help
soku call <namespace> <action> -p key=value
Problem: Review ID returned but want to skip review (for testing)
# Reviews are intentional for delivery-changing operations
# Always approve/reject properly to maintain audit trail
soku review approve <review_id>
Problem: Malformed JSON output
# Ensure you're in non-interactive mode
# Interactive prompts can interfere with JSON output
# Set CI environment or redirect stderr
soku ads list-ad-accounts 2>/dev/null
Problem: FORBIDDEN or missing capabilities
# Check workspace permissions
soku workspace status
# Ensure you're using correct workspace
soku workspace use-brand <correct-brand>
# Some capabilities require specific Soku plan features
# Contact workspace admin to verify feature availability
Problem: RATE_LIMIT_EXCEEDED errors
# Soku handles third-party rate limits
# Add delays between bulk operations
sleep 1
Soku CLI respects standard environment variables:
NODE_ENV - Set to production to suppress dev warningsCI - Set to true to force non-interactive modeNO_COLOR - Set to disable colored outputSOKU_API_URL - Override API endpoint (advanced use)soku auth status before executing workflowsresponse.ok before accessing response.datasoku callsoku workspace statussoku skill install --all --global during setup--summary flag for writes should explain WHYWhen developing scripts that use Soku CLI:
// Check if Soku CLI is available
import { exec } from 'node:child_process';
async function checkSokuCLI() {
try {
await execAsync('soku --version');
return true;
} catch {
console.error('Soku CLI not found. Install: npm install -g @soku-ai/cli');
return false;
}
}
// Test with dry-run patterns
async function testCampaignCreate(config: any) {
// Create returns review ID - safe to test
const result = await execSoku(`ads meta campaign create \
--account-id ${config.accountId} \
--name "TEST ${config.name}" \
--objective ${config.objective} \
--summary "Test campaign - do not approve"`);
// Review but don't approve
const reviewId = result.data.review_id;
console.log(`Test review created: ${reviewId}`);
console.log('Remember to reject this review');
return reviewId;
}