Soku CLI

The soku CLI is the shell-native way for an AI agent to use Soku from Claude Code, Codex, Cursor, or any terminal. It talks to Soku over /api/cli/*; no MCP host is required. Treat this file as the router. Load the relevant reference file before acting on a detailed workflow.

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.

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

• 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 must authorize every review-gated write — but don’t force a copy-paste. If your harness prompts for explicit human confirmation before each shell command (e.g. Claude Code’s permission prompt), you MAY run soku review approve <id> yourself after showing the user the diff/summary; that confirmation prompt is the human gate. Never allowlist or auto-approve soku review approve/deny, and never approve a write the user has not seen. If your harness runs commands without per-command human confirmation, do NOT self-approve — surface the review_id for the user to run.
• 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

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.

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.