Soku is the AI marketing agent for ads and creatives. This plugin brings it into your coding agent: analyze performance across Google, Meta, TikTok and ChatGPT Ads, GA4 and PostHog, audit spend, research competitors, publish SEO pages, and prepare campaign changes for your approval.

version
0.1.0-alpha.27
GitHub stars
302

Install

/plugin install soku@soku

Run it inside Claude Code after adding the marketplace with /plugin marketplace add About-Intelligence/soku-cli.

Contents

Discovered from source

Skills 1

Soku CLI

Written against Soku CLI release 0.1.0-alpha.29. If soku --version reports a newer release, run soku changelog --since that release before relying on details here.

The soku CLI is the shell-native way for an AI agent to use Soku from your coding agent or any terminal. It talks to Soku over /api/cli/*; the CLI path needs no MCP host. Treat this file as the router. Load the relevant reference file before acting on a detailed workflow. If you have no usable shell, skip to "No Shell? Use the Soku MCP Connection".

Reference Router

Read only the reference files needed for the user's task:

TaskRead
First-time setup, expired token, workspace selection, org/brand ambiguityreferences/auth-workspace.md
Ads, GA4, or PostHog reads; raw soku call; command discoveryreferences/data-capabilities.md and references/capability-flow.md
Meta/Google/ChatGPT Ads writes, image/video uploads, video ads from local files, bulk create, review-gated approvalreferences/ads-write.md
SEO Hosting, automations, Context Hub files, temporary public file URLsreferences/seo-automation-files.md
Third-party APIs through server-side credential injection; what calls cost and soku credits; security rulesreferences/egress-security.md
Installing, updating, or removing Soku-managed local skills; finding out what an upgrade changedreferences/skills-updates.md

For an installed business skill such as soku-ads-report, read that skill too. Business skills carry their own "Running this skill with the Soku CLI" section.

Prerequisite: The CLI Must Be Installed

This skill only describes the soku command; it does not contain it. Check first:

soku --version

If the command is missing, install it (Node.js 20 or newer is required) and check again:

npm i -g @soku-ai/cli
soku --version

If npm says @soku-ai/cli is not found, report that the official package is unavailable. Do not invent an unofficial package name.

When this skill arrived as a marketplace plugin, the CLI may also have installed its own copy under ~/.claude/skills/soku/, ~/.codex/skills/soku/, or ~/.cursor/skills/soku/. Both copies are the same document at possibly different versions. The copy the CLI installed is refreshed together with the binary, so when the two disagree, prefer that one, and treat soku --help and soku changelog as the authority over either copy.

No Shell? Use the Soku MCP Connection

Some hosts cannot run the CLI: Claude Cowork and claude.ai have no local shell, and a sandboxed environment may block npm or api.soku.ai. For those hosts the Claude Code plugin also registers Soku's remote MCP server (name soku, https://api.soku.ai/mcp, OAuth). Rules for that path:

  • Sign in through the host's MCP authentication, never by pasting a token: in Claude Code run /mcp (or claude mcp login soku from a shell); in Cowork approve the Soku connector when the host asks. Both open a Soku login page.
  • The MCP tools cover brand-scoped reads, research and generation. Writes on MCP are limited to what Soku Connect publishes (today the creatives canvas operations); they are review-gated, and Soku returns a Live Surface link where a human approves them. Hand that link to the user; do not try to approve on their behalf. Ads and SEO Hosting writes are CLI-only.
  • Local skill installation, Context Hub uploads from local files, memory and soku review wait exist only on the CLI. When a shell is available and soku can be installed, prefer the CLI.

Default Flow

  1. Check auth/workspace state:
soku auth status
soku workspace status
  1. If auth is missing or expired, use the agent split-flow from references/auth-workspace.md.

  2. If the workspace is not ready, resolve and select the remote Soku brand:

soku workspace resolve <brand>
soku workspace use-brand <brand>
  1. Pick the reference for the task. Do not infer Soku org/brand from the current local repo directory.

  2. Inspect command help before unfamiliar calls:

soku --help
soku <namespace> --help
soku <namespace> <action> --help
  1. Run the command and parse JSON output. In non-TTY contexts, success is {"ok":true,"data":...} and errors are {"ok":false,"error":...}.

Non-Negotiable Rules

  • Confirm the target brand immediately before any write, and read it back after. Run soku workspace status in the same turn as the write — not earlier in the session — and check the reported brand is the one the user named (its source field tells you whether saved config or a SOKU_BRAND_ID environment variable decided it, which is what you would have to change). The CLI keeps whatever brand was selected last, and it does not follow the brand the user is looking at in the web app, so a brand confirmed three turns ago proves nothing about this write. After the write, read the object back (soku automation get, soku context list, soku seo-hosting pages list) and confirm it landed where you intended. A write into the wrong brand succeeds silently and looks identical to a correct one; the read-back is the only thing that tells them apart.
  • Never print or persist the Soku access token.
  • Never ask the user to paste third-party provider keys for covered providers.
  • Do not fail just because an upstream provider key env var is unset. Use soku egress -- curl ... for covered third-party APIs.
  • A human authorizes every review-gated write, in Soku, not through you. The pending response carries approve_url (this review) and inbox_url (every pending review in the brand). Give the user the link with one line on what they are approving, then run soku review wait <review_id> to continue once they decide; it exits 5 if they deny it or the write fails. For several reviews, send the inbox link and wait on all ids at once. Never run soku review approve/deny yourself and never allowlist them — they are for a person deciding in their own terminal. If a pending response has no approve_url (an older Soku API), ask the user to run soku review approve <review_id> themselves.
  • A write the user chose to "Always approve" in Soku comes back as a normal result marked auto_approved instead of a pending review. Treat it like any other executed write: read it back before telling the user it landed.
  • An ads write that names an existing campaign / ad set / ad group / ad must read that object back first and quote its current name and literal id in --summary; the server rejects a summary that omits a literal target id.
  • Pass user values as separate argv elements. Do not build a shell command by string-concatenating untrusted values.
  • Do not scan local repo files, AGENTS.md, or context/ folders for Soku workspace state unless the user explicitly asks about local files.
  • When a command prints a hint, follow it before retrying. Do not loop blindly.

Exit Codes

ExitMeaningWhat to do
0SuccessParse data.
1Usage or no workspaceFix args, or run soku workspace status / use-brand.
2Auth missing, expired, or revokedRun soku auth login --no-wait.
4Not found or unknown capabilityRe-check soku --help / soku <ns> --help.
5Runtime or network failureRetry if transient; if behind a proxy set ALL_PROXY.

Capability Discovery

Typed command names are kebab-case:

soku ads query-single-dimension --help

Raw soku call action names use registry snake_case:

soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'

Prefer typed commands when they exist. Use soku call only as a forward-compatible escape hatch for a newer action or an action not yet exposed ergonomically.

For generated multi-platform commands, select --platform first. Parameter requirements follow that platform: Meta does not require TikTok scheduling, budget, or creatives fields. Help labels platform-specific requirements; passing a field for another platform is rejected before any request.

Installed Skill Names

The bundled CLI meta skill is named soku. Business skills are installed with a Soku prefix, for example soku-ads-report and soku-google-ads.

soku skill list
soku skill install ads-report google-ads
soku skill status

When asking an AI client to invoke a business skill, write use @soku-ads-report skill, not @ads-report.

Updating This Skill

soku update skills refreshes the bundled soku meta skill and every installed Soku-managed business skill recorded in .soku-skills.json. It also refreshes legacy meta-only installs that have soku/SKILL.md but no manifest, so older installations receive this references/ directory.

soku update cli also silently refreshes an already-installed global soku meta skill as an npm postinstall side effect. Its JSON result carries mustRereadMetaSkill: true plus metaSkillRefreshed: [<paths>] when that happened. After running soku update cli, check that field: if true, re-read this file (and references/) from the listed path before continuing — do not keep acting on this session's previously loaded copy of this skill.

MCP servers 1

Sponsors

Details

Marketplace
About-Intelligence/soku-cli
Author
About Intelligence
Category
Productivity
License
MIT
Keywords
soku, marketing, ai-marketing-agent, ads, ad-creatives, google-ads, meta-ads, tiktok-ads, chatgpt-ads, ga4, posthog, seo, media-plan, competitor-research, analytics, cli