Soku CLI: giving an AI agent a typed command line to marketing data with a human gate on every write

A command line built so an agent, not a person, is the main caller

Soku CLI exists to let an AI agent query marketing data and prepare campaign changes without a human copying numbers between browser tabs or pasting API keys into a prompt. The README states the design goal directly: it turns the tools and data already connected to a Soku workspace into typed, discoverable commands, so an agent can move from a question to an answer, or from a plan to a human-approved action.

The intended operator is someone running paid acquisition and analytics through Google Ads, Meta Ads, ChatGPT Ads, GA4, PostHog, SEO Hosting and related connectors, who wants an agent in Claude Code, Codex or Cursor to do the legwork. It is MIT licensed and, per `package.json`, at an early `0.1.0-alpha.18` version, so the surface is real but pre-1.0.

What makes it more than a thin API wrapper is the stated contract for agents: in a non-interactive shell every command returns a stable JSON envelope, `{"ok":true,"data":{...}}` on success and the same shape with a non-zero exit code on error. A predictable envelope is what lets an agent parse results reliably instead of scraping formatted text.

Credentials server-side and a review gate on delivery

Two decisions separate this from a generic API bridge. The README says Soku handles authentication and can inject connected third-party credentials server-side, so the ad-platform keys never enter the prompt or the agent's context. That matters because an agent's context is the last place you want a live Google Ads token to sit.

The second is that writes that change delivery are gated. The README states that delivery-changing ads operations create a review request before anything goes live, returning a review ID rather than executing. A campaign creation shows the pattern:

soku ads meta campaign create \
  --account-id <meta_account_id> \
  --name "Launch Test" \
  --objective OUTCOME_TRAFFIC \
  --summary "Create paused Meta traffic campaign Launch Test"

That call does not spend money. It produces a review the person then inspects and approves:

soku review show <review_id>
soku review approve <review_id>

The README's framing is that the agent prepares the exact change and explains it, and a human still decides whether it runs. For anyone who has watched an autonomous agent do something confident and wrong, moving the irreversible step behind an explicit human approval is the design choice that makes agent-driven ad management defensible at all.

Installing and pointing it at a workspace

The manual path is an npm global install followed by a browser-based device login and workspace selection. The README lays it out:

npm install -g @soku-ai/cli
soku auth login
soku workspace resolve <brand>
soku workspace use-brand <brand>
soku workspace status

`soku auth login` runs the device flow, `workspace resolve` finds a brand workspace, `use-brand` selects it, and `workspace status` confirms the context. Running `soku --help` then lists everything available to the signed-in account. The README notes you can skip the global install with `npx @soku-ai/cli --help`, and that Node.js 20 or newer is required.

A first real query reads cached, normalized ad reporting rather than writing anything:

soku ads list-ad-accounts --platform google

That returns the Google ad accounts the workspace can see, which is the safe first call to confirm the connection works before touching a single-dimension query or a GA4 property. The README also documents a plugin path: `claude plugin marketplace add About-Intelligence/soku-cli` then `claude plugin install soku@soku` registers the workflows in Claude Code, though the README is explicit that the plugin does not bundle the CLI, so `npm install -g @soku-ai/cli` still runs on your machine.

Skills carry the guardrails the bare commands do not

A distinction the README draws is between the commands and the skills. The typed command tree is generated from Soku's capability registry, and `soku call` is offered as a forward-compatible escape hatch for capabilities newer than the generated commands. But the commands are just the surface.

The business skills, named like `soku-ads-report` and `soku-google-ads`, are installed separately and carry the workflows and guardrails behind the commands rather than only their names:

soku skill install --all --global
soku skill list
soku skill status

The README is explicit that these skills are not part of the plugin and are installed on demand with `soku skill install <slug>`, kept current with `soku update skills`. This matters for setting expectations: installing the CLI gives an agent the ability to call commands, but the judgement about how to sequence a reporting or campaign workflow lives in the skills. An agent with the commands and no skills has the verbs without the recipes.

Where the model shows its edges

The honest limitations follow from the architecture. Soku CLI is a client to a hosted Soku workspace, not a standalone tool. Everything routes through Soku's servers, which is exactly what lets credentials stay server-side and writes be reviewed, but it also means the workspace, its connectors and its account are a dependency you cannot remove. This is the wrong tool for someone who wants a local, self-hosted way to hit ad APIs with their own keys.

The version number is the second caution. At `0.1.0-alpha.18` the command surface can still move, and while the README says the generated command tree and the `soku call` escape hatch are meant to absorb new capabilities without breaking, an alpha is an alpha. The forward-compatibility promise is a design intent, not a stability guarantee.

There is also a scope boundary worth naming. The review gate covers delivery-changing ad writes. Reads across GA4, PostHog and reporting are not gated, which is correct for reads but means an agent with access can pull a lot of analytics data on its own. The control that matters, human approval, is placed on the actions that spend money or change what ships, and read access is governed by whatever the workspace grants.

Against a raw MCP server or direct API integration

The alternative most teams reach for is wiring each platform's API directly, or standing up an MCP server per service so an agent can call them. That gives maximum control and no dependency on a hosted intermediary.

The difference is where credentials and safety live. A direct integration puts the API keys wherever the agent runs and leaves write safety for you to build, which is a real amount of work to do well and easy to do badly. Soku CLI centralises both: authentication and third-party credential injection happen server-side, and the review gate on delivery-changing writes is built in rather than something you implement per platform. The README even notes that the Claude plugin registers Soku's remote MCP server at `https://api.soku.ai/mcp` for hosts without a shell, so the MCP path is offered too, backed by the same gated backend. The trade is autonomy for a managed boundary: you accept a hosted workspace in exchange for not hand-rolling credential handling and approval flows across a half-dozen ad and analytics APIs.

Licensing and keeping current

Soku CLI is MIT licensed, so the client can be forked, inspected and adapted with attribution. That openness has a natural limit worth stating plainly: the license covers the CLI, not the hosted Soku service it talks to, so a fork still needs a Soku workspace to be useful. The valuable part, the connectors and the review backend, lives on the server.

Staying current is unusually low-friction by design. Because the typed command tree is generated from the capability registry, the README says new capabilities arrive automatically, and `soku call` reaches anything the generated commands do not yet cover. Skills are refreshed with `soku update skills`. So the upgrade story splits cleanly: the CLI itself updates through npm, while the capabilities it exposes track the server without a client release. The thing to verify before depending on it is account and connector scope: run `soku workspace status` and `soku --help` after signing in to see exactly which platforms and commands your workspace actually grants, since that, not the README's feature list, defines what your agent can do.

Editorial conclusion

Adopt Soku CLI if you want an AI agent to investigate ad and product analytics across Google Ads, Meta, GA4 and PostHog and prepare campaign changes, with credentials kept server-side and every delivery-changing write held behind soku review approve. It is the wrong choice if you need a local, self-hosted tool with your own API keys and no hosted dependency, since everything routes through a Soku workspace. Before relying on it, sign in and run soku workspace status and soku --help to confirm which connectors and commands your workspace grants, and install the business skills, because the CLI gives an agent the commands but the skills carry the workflows.

Frequently asked questions

Official sources

1. About-Intelligence/soku-cli on GitHub
2. Issues
3. License: MIT
4. README