Soku CLI

Soku CLI for Claude Code, Codex, and Cursor

Give a shell-based AI agent trusted marketing data, focused Soku skills, covered APIs, and review-gated write actions—then get from installation to a useful account health check in one guided flow.

What your agent gets

A single CLI connection gives shell-based agents the core Soku surfaces they need for data, research, content, and safe writes.

Ads

Google and Meta reporting

GA4

Site analytics and events

PostHog

Product analytics queries

Egress

Covered APIs with server keys

SEO Hosting

Pages, publishing, domains

Skills

Soku playbooks for agents

Memory

Brand context and references

Review gates

Human-approved write actions

Copy this prompt

Paste it into your agent when you want Soku ready in the current workspace.

Prompt

Read https://soku.ai/cli/skill.md, install or update Soku CLI, sign in with device login, and select my Soku workspace. Ask me to choose when more than one workspace or account matches. Install only the business skills needed for my task, then run a read-only 30-day marketing performance health check on the account I choose and save the findings with their data window. Stop whenever browser approval or a human review is required.

Install the CLI

If you prefer to install manually, use npm with Node.js 20 or newer. Then confirm the installed version and update status.

Terminal

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

Authenticate with device login

For a human terminal, use the interactive device-login flow. The CLI opens or prints a browser verification URL, waits for approval, then resumes the session automatically.

Agent or container

SOKU_NO_KEYCHAIN=1 soku auth login --no-wait
# Show the verification URL and wait for browser approval.

Interactive human terminal

soku auth login

Use the default login command. Do not add a legacy resource bundle flag. Review-gated ads mutations create a pending review. Direct writes such as SEO Hosting publishing require explicit user confirmation in the prompt or agent harness before execution.

Select the workspace

The Soku workspace is the remote org and brand. Do not infer it from the local folder name. Resolve candidate brands first, then select the intended brand.

Workspace commands

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

Install agent skills

Install the narrowest business skill for the current task. Avoid installing the whole catalog unless the user explicitly asks for it. Installed business skills appear with a soku- prefix in agent autocomplete.

Skill commands

soku skill list
soku skill install <skill-slug> --global
soku skill status --global
soku skill list-installed --global

Produce the first useful result

A saved, read-only performance health check with the selected account, exact date window, evidence, and next actions — not merely a successful installation.

Setup is not complete after package installation or login. Verify the available surfaces, choose one connected account, and run the concrete read-only task from the copied prompt.

Capability checks

soku ads --help
soku ga4 --help
soku gsc --help
soku posthog --help
soku egress providers
soku seo-hosting status

Module calls

Use soku --help and soku <namespace> --help as the source of truth for current flags. The examples below are the direct entry points for each CLI module.

Ads reporting

Read-only data

Use typed ads commands for account discovery and cached reporting. Read command help before using an unfamiliar dimension or flag.

Commands

soku ads list-ad-accounts --platform google
soku ads list-dimensions --platform google
soku ads query-single-dimension --platform google --account-id <account_id> \
  --date-start 2026-06-01 --date-end 2026-06-18 --dimension campaign
soku ads query-multi-dimension --platform google --account-id <account_id> \
  --date-start 2026-06-01 --date-end 2026-06-18 --dimensions '["campaign","device"]'

GA4 reporting

Read-only data

Use GA4 commands for property discovery, performance overview, top pages, events, and custom reports.

Commands

soku ga4 list-properties
soku ga4 get-property-overview --property-id <property_id> \
  --date-start 2026-06-01 --date-end 2026-06-18
soku ga4 list-top-pages --property-id <property_id> \
  --date-start 2026-06-01 --date-end 2026-06-18 --limit 20
soku ga4 run-report --property-id <property_id> \
  --date-ranges '[{"start_date":"2026-06-01","end_date":"2026-06-18"}]' \
  --dimensions '["date","sessionSource"]' --metrics '["sessions","totalUsers"]'

PostHog customer analytics

Read-only data

Use PostHog commands for granted project discovery, live tool discovery, and read-only product analytics queries. Unvetted or write tools are not exposed through the generated CLI command tree.

Commands

soku posthog list-projects
soku posthog list-tools --project-id <project_id>
soku posthog query --project-id <project_id> --tool read-data-schema \
  --arguments '{}'
soku posthog query --project-id <project_id> --tool execute-sql \
  --arguments '{"query":"SELECT count() FROM events WHERE event = '\''$pageview'\''"}'

Third-party API egress

Server-key proxy

Prefix provider curl calls with Soku egress so credentials are injected on Soku servers instead of the local machine.

Commands

soku egress providers
soku egress -- curl "https://api.ahrefs.com/v3/site-explorer/overview?target=example.com"
soku egress -- curl -X POST "https://api.dataforseo.com/v3/..." \
  -H "Content-Type: application/json" -d '{"key":"value"}'

SEO Hosting content

Direct publish

Author owned-media pages as complete HTML documents, publish them, and inspect what is live for the active brand.

Commands

soku seo-hosting status
soku seo-hosting pages list --section blog --status draft
soku seo-hosting pages put --section blog --slug how-to --title "How to ..." --html-file page.html
soku seo-hosting pages publish --section blog --slug how-to
soku seo-hosting pages upload-asset --path blog/how-to/hero.png --file ./hero.png

SEO Hosting domains

Org admin setup

Connect a dedicated CNAME host, or mount sections on an existing Cloudflare hostname through a Worker reverse proxy.

Commands

soku seo-hosting connections list
soku seo-hosting connections connect-cname --hostname blog.example.com
soku seo-hosting connections probe --hostname example.com --sections blog,use-cases
soku seo-hosting connections connect-worker --hostname example.com \
  --sections blog,use-cases --cf-token-env CLOUDFLARE_API_TOKEN
soku seo-hosting connections verify <connection_id>

Brand memory

Workspace context

Read brand-scoped memory as background context, then confirm factual claims with data commands when needed.

Commands

soku memory list
soku memory search "brand positioning"
soku memory get reference <name>

Business skills

Local agent

Install playbooks into Claude Code, Codex, Cursor, or another local agent skill directory. The Soku meta skill is handled automatically.

Commands

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

Review-gated writes

Human review gate

Sensitive writes create a pending review and execute only after explicit human approval.

Commands

soku call ads create_conversion_group --summary "create group: qualified leads" \
  -p name="Qualified leads"
soku review list
soku review show <review_id>
soku review approve <review_id>