@soku-ai/cli 0.1.0-alpha.7 → 0.1.0-alpha.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/generated/capabilities.json +83 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +4 -3
- package/skills/soku/SKILL.md +32 -7
|
@@ -943,6 +943,89 @@
|
|
|
943
943
|
"action:ga4/list_properties",
|
|
944
944
|
"action:ga4/get_property_overview"
|
|
945
945
|
]
|
|
946
|
+
},
|
|
947
|
+
{
|
|
948
|
+
"id": "action:posthog/list_projects",
|
|
949
|
+
"namespace": "posthog",
|
|
950
|
+
"action": "list_projects",
|
|
951
|
+
"description": "List the PostHog projects this brand can query.",
|
|
952
|
+
"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.)",
|
|
953
|
+
"mode": "read",
|
|
954
|
+
"priority": "normal",
|
|
955
|
+
"requires_review": false,
|
|
956
|
+
"freshness_kind": "realtime",
|
|
957
|
+
"input_params": [],
|
|
958
|
+
"output_shape": "data.rows[].{project_id, name}",
|
|
959
|
+
"see_also": []
|
|
960
|
+
},
|
|
961
|
+
{
|
|
962
|
+
"id": "action:posthog/list_tools",
|
|
963
|
+
"namespace": "posthog",
|
|
964
|
+
"action": "list_tools",
|
|
965
|
+
"description": "List the PostHog analytics tools available for a project.",
|
|
966
|
+
"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`.",
|
|
967
|
+
"mode": "read",
|
|
968
|
+
"priority": "normal",
|
|
969
|
+
"requires_review": false,
|
|
970
|
+
"freshness_kind": "realtime",
|
|
971
|
+
"input_params": [
|
|
972
|
+
{
|
|
973
|
+
"name": "project_id",
|
|
974
|
+
"type": "string",
|
|
975
|
+
"required": false,
|
|
976
|
+
"description": "PostHog project id (from posthog/list_projects).",
|
|
977
|
+
"example": "12345"
|
|
978
|
+
},
|
|
979
|
+
{
|
|
980
|
+
"name": "tool",
|
|
981
|
+
"type": "string",
|
|
982
|
+
"required": false,
|
|
983
|
+
"description": "Exact PostHog tool name; when provided, returns that tool's full input schema.",
|
|
984
|
+
"example": "insight-query"
|
|
985
|
+
}
|
|
986
|
+
],
|
|
987
|
+
"output_shape": "data.project_id, data.tools[].{name, description, requires_review[, input_schema when tool is provided]}",
|
|
988
|
+
"see_also": []
|
|
989
|
+
},
|
|
990
|
+
{
|
|
991
|
+
"id": "action:posthog/query",
|
|
992
|
+
"namespace": "posthog",
|
|
993
|
+
"action": "query",
|
|
994
|
+
"description": "Run a read-only PostHog analytics tool (trends, funnels, HogQL, etc.).",
|
|
995
|
+
"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.",
|
|
996
|
+
"mode": "read",
|
|
997
|
+
"priority": "normal",
|
|
998
|
+
"requires_review": false,
|
|
999
|
+
"freshness_kind": "realtime",
|
|
1000
|
+
"input_params": [
|
|
1001
|
+
{
|
|
1002
|
+
"name": "project_id",
|
|
1003
|
+
"type": "string",
|
|
1004
|
+
"required": true,
|
|
1005
|
+
"description": "PostHog project id (from posthog/list_projects).",
|
|
1006
|
+
"example": "12345"
|
|
1007
|
+
},
|
|
1008
|
+
{
|
|
1009
|
+
"name": "tool",
|
|
1010
|
+
"type": "string",
|
|
1011
|
+
"required": true,
|
|
1012
|
+
"description": "Exact PostHog tool name from posthog/list_tools.",
|
|
1013
|
+
"example": "insight-query"
|
|
1014
|
+
},
|
|
1015
|
+
{
|
|
1016
|
+
"name": "arguments",
|
|
1017
|
+
"type": "object",
|
|
1018
|
+
"required": false,
|
|
1019
|
+
"description": "Tool arguments object per the tool's input schema.",
|
|
1020
|
+
"example": {
|
|
1021
|
+
"query": {
|
|
1022
|
+
"kind": "TrendsQuery"
|
|
1023
|
+
}
|
|
1024
|
+
}
|
|
1025
|
+
}
|
|
1026
|
+
],
|
|
1027
|
+
"output_shape": "data.{project_id, tool, is_error, content[], structured, truncated}",
|
|
1028
|
+
"see_also": []
|
|
946
1029
|
}
|
|
947
1030
|
]
|
|
948
1031
|
}
|
package/dist/index.js
CHANGED
|
@@ -20,7 +20,7 @@ import { CLI_VERSION } from './version.js';
|
|
|
20
20
|
const program = new Command();
|
|
21
21
|
program
|
|
22
22
|
.name('soku')
|
|
23
|
-
.description('Call Soku ads/GA4 data capabilities from any AI agent or shell.')
|
|
23
|
+
.description('Call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.')
|
|
24
24
|
.version(CLI_VERSION);
|
|
25
25
|
registerAuthCommands(program);
|
|
26
26
|
registerOrgCommands(program);
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,4BAA4B;AAE5B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAA;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACnE,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AACjF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACJ,IAAI,CAAC,MAAM,CAAC;KACZ,WAAW,CAAC,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/version.d.ts
CHANGED
package/dist/version.js
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@soku-ai/cli",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
4
|
-
"description": "Soku CLI — call Soku ads/GA4 data capabilities from any AI agent or shell.",
|
|
3
|
+
"version": "0.1.0-alpha.8",
|
|
4
|
+
"description": "Soku CLI — call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.",
|
|
5
5
|
"license": "Proprietary",
|
|
6
6
|
"author": "Soku",
|
|
7
7
|
"homepage": "https://soku.ai/cli",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
"ai-agent",
|
|
20
20
|
"marketing-analytics",
|
|
21
21
|
"google-ads",
|
|
22
|
-
"ga4"
|
|
22
|
+
"ga4",
|
|
23
|
+
"posthog"
|
|
23
24
|
],
|
|
24
25
|
"type": "module",
|
|
25
26
|
"bin": {
|
package/skills/soku/SKILL.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: soku
|
|
3
3
|
description: >-
|
|
4
|
-
Use when calling Soku ads/GA4 marketing-data capabilities or SEO
|
|
5
|
-
domain connections from the shell —
|
|
4
|
+
Use when calling Soku ads/GA4/PostHog marketing-data capabilities or SEO
|
|
5
|
+
Hosting domain connections from the shell —
|
|
6
6
|
running `soku auth login`, switching org/brand with `soku org use` /
|
|
7
7
|
`soku brand use`, discovering capabilities, calling a data action, routing a
|
|
8
8
|
third-party API call (Ahrefs/DataForSEO/Firecrawl/Gemini/…) through
|
|
@@ -16,10 +16,10 @@ metadata:
|
|
|
16
16
|
|
|
17
17
|
# Soku CLI
|
|
18
18
|
|
|
19
|
-
The `soku` CLI calls Soku's ads, GA4, and SEO Hosting capabilities over
|
|
20
|
-
is the preferred way for an agent to use Soku from any shell, with no
|
|
21
|
-
required. Output is JSON on stdout; errors are a JSON envelope on
|
|
22
|
-
semantic exit code.
|
|
19
|
+
The `soku` CLI calls Soku's ads, GA4, PostHog, and SEO Hosting capabilities over
|
|
20
|
+
HTTP. It is the preferred way for an agent to use Soku from any shell, with no
|
|
21
|
+
MCP host required. Output is JSON on stdout; errors are a JSON envelope on
|
|
22
|
+
stderr with a semantic exit code.
|
|
23
23
|
|
|
24
24
|
## Output & exit codes
|
|
25
25
|
|
|
@@ -128,8 +128,9 @@ inspect them with `--help` — never guess action names or flags.
|
|
|
128
128
|
|
|
129
129
|
```bash
|
|
130
130
|
soku resources list # what's granted (e.g. data-infra, seo-hosting)
|
|
131
|
-
soku --help # namespaces: ads, ga4, …
|
|
131
|
+
soku --help # namespaces: ads, ga4, posthog, …
|
|
132
132
|
soku ads --help # actions in the ads namespace
|
|
133
|
+
soku posthog --help # customer PostHog read actions
|
|
133
134
|
soku ads query-single-dimension --help # flags, types, and usage for one action
|
|
134
135
|
|
|
135
136
|
soku ads list-ad-accounts --platform google
|
|
@@ -167,6 +168,29 @@ Do not write full `SELECT ... FROM ...` GAQL SQL. `gaql-search` takes structured
|
|
|
167
168
|
server translates those into real GAQL. For the same action through the raw
|
|
168
169
|
escape hatch, use snake_case: `soku call ads gaql_search --payload '{...}'`.
|
|
169
170
|
|
|
171
|
+
### PostHog customer analytics
|
|
172
|
+
|
|
173
|
+
PostHog data uses the same backend MCP forwarding gateway as the sandbox agent.
|
|
174
|
+
Start by listing the current brand's granted projects, then inspect the live
|
|
175
|
+
tool menu, then run an allowlisted read tool. Do not ask the user for a project
|
|
176
|
+
id before listing projects.
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
soku posthog list-projects
|
|
180
|
+
soku posthog list-tools --project-id 12345
|
|
181
|
+
soku posthog query --project-id 12345 --tool execute-sql \
|
|
182
|
+
--arguments '{"query":"SELECT count() FROM events WHERE event = '\''$pageview'\''"}'
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Use `read-data-schema` before writing HogQL if field names are unclear:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
soku posthog query --project-id 12345 --tool read-data-schema --arguments '{}'
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The CLI default read surface does not expose `posthog/request_change`; writes and
|
|
192
|
+
unvetted PostHog MCP tools remain outside the generated command tree.
|
|
193
|
+
|
|
170
194
|
### Raw escape hatch
|
|
171
195
|
|
|
172
196
|
`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:
|
|
|
176
200
|
```bash
|
|
177
201
|
soku call ads list_ad_accounts -p platform=google
|
|
178
202
|
soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
|
|
203
|
+
soku call posthog query --payload '{"project_id":"12345","tool":"execute-sql","arguments":{"query":"SELECT count() FROM events"}}'
|
|
179
204
|
```
|
|
180
205
|
|
|
181
206
|
## SEO Hosting domain connections
|