About-Intelligence/soku-cli

Soku CLI – a secure command‑line bridge for AI agents

What it is

• A Node‑based command‑line tool (@soku-ai/cli) that lets large‑language‑model agents (Claude, Codex, Cursor, etc.) talk directly to the services in a Soku workspace – ad platforms, analytics, SEO hosting, automation, and more.
• The CLI turns the capabilities exposed by Soku’s backend into typed, discoverable shell commands and returns a stable JSON envelope that agents can parse without human interaction.

Why it matters

• One unified interface for a growth‑stack: Google Ads, Meta Ads, TikTok, GA4, PostHog, SEO hosting, etc., all reachable via the same soku … commands.
• Agent‑first design – commands are self‑documenting, non‑interactive, and output JSON ({"ok":true,"data":…}) so an LLM can call them programmatically and handle errors reliably.
• Credential safety – authentication is handled by Soku; API keys never appear in prompts.
• Human‑in‑the‑loop writes – any operation that changes ad delivery creates a review request that must be approved manually before execution.

Getting started

1. Install globally with npm install -g @soku-ai/cli (Node 20+ required) or run via npx.
2. Log in using soku auth login (browser‑based device flow).
3. Select a workspace (soku workspace resolve <brand> → soku workspace use-brand <brand>).
4. Install the needed “skills” (business‑specific command sets) with soku skill install <slug> or soku skill install --all --global.
5. Run soku --help to see the full command tree.

Typical use cases

Goal	Example command	What it does
Query ad performance	soku ads query-single-dimension --platform google --account-id 123 --dimension campaign --date-start 2026-06-01 --date-end 2026-06-30	Retrieves campaign‑level metrics from Google Ads and returns JSON.
Combine acquisition & product data	soku ga4 list-properties → soku posthog query --project-id xyz --tool execute-sql --arguments '{"query":"SELECT count() FROM events WHERE event = \"$pageview\""}'	Pulls GA4 property info and runs a SQL‑like query on PostHog events, enabling an agent to trace spend → traffic → in‑product behavior.
Create a new ad campaign (human‑approved)	soku ads meta campaign create --account-id 456 --name "Launch Test" --objective OUTCOME_TRAFFIC --summary "Create paused Meta traffic campaign Launch Test"	Generates a review ID; the agent can present the plan, and a human later runs soku review approve <id>.
Publish SEO content	soku seo-hosting pages put --section blog --slug launch-notes --title "Launch notes" --html-file page.html followed by soku seo-hosting pages publish --section blog --slug launch-notes	Stages and publishes a static HTML page via Soku’s SEO hosting service.
Schedule recurring agent work	soku automation create --name "Weekly account health" --prompt "Review paid acquisition performance and flag anomalies" --cron "0 9 * * 1" --timezone America/Los_Angeles	Sets up a cron‑like automation that an LLM will run weekly.
Provide context files	soku context upload ./campaign-brief.pdf --dir research	Uploads a PDF to the workspace’s Context Hub so agents can reference it when answering questions.

How it works under the hood

• The CLI calls Soku’s /api/cli/* endpoints; no separate MCP host is required.
• Typed commands are generated automatically from src/generated/capabilities.json, which mirrors the backend capability registry.
• For capabilities that lack a friendly typed command, the generic soku call <namespace> <action> … syntax can be used.
• Credential storage uses the optional keytar library; if unavailable, it falls back to a file‑based store.

Development & contribution

• Built with TypeScript, ESM, and NodeNext module resolution.
• Standard scripts: pnpm install, pnpm typecheck, pnpm test, pnpm build.
• Tests live alongside source files (*.test.ts) and run with Node’s built‑in test runner.
• Contributions are welcomed via the usual GitHub workflow; see CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md for guidelines.

Bottom line Soku CLI is a practical bridge that lets AI agents act on real‑world marketing and analytics tools safely and transparently, turning a complex growth stack into a set of predictable, JSON‑driven shell commands.