Soku CLI

Soku CLI

Written against Soku CLI release 0.1.0-alpha.24. 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:

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

2. If auth is missing or expired, use the agent split-flow from references/auth-workspace.md.

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

soku workspace resolve <brand>
soku workspace use-brand <brand>

4. Pick the reference for the task. Do not infer Soku org/brand from the current local repo directory.

5. Inspect command help before unfamiliar calls:

soku --help
soku <namespace> --help
soku <namespace> <action> --help

6. 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.