@soku-ai/cli 0.1.0-alpha.7 → 0.1.0-alpha.8

package/dist/generated/capabilities.json

@@ -943,6 +943,89 @@
         "action:ga4/list_properties",
         "action:ga4/get_property_overview"
       ]
+    },
+    {
+      "id": "action:posthog/list_projects",
+      "namespace": "posthog",
+      "action": "list_projects",
+      "description": "List the PostHog projects this brand can query.",
+      "long_description": "Returns the PostHog projects granted to the current brand (project_id + name). START HERE for any PostHog task: every other posthog action requires one of these project_ids. Do NOT ask the user for a project id \u2014 this action is the source of truth. (Upstream PostHog project listing is org-wide and not available.)",
+      "mode": "read",
+      "priority": "normal",
+      "requires_review": false,
+      "freshness_kind": "realtime",
+      "input_params": [],
+      "output_shape": "data.rows[].{project_id, name}",
+      "see_also": []
+    },
+    {
+      "id": "action:posthog/list_tools",
+      "namespace": "posthog",
+      "action": "list_tools",
+      "description": "List the PostHog analytics tools available for a project.",
+      "long_description": "Returns the live PostHog MCP tool catalog for one granted project, each annotated with `requires_review`. The default response is a slim catalog without input schemas. Pass `tool` to fetch one exact tool's full input schema before calling `posthog/query`. Tools with `requires_review=true` (writes, or anything not on our read-only allowlist) must go through `posthog/request_change`, not `posthog/query`.",
+      "mode": "read",
+      "priority": "normal",
+      "requires_review": false,
+      "freshness_kind": "realtime",
+      "input_params": [
+        {
+          "name": "project_id",
+          "type": "string",
+          "required": false,
+          "description": "PostHog project id (from posthog/list_projects).",
+          "example": "12345"
+        },
+        {
+          "name": "tool",
+          "type": "string",
+          "required": false,
+          "description": "Exact PostHog tool name; when provided, returns that tool's full input schema.",
+          "example": "insight-query"
+        }
+      ],
+      "output_shape": "data.project_id, data.tools[].{name, description, requires_review[, input_schema when tool is provided]}",
+      "see_also": []
+    },
+    {
+      "id": "action:posthog/query",
+      "namespace": "posthog",
+      "action": "query",
+      "description": "Run a read-only PostHog analytics tool (trends, funnels, HogQL, etc.).",
+      "long_description": "Forwards a read-only PostHog tool call for one granted project. Common tools: `insight-query` (trends / funnels / retention), `execute-sql` (HogQL \u2014 read-only, validated), `read-data-schema` (use before writing HogQL to get real field names). Get the project_id from `posthog/list_projects` (never ask the user for it). Only allowlisted read tools are accepted here; a write or unvetted tool returns `requires_review` \u2014 call `posthog/request_change` for those. The response echoes which project was queried.",
+      "mode": "read",
+      "priority": "normal",
+      "requires_review": false,
+      "freshness_kind": "realtime",
+      "input_params": [
+        {
+          "name": "project_id",
+          "type": "string",
+          "required": true,
+          "description": "PostHog project id (from posthog/list_projects).",
+          "example": "12345"
+        },
+        {
+          "name": "tool",
+          "type": "string",
+          "required": true,
+          "description": "Exact PostHog tool name from posthog/list_tools.",
+          "example": "insight-query"
+        },
+        {
+          "name": "arguments",
+          "type": "object",
+          "required": false,
+          "description": "Tool arguments object per the tool's input schema.",
+          "example": {
+            "query": {
+              "kind": "TrendsQuery"
+            }
+          }
+        }
+      ],
+      "output_shape": "data.{project_id, tool, is_error, content[], structured, truncated}",
+      "see_also": []
     }
   ]
 }

package/dist/index.js

@@ -20,7 +20,7 @@ import { CLI_VERSION } from './version.js';
 const program = new Command();
 program
     .name('soku')
-    .description('Call Soku ads/GA4 data capabilities from any AI agent or shell.')
+    .description('Call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.')
     .version(CLI_VERSION);
 registerAuthCommands(program);
 registerOrgCommands(program);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const CLI_PACKAGE_NAME = "@soku-ai/cli";
-export declare const CLI_VERSION = "0.1.0-alpha.7";
+export declare const CLI_VERSION = "0.1.0-alpha.8";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soku-ai/cli",
-  "version": "0.1.0-alpha.7",
-  "description": "Soku CLI — call Soku ads/GA4 data capabilities from any AI agent or shell.",
+  "version": "0.1.0-alpha.8",
+  "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": {

package/skills/soku/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: soku
 description: >-
-  Use when calling Soku ads/GA4 marketing-data capabilities or SEO Hosting
-  domain connections 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
@@ -16,10 +16,10 @@ metadata:
 
 # Soku CLI
 
-The `soku` CLI calls Soku's ads, GA4, and SEO Hosting 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.
+The `soku` CLI calls Soku's ads, GA4, PostHog, and SEO Hosting 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
 
@@ -128,8 +128,9 @@ inspect them with `--help` — never guess action names or flags.
 
 ```bash
 soku resources list                       # what's granted (e.g. data-infra, seo-hosting)
-soku --help                               # namespaces: ads, ga4, …
+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
@@ -167,6 +168,29 @@ Do not write full `SELECT ... FROM ...` GAQL SQL. `gaql-search` takes structured
 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
 
 `soku call <namespace> <action>` runs any action by its raw (snake_case) name
@@ -176,6 +200,7 @@ 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"}}'
 ```
 
 ## SEO Hosting domain connections