@soku-ai/cli

Call Soku ads/GA4 data capabilities from any shell or AI agent. It is the preferred surface for external agents and does not require an MCP host.

Install

npm i -g @soku-ai/cli

Development builds can be linked from this repo:

pnpm --filter @soku-ai/cli run build
npm link apps/cli

Quick start

soku auth login              # device-login in the browser
soku org use <slug|id>       # pick a workspace (id, slug, or name)
soku brand use <slug|id>
soku --help                  # discover namespaces (ads, ga4, …)
soku update status           # check CLI and installed skill updates
soku memory list             # read current-brand memory context
soku ads --help              # actions in a namespace
soku ads list-ad-accounts --platform google

Each data capability is a typed sub-command under its namespace; <command> --help shows its flags. soku call <ns> <action> is a raw escape hatch for actions not yet exposed as a typed sub-command.

Authentication

soku uses an org-agnostic, device-login session token (RFC 8628). You log in once; the org and brand are chosen at runtime and sent per request.

• Human: soku auth login opens the browser and waits for approval.
• Agent (non-blocking): soku auth login --no-wait returns the verification URL immediately; resume with soku auth login --device-code <code> after the user approves.
• CI / headless: set SOKU_TOKEN to a pre-issued token to skip interactive auth (and the OS keychain).

Token storage: OS keychain when available, else ~/.soku/credentials.json (0600). Set SOKU_NO_KEYCHAIN=1 to always use the file. Behind a proxy, set ALL_PROXY.

Output

TTY output is human-readable: status lines, key/value summaries, and tables for lists. Piped or non-TTY output stays machine-readable JSON ({"ok":true,"data":...}). Errors go to stderr as {"ok":false,"error":{type,message,hint}} with a semantic exit code (0 ok / 1 usage / 2 auth / 4 not-found / 5 runtime). soku egress -- curl ... is the exception: successful upstream responses are passed through verbatim.

Use from an AI agent

For a fresh agent, point it at the hosted installer guide:

Read https://soku.ai/cli/skill.md and install the Soku CLI.

Install the bundled skill so Claude Code / Codex / Cursor know how to drive the CLI:

soku skill install --global        # all detected agents
soku skill install --agent claude  # one agent, into the project

The CLI writes .soku-skills.json only while Soku-managed skills are installed in a skills directory. It is a local install manifest, not a credential or user config file, and it is removed automatically when the last Soku-managed skill is removed.

Updates

soku update status queries the npm registry for @soku-ai/cli@latest and compares installed Soku-managed skills against the public skill catalog. soku update skills refreshes the bundled soku meta-skill plus already installed business skills. soku update cli runs npm i -g @soku-ai/cli.

The CLI also performs an advisory check on every command invocation, writing update notices to stderr only. There is no update-check cache; set SOKU_NO_UPDATE_CHECK=1 to disable the background notice. The legacy soku update-check command still exists as a hidden compatibility alias.

Release

Release publishing is handled by .github/workflows/publish-soku-cli.yml.

1. Bump both apps/cli/package.json and apps/cli/src/version.ts.
2. Run pnpm --filter @soku-ai/cli test and pnpm --filter @soku-ai/cli build.
3. Use workflow dispatch with dry_run=true to verify packaging.
4. After the PR is merged, push a tag named soku-ai-cli-v<version>.

The workflow verifies that the tag matches the package version, checks that the version is not already on npm, runs npm pack --dry-run, then publishes with npm publish --access public --tag latest via npm Trusted Publishing. The publish workflow upgrades npm to the Trusted Publishing compatible runtime before calling npm publish.

Environment variables

Production is the default: API calls go to https://api.soku.ai, and skills are downloaded from https://api.soku.ai/api/cli/skills. Local and staging endpoints are environment-only overrides so a dev session cannot poison ~/.soku/config.json.

SOKU_API_BASE=http://localhost:15386 soku auth status
SOKU_SKILLS_URL=http://127.0.0.1:18080 soku skill list

| Variable | Purpose | |----------|---------| | SOKU_TOKEN | Pre-issued session token (overrides stored credentials) | | SOKU_API_BASE | Per-command API base URL override; default is https://api.soku.ai | | SOKU_ORG_ID / SOKU_BRAND_ID | One-off workspace override | | SOKU_NO_KEYCHAIN | Skip the OS keychain; use the 0600 file | | SOKU_NO_UPDATE_CHECK | Disable the background update notice | | SOKU_SKILLS_URL | Per-command skill catalog override | | ALL_PROXY | Proxy for outbound HTTPS |