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@sokuRun it inside Claude Code after adding the marketplace with /plugin marketplace add About-Intelligence/soku-cli.
Contents
Discovered from sourceSkills 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:
| Task | Read |
|---|---|
| First-time setup, expired token, workspace selection, org/brand ambiguity | references/auth-workspace.md |
Ads, GA4, or PostHog reads; raw soku call; command discovery | references/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 approval | references/ads-write.md |
| SEO Hosting, automations, Context Hub files, temporary public file URLs | references/seo-automation-files.md |
Third-party APIs through server-side credential injection; what calls cost and soku credits; security rules | references/egress-security.md |
| Installing, updating, or removing Soku-managed local skills; finding out what an upgrade changed | references/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(orclaude mcp login sokufrom 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 waitexist only on the CLI. When a shell is available andsokucan be installed, prefer the CLI.
Default Flow
- Check auth/workspace state:
soku auth status
soku workspace status
-
If auth is missing or expired, use the agent split-flow from
references/auth-workspace.md. -
If the workspace is not ready, resolve and select the remote Soku brand:
soku workspace resolve <brand>
soku workspace use-brand <brand>
-
Pick the reference for the task. Do not infer Soku org/brand from the current local repo directory.
-
Inspect command help before unfamiliar calls:
soku --help
soku <namespace> --help
soku <namespace> <action> --help
- 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 statusin the same turn as the write — not earlier in the session — and check the reported brand is the one the user named (itssourcefield tells you whether saved config or aSOKU_BRAND_IDenvironment 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) andinbox_url(every pending review in the brand). Give the user the link with one line on what they are approving, then runsoku 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 runsoku review approve/denyyourself and never allowlist them — they are for a person deciding in their own terminal. If a pending response has noapprove_url(an older Soku API), ask the user to runsoku review approve <review_id>themselves. - A write the user chose to "Always approve" in Soku comes back as a normal
result marked
auto_approvedinstead 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, orcontext/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
| Exit | Meaning | What to do |
|---|---|---|
| 0 | Success | Parse data. |
| 1 | Usage or no workspace | Fix args, or run soku workspace status / use-brand. |
| 2 | Auth missing, expired, or revoked | Run soku auth login --no-wait. |
| 4 | Not found or unknown capability | Re-check soku --help / soku <ns> --help. |
| 5 | Runtime or network failure | Retry 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
