@soku-ai/cli 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAC9C,eAAO,MAAM,WAAW,kBAAkB,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAC9C,eAAO,MAAM,WAAW,mBAAmB,CAAA"}

package/dist/version.js

@@ -1,3 +1,3 @@
 export const CLI_PACKAGE_NAME = '@soku-ai/cli';
-export const CLI_VERSION = '0.1.0-alpha.1';
+export const CLI_VERSION = '0.1.0-alpha.10';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soku-ai/cli",
-  "version": "0.1.0-alpha.1",
-  "description": "Soku CLI — call Soku ads/GA4 data capabilities from any AI agent or shell.",
+  "version": "0.1.0-alpha.10",
+  "description": "Soku CLI — call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.",
   "license": "Proprietary",
   "author": "Soku",
   "homepage": "https://soku.ai/cli",
@@ -19,7 +19,8 @@
     "ai-agent",
     "marketing-analytics",
     "google-ads",
-    "ga4"
+    "ga4",
+    "posthog"
   ],
   "type": "module",
   "bin": {
@@ -27,6 +28,7 @@
   },
   "files": [
     "dist",
+    "postinstall.cjs",
     "skills"
   ],
   "engines": {
@@ -39,9 +41,10 @@
   "scripts": {
     "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json dist/generated/capabilities.json",
     "typecheck": "tsc --noEmit",
-    "test": "tsc -p tsconfig.test.json && node --test \".test-build/**/*.test.js\"",
+    "test": "tsc -p tsconfig.test.json && find .test-build -name '*.test.js' -print | sort | xargs node --test",
     "gen:capabilities": "pnpm run build && node scripts/gen-capabilities.ts",
     "clean": "rm -rf dist .test-build",
+    "postinstall": "node postinstall.cjs",
     "prepublishOnly": "pnpm run clean && pnpm run build"
   },
   "dependencies": {

package/postinstall.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/*
+ * Refresh previously installed bundled Soku meta-skills after a global npm
+ * install. Business skills still update through `soku update skills`, because
+ * that path verifies catalog zip checksums and may need network access.
+ */
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const MANIFEST_FILE = '.soku-skills.json'
+const SOKU_META = 'soku'
+
+function shouldRun() {
+  return process.env.npm_config_global === 'true' || process.env.npm_config_global === '1'
+}
+
+function copyDir(source, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name)
+    const to = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(from, to)
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to)
+    }
+  }
+}
+
+function loadManifest(baseDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(baseDir, MANIFEST_FILE), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function hasSokuSkill(baseDir) {
+  const manifest = loadManifest(baseDir)
+  return (
+    Object.keys(manifest).length > 0 ||
+    fs.existsSync(path.join(baseDir, SOKU_META, 'SKILL.md'))
+  )
+}
+
+function refreshMetaSkill(baseDir, bundledDir) {
+  if (!hasSokuSkill(baseDir)) return
+
+  const dest = path.join(baseDir, SOKU_META)
+  fs.mkdirSync(dest, { recursive: true })
+  fs.rmSync(path.join(dest, 'SKILL.md'), { force: true })
+  fs.rmSync(path.join(dest, 'references'), { recursive: true, force: true })
+  fs.copyFileSync(path.join(bundledDir, 'SKILL.md'), path.join(dest, 'SKILL.md'))
+  const referencesDir = path.join(bundledDir, 'references')
+  if (fs.existsSync(referencesDir)) {
+    copyDir(referencesDir, path.join(dest, 'references'))
+  }
+
+  const manifest = loadManifest(baseDir)
+  manifest[SOKU_META] = {
+    sha256: '',
+    installed_at: new Date().toISOString(),
+    source: 'bundled',
+  }
+  fs.writeFileSync(path.join(baseDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function main() {
+  if (!shouldRun()) return
+  const bundledDir = path.join(__dirname, 'skills', SOKU_META)
+  if (!fs.existsSync(path.join(bundledDir, 'SKILL.md'))) return
+
+  for (const agentDir of ['.claude/skills', '.codex/skills', '.cursor/skills']) {
+    try {
+      refreshMetaSkill(path.join(os.homedir(), agentDir), bundledDir)
+    } catch {
+      // Best-effort lifecycle hook: npm install must not fail because an agent
+      // skill directory is missing, locked, or otherwise temporarily unreadable.
+    }
+  }
+}
+
+main()

package/skills/soku/SKILL.md

@@ -1,23 +1,26 @@
 ---
 name: soku
 description: >-
-  Use when calling Soku ads/GA4 marketing-data capabilities from the shell —
+  Use when calling Soku ads/GA4/PostHog marketing-data capabilities or SEO
+  Hosting domain connections from the shell —
   running `soku auth login`, switching org/brand with `soku org use` /
   `soku brand use`, discovering capabilities, calling a data action, routing a
   third-party API call (Ahrefs/DataForSEO/Firecrawl/Gemini/…) through
-  `soku egress`, handling 401/403 errors, or installing/updating the Soku CLI.
+  `soku egress`, managing `soku seo-hosting connections`, managing
+  `soku automation`, handling 401/403 errors, or installing/updating the Soku
+  CLI.
 license: Proprietary
 metadata:
   author: nex-ad
-  version: "0.1"
+  version: "0.2"
 ---
 
 # Soku CLI
 
-The `soku` CLI calls Soku's ads + GA4 data capabilities over HTTP. It is the
-preferred way for an agent to use Soku data — it works in any shell, with no MCP
-host required. Output is JSON on stdout; errors are a JSON envelope on stderr
-with a semantic exit code.
+The `soku` CLI calls Soku's ads, GA4, PostHog, SEO Hosting, and Automation
+capabilities over HTTP. It is the preferred way for an agent to use Soku from
+any shell, with no MCP host required. Output is JSON on stdout; errors are a
+JSON envelope on stderr with a semantic exit code.
 
 ## Output & exit codes
 
@@ -89,19 +92,46 @@ soku org list             # organizations you belong to
 soku org use <slug|id>    # set active org (id, slug, or name; clears a now-mismatched brand)
 soku brand list           # brands in the active org
 soku brand use <slug|id>  # id, slug, or name
+soku workspace status     # show the active org/brand and whether it is ready
+soku workspace resolve <brand>    # inspect accessible brand matches across orgs
+soku workspace use-brand <brand>  # set org + brand together when the match is unique
 ```
 
 Env overrides for one-off invocations: `SOKU_ORG_ID`, `SOKU_BRAND_ID`.
 
+Do not infer Soku workspace state from the current shell directory. The working
+directory may contain unrelated README/AGENTS/context files from the user's local
+project. Start with `soku workspace status`; if the target brand is unknown, use
+`soku workspace resolve <brand>` and then `soku workspace use-brand <brand>`.
+
+## Brand memory
+
+Memory is scoped to the active Soku workspace, not to the local shell directory.
+After `soku workspace status` is ready, these commands read memory for the
+current brand only:
+
+```bash
+soku memory list
+soku memory search "policy 2026-05-31"
+soku memory get reference noiz-policy-event
+```
+
+Use brand memory as background, hypotheses, and investigation leads. Do not
+treat a memory note as a verified data fact unless this turn also confirms it
+with data actions, change history, billing evidence, or another authoritative
+source. In reports, label memory-derived context separately from data-confirmed
+findings.
+
 ## Calling capabilities (discover with --help, then run)
 
 Each data capability is a typed sub-command under its namespace. Discover and
 inspect them with `--help` — never guess action names or flags.
 
 ```bash
-soku resources list                       # what's granted (e.g. data-infra)
-soku --help                               # namespaces: ads, ga4, …
+soku resources list                       # what's granted (e.g. data-infra, seo-hosting, automation)
+soku --help                               # namespaces: ads, ga4, posthog, …
 soku ads --help                           # actions in the ads namespace
+soku posthog --help                       # customer PostHog read actions
 soku ads query-single-dimension --help    # flags, types, and usage for one action
 
 soku ads list-ad-accounts --platform google
@@ -110,8 +140,57 @@ soku ads query-single-dimension --account-id 123 --dimension campaign \
 ```
 
 `<command> --help` is authoritative for valid flags, required vs optional, types,
-and usage. Read it before invoking an unfamiliar action. Object/list flags take a
-JSON string, e.g. `--filters '{"campaign_id":["123"]}'`.
+and usage. Read it before invoking an unfamiliar action. Typed command names use
+kebab-case (`soku ads query-single-dimension`); raw `soku call` action names use
+registry snake_case (`soku call ads query_single_dimension`). Object/list flags
+take a JSON string, e.g. `--filters '{"campaign_id":["123"]}'`.
+
+### Google Ads GAQL fallback
+
+Prefer cached ads analytics first:
+
+```bash
+soku ads list-dimensions --platform google --account-id 123
+soku ads query-single-dimension --account-id 123 --dimension campaign ...
+soku ads query-multi-dimension --account-id 123 --dimensions '["campaign","device"]' ...
+```
+
+Use GAQL only when cached query actions cannot expose the Google-native fields
+or segment combination you need:
+
+```bash
+soku ads get-resource-metadata --platform google --account-id 123 --resource-name campaign
+soku ads gaql-search --platform google --account-id 123 \
+  --dimensions '["date","campaign"]' --metrics '["cost","clicks"]' --limit 20
+```
+
+Do not write full `SELECT ... FROM ...` GAQL SQL. `gaql-search` takes structured
+`dimensions`, `metrics`, `filters`, `date_range`, `order_by`, and `limit`; the
+server translates those into real GAQL. For the same action through the raw
+escape hatch, use snake_case: `soku call ads gaql_search --payload '{...}'`.
+
+### PostHog customer analytics
+
+PostHog data uses the same backend MCP forwarding gateway as the sandbox agent.
+Start by listing the current brand's granted projects, then inspect the live
+tool menu, then run an allowlisted read tool. Do not ask the user for a project
+id before listing projects.
+
+```bash
+soku posthog list-projects
+soku posthog list-tools --project-id 12345
+soku posthog query --project-id 12345 --tool execute-sql \
+  --arguments '{"query":"SELECT count() FROM events WHERE event = '\''$pageview'\''"}'
+```
+
+Use `read-data-schema` before writing HogQL if field names are unclear:
+
+```bash
+soku posthog query --project-id 12345 --tool read-data-schema --arguments '{}'
+```
+
+The CLI default read surface does not expose `posthog/request_change`; writes and
+unvetted PostHog MCP tools remain outside the generated command tree.
 
 ### Raw escape hatch
 
@@ -122,8 +201,147 @@ a newer action than this CLI version ships:
 ```bash
 soku call ads list_ad_accounts -p platform=google
 soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
+soku call posthog query --payload '{"project_id":"12345","tool":"execute-sql","arguments":{"query":"SELECT count() FROM events"}}'
+```
+
+## Automations
+
+Use `soku automation` to manage automations for the active brand. The session
+must include the `automation` resource. Request it at login:
+
+```bash
+soku auth login --resource automation
+# or include it with data access:
+soku auth login --resource data-infra,automation
 ```
 
+The workspace must be ready before any automation call:
+
+```bash
+soku workspace status
+soku org use <slug|id>
+soku brand use <slug|id>
+soku resources list
+```
+
+Commands:
+
+```bash
+soku automation list
+soku automation create --name "Fast check" --prompt "Check account health" --cron "* * * * *" --timezone UTC
+soku automation trigger <automation_id>
+soku automation runs <automation_id>
+```
+
+`create` requires exactly one schedule option:
+
+- `--cron <expr>` with optional `--timezone <iana>` (default `UTC`).
+- `--interval-seconds <seconds>` for interval schedules; must be at least
+  `3600` and divisible by `60`.
+- `--once-at <iso>` for a one-time UTC instant.
+
+`runs` shows run status and a browser link when a conversation exists. The CLI
+does not read conversation content; open the printed link in Studio to inspect
+the actual chat. For local development links, set `SOKU_WEB_BASE`, for example:
+
+```bash
+SOKU_WEB_BASE=http://127.0.0.1:47627 soku automation runs <automation_id>
+```
+
+## SEO Hosting domain connections
+
+Use `soku seo-hosting` to manage SEO Hosting for the active brand. The session
+must include the `seo-hosting` resource. Request it at login:
+
+```bash
+soku auth login --resource seo-hosting
+# or include it with data access:
+soku auth login --resource data-infra,seo-hosting
+```
+
+The workspace must be ready before any connection call:
+
+```bash
+soku workspace status
+soku org use <slug|id>
+soku brand use <slug|id>
+```
+
+### Posts
+
+Use typed `pages` commands for the same SEO Hosting content actions exposed to
+runtime agents through `seo_hosting/*`. SEO Hosting pages are **complete HTML
+documents** (not Markdown) served as owned-media web pages on the brand's
+connected domain; they are identified by `section` + `slug` (there are no post
+ids). They are not social posts.
+
+Always check status first:
+
+```bash
+soku seo-hosting status
+```
+
+`status` shows each connected domain, whether it is `live`, and which sections it
+serves. If no domain is live, do not publish yet; connect or fix a domain first.
+When hosting is live:
+
+```bash
+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 unpublish --section blog --slug how-to
+soku seo-hosting pages delete --section blog --slug how-to --confirm
+soku seo-hosting pages upload-asset --path blog/how-to/hero.png --file ./hero.png
+```
+
+`put` creates or overwrites a page as a **draft** and requires `--section`,
+`--slug`, `--title`, and exactly one HTML source: `--html`, `--html-file`, or
+`--html-stdin`. Optional metadata flags are `--description`, `--template`, and
+`--seo '<json object>'`. Reference images / CSS / fonts by the absolute URL
+returned from `pages upload-asset` (no custom JavaScript — HTML + CSS only).
+
+`publish` runs the validation gate (no `<script>` / inline JS) and
+makes the page live once a domain serves its section; it also prints advisory
+`Link warnings` for dead internal links (these do not block publishing — fix the
+links and re-publish). `unpublish` reverts it to draft. Writes run immediately
+(no-review), so confirm intent with the user before publishing or deleting.
+
+### Domain connections
+
+Connection commands:
+
+```bash
+soku seo-hosting connections list
+soku seo-hosting connections connect-cname --hostname blog.example.com
+soku seo-hosting connections verify <connection_id>
+soku seo-hosting connections disconnect <connection_id> --confirm
+```
+
+Cloudflare Worker reverse proxy setup runs a probe before provisioning. Use it
+when the customer's root or existing hostname is already on Cloudflare and SEO
+Hosting needs to mount sections such as `/blog`, `/use-cases`, or
+`/alternatives`:
+
+```bash
+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
+printf %s "$CLOUDFLARE_API_TOKEN" | soku seo-hosting connections connect-worker \
+  --hostname example.com --sections blog --cf-token-stdin
+```
+
+Allowed sections are `blog`, `use-cases`, and `alternatives`; omitted sections
+default to `blog`. If the probe reports existing mounted content, add
+`--accept-conflicts` only after the user confirms SEO Hosting may shadow those
+paths. If the hostname serves its own Next.js assets, add
+`--accept-next-assets-warning` only after confirming `/_next/static/*` may route
+through the Worker.
+
+Do not pass Cloudflare API tokens as literal argv values or print them. Use
+`--cf-token-env <ENV_NAME>` or `--cf-token-stdin` exactly once. Vercel OAuth
+domain connections are not exposed in the CLI yet; use the Studio web settings
+for Vercel-backed domains.
+
 ## Write actions (human approval required)
 
 Some actions mutate state (e.g. conversion-group writes) and are **review-gated**.
@@ -180,18 +398,25 @@ returned verbatim on stdout.
 ## Installing / updating the skill
 
 ```bash
-soku update-check          # check whether the CLI itself needs updating
+soku update status            # show CLI + installed skill update status
+soku update skills            # refresh this meta-skill and installed business skills
+soku update cli               # install the latest CLI from npm
 soku skill install            # this meta-skill into .claude / .codex / .cursor (project)
 soku skill install --global   # into ~/.claude, ~/.codex, ~/.cursor
 soku skill install --agent claude --global
 ```
 
-If `soku update-check` reports an available CLI update, ask the user before
-running:
+Normal `soku` commands schedule a background refresh for installed Soku-managed
+skills at most once every 24 hours. Set `SOKU_NO_SKILL_AUTO_UPDATE=1` to disable
+skill auto updates, or `SOKU_UPDATE_INTERVAL_HOURS=<n>` to change the interval.
 
-```bash
-npm i -g @soku-ai/cli
-```
+The CLI binary itself is advisory by default. To opt into automatic npm CLI
+updates, set `SOKU_AUTO_UPDATE_CLI=1`; otherwise run `soku update cli` when
+`soku update status` shows a newer version.
+
+A global `npm i -g @soku-ai/cli` refreshes this already-installed global
+meta-skill after npm finishes installing. It does not install new skills and it
+does not update project-local skills.
 
 ## Installing business skills (account audits, Google Ads, reports, …)
 
@@ -205,10 +430,21 @@ soku skill list                       # browse the catalog
 soku skill install account-audit      # install one (into soku-account-audit/)
 soku skill install ads-report google-ads
 soku skill install --all              # install everything
-soku skill installed                  # what's installed locally
+soku skill status                     # what's installed locally
+soku skill list-installed             # same as status
 soku skill remove account-audit
 ```
 
+Catalog slugs are used for install/remove commands (`ads-report`). Installed AI
+client skill names are Soku-prefixed (`soku-ads-report`). When asking an agent to
+run an installed business skill, write `use @soku-ads-report skill`, not
+`@ads-report`.
+
+Business skill updates are detected from `.soku-skills.json`: for each installed
+catalog slug, Soku compares local `version`, `sha256`, and `source` against the
+latest catalog `index.json`. A changed version, changed hash, or old source is
+treated as an update; missing catalog entries are reported but not deleted.
+
 Each installed skill carries a "Running this skill with the Soku CLI" section
 (its data actions mapped to `soku call`, its third-party APIs to `soku egress`),
 so it runs through this same CLI — no in-sandbox tools, no local API keys.

package/README.md

@@ -1,91 +0,0 @@
-# @soku-ai/cli
-
-Call Soku ads/GA4 data capabilities from any shell or AI agent. It's the
-preferred surface for external agents — equivalent to the hosted MCP server, but
-works without an MCP host.
-
-## Install
-
-```bash
-npm i -g @soku-ai/cli
-```
-
-Development builds can be linked from this repo:
-
-```bash
-pnpm --filter @soku-ai/cli run build
-npm link apps/cli
-```
-
-## Quick start
-
-```bash
-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-check            # check npm for a newer CLI release
-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
-
-stdout is JSON (`{"ok":true,"data":...}` when piped; pretty when a TTY).
-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).
-
-## Use from an AI agent
-
-For a fresh agent, point it at the hosted installer guide:
-
-```text
-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:
-
-```bash
-soku skill install --global        # all detected agents
-soku skill install --agent claude  # one agent, into the project
-```
-
-## Updates
-
-`soku update-check` queries the npm registry for `@soku-ai/cli@latest` and tells
-the user whether `npm i -g @soku-ai/cli` should be re-run. The CLI also performs a
-TTY-only advisory check at most once every 24 hours, cached in
-`~/.soku/update-check.json`. Set `SOKU_NO_UPDATE_CHECK=1` to disable the
-background notice.
-
-## Environment variables
-
-| Variable | Purpose |
-|----------|---------|
-| `SOKU_TOKEN` | Pre-issued session token (overrides stored credentials) |
-| `SOKU_API_BASE` | API base URL override |
-| `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 TTY-only update notice |
-| `ALL_PROXY` | Proxy for outbound HTTPS |