@soku-ai/cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/skills/unzip.js

@@ -7,7 +7,7 @@
  * (stripped) root. Pure — returns a relpath→bytes map without touching disk, so
  * it is unit-testable and the caller decides where to write. */
 import { unzipSync } from 'fflate';
-const ALLOWED_EXTENSIONS = new Set(['.md', '.json', '.txt', '.yaml', '.yml', '.csv']);
+const ALLOWED_EXTENSIONS = new Set(['.md', '.py', '.json', '.txt', '.yaml', '.yml', '.csv']);
 const MAX_FILE_COUNT = 100;
 const MAX_SINGLE_FILE_BYTES = 10 * 1024 * 1024;
 const MAX_TOTAL_BYTES = 50 * 1024 * 1024;

package/dist/skills/unzip.js.map

@@ -1 +1 @@
-{"version":3,"file":"unzip.js","sourceRoot":"","sources":["../../src/skills/unzip.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"unzip.js","sourceRoot":"","sources":["../../src/skills/unzip.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.13";
+export declare const CLI_VERSION = "0.1.0-alpha.15";
 //# 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.13';
+export const CLI_VERSION = '0.1.0-alpha.15';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,17 +1,16 @@
 {
   "name": "@soku-ai/cli",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "description": "Soku CLI — call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.",
-  "license": "Proprietary",
-  "author": "Soku",
+  "license": "MIT",
+  "author": "About Intelligence",
   "homepage": "https://soku.ai/cli",
   "bugs": {
-    "url": "https://github.com/About-Intelligence/nex-studio/issues"
+    "url": "https://github.com/About-Intelligence/soku-cli/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/About-Intelligence/nex-studio.git",
-    "directory": "apps/cli"
+    "url": "git+https://github.com/About-Intelligence/soku-cli.git"
   },
   "keywords": [
     "soku",
@@ -34,6 +33,7 @@
   "engines": {
     "node": ">=20"
   },
+  "packageManager": "pnpm@10.28.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -42,7 +42,6 @@
     "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json dist/generated/capabilities.json",
     "typecheck": "tsc --noEmit",
     "test": "tsc -p tsconfig.test.json && find .test-build -name '*.test.js' -print | sort | xargs node --test",
-    "gen:capabilities": "uv run --project ../.. python ../../scripts/gen_cli_capabilities.py",
     "clean": "rm -rf dist .test-build",
     "postinstall": "node postinstall.cjs",
     "prepublishOnly": "pnpm run clean && pnpm run build"

package/skills/soku/SKILL.md

@@ -3,11 +3,12 @@ name: soku
 description: >-
   Use when calling Soku CLI capabilities from a shell: auth, workspace
   selection, ads/GA4/PostHog data reads, typed ads writes, SEO Hosting,
-  automations, Context Hub files, temporary file publishing, brand skills,
-  third-party egress, review-gated writes, skill installation, or CLI updates.
-license: Proprietary
+  automations, Context Hub files, migrating context or project files from
+  Claude, temporary file publishing, brand skills, third-party egress,
+  review-gated writes, skill installation, or CLI updates.
+license: MIT
 metadata:
-  author: nex-ad
+  author: About Intelligence
   version: "0.4"
 ---
 
@@ -26,10 +27,11 @@ Read only the reference files needed for the user's task:
 | --- | --- |
 | First-time setup, expired token, workspace selection, org/brand ambiguity | `references/auth-workspace.md` |
 | Ads, GA4, or PostHog reads; raw `soku call`; command discovery | `references/data-capabilities.md` and `references/capability-flow.md` |
-| Meta/Google Ads writes, uploads, bulk create, review-gated approval | `references/ads-write.md` |
+| Meta/Google/ChatGPT Ads writes, uploads, bulk create, review-gated approval | `references/ads-write.md` |
 | SEO Hosting, automations, Context Hub files, temporary public file URLs | `references/seo-automation-files.md` |
 | Third-party APIs through server-side credential injection; security rules | `references/egress-security.md` |
 | Installing, updating, or removing Soku-managed local skills | `references/skills-updates.md` |
+| Migrate context, project files, or workspaces from Claude into Soku | Run `soku skill install migrate-from-claude`, then read the installed `soku-migrate-from-claude` skill. |
 
 For an installed business skill such as `soku-ads-report`, read that skill too.
 Business skills carry their own "Running this skill with the Soku CLI" section.
@@ -73,8 +75,14 @@ soku <namespace> <action> --help
 - Never ask the user to paste third-party provider keys for covered providers.
 - Do not fail just because an upstream provider key env var is unset. Use
   `soku egress -- curl ...` for covered third-party APIs.
-- Do not approve review-gated writes on the user's behalf. Surface the
-  `review_id` and let the user run `soku review approve <id>`.
+- A human must authorize every review-gated write — but don't force a
+  copy-paste. If your harness prompts for explicit human confirmation before
+  each shell command (e.g. Claude Code's permission prompt), you MAY run
+  `soku review approve <id>` yourself after showing the user the diff/summary;
+  that confirmation prompt is the human gate. Never allowlist or auto-approve
+  `soku review approve`/`deny`, and never approve a write the user has not seen.
+  If your harness runs commands without per-command human confirmation, do NOT
+  self-approve — surface the `review_id` for the user to run.
 - Pass user values as separate argv elements. Do not build a shell command by
   string-concatenating untrusted values.
 - Do not scan local repo files, `AGENTS.md`, or `context/` folders for Soku

package/skills/soku/references/ads-write.md

@@ -1,8 +1,8 @@
 # Ads Writes
 
-Meta and Google write commands use typed CLI surfaces where available. Most
-delivery-changing writes are review-gated: the command creates a pending review
-and does not execute until a human approves.
+Meta, Google, and ChatGPT Ads write commands use typed CLI surfaces where
+available. Most delivery-changing writes are review-gated: the command creates a
+pending review and does not execute until a human approves.
 
 ## Prerequisites
 
@@ -19,10 +19,25 @@ delivery-changing write still returns a pending review for a human to approve.
 
 ```bash
 soku ads meta account pages --account-id <meta_account_id>
+soku ads meta account instagram --account-id <meta_account_id>
 soku ads meta campaign get --account-id <meta_account_id> --campaign-id <campaign_id>
 soku ads meta ad get --account-id <meta_account_id> --ad-id <ad_id>
 ```
 
+### Instagram identity (required for IG placements)
+
+Before creating any creative that runs on Instagram, resolve the
+**ad-account-connected** IG identity. The public IG `@handle` or the Facebook
+Page id is rejected by the ads API — you must use the id returned by:
+
+```bash
+soku ads meta account instagram --account-id <meta_account_id>
+```
+
+Pass that `data[].id` as `instagram_user_id` (e.g. `-p instagram_user_id=<id>`)
+when building the creative. An empty result means no IG account is connected to
+the ad account — connect it in Business Manager first.
+
 ## Meta Assets
 
 Image upload mutates the Meta asset library but does not change delivery, so it
@@ -82,6 +97,23 @@ soku ads meta ad create \
   --summary "Create paused Meta ad Hero image ad"
 ```
 
+Dynamic creative (Advantage+ creative) uses `--asset-feed-spec` instead of a
+single asset — Meta auto-combines the arrays. It is a primary media source, so
+it is mutually exclusive with `--image-hash` / `--video-id` /
+`--child-attachments`; the spec needs at least one of `images`/`videos` plus
+`ad_formats`, and CTA / lead-form wiring goes inside the spec
+(`call_to_action_types`), not as top-level flags. The ad set must be
+dynamic-creative-enabled (`soku ads meta adset create ... -p is_dynamic_creative=true`).
+
+```bash
+soku ads meta creative create \
+  --account-id <meta_account_id> \
+  --name "Dynamic creative" \
+  --page-id <page_id> \
+  --asset-feed-spec '{"images":[{"hash":"<hash1>"},{"hash":"<hash2>"}],"bodies":[{"text":"Primary text A"},{"text":"Primary text B"}],"titles":[{"text":"Headline A"}],"link_urls":[{"website_url":"https://example.com"}],"call_to_action_types":["LEARN_MORE"],"ad_formats":["SINGLE_IMAGE"]}' \
+  --summary "Create Meta dynamic creative"
+```
+
 Status controls exist at delivery levels:
 
 ```bash
@@ -123,6 +155,35 @@ soku ads google keyword --help
 The command path determines platform. Do not add `--platform`; the CLI injects
 `platform=google`.
 
+## ChatGPT Ads Writes
+
+ChatGPT Ads uses the generic `ads` action surface. The platform object model is
+ad unit first, campaign second:
+
+1. Create one or more ad units with `ads/create_ad_unit`.
+2. Create the campaign with `ads/create_campaign`, `platform=chatgpt_ads`, and a
+   non-empty `ad_unit_ids` list.
+3. Keep new campaigns paused. The backend forces create to paused; do not submit
+   `update_campaign(status=active)` unless the user explicitly asks for
+   activation and approves that exact review.
+
+Use `soku call` when a typed command is not obvious:
+
+```bash
+soku call ads create_ad_unit \
+  --payload '{"platform":"chatgpt_ads","account_id":"<account_id>","platform_extras":{"description":"Ad unit description","landing_page":"https://example.com/?utm_source=chatgpt_ads","static_ad_text":"Primary text","static_cta":"Learn more"}}' \
+  --summary "Create paused ChatGPT Ads ad unit input"
+
+soku call ads create_campaign \
+  --payload '{"platform":"chatgpt_ads","account_id":"<account_id>","name":"Launch Test","budget_daily_micros":300000000,"platform_extras":{"landing_page":"https://example.com/?utm_source=chatgpt_ads","campaign_objective":"clicks","ad_unit_ids":["<ad_unit_id>"]}}' \
+  --summary "Create paused ChatGPT Ads campaign Launch Test"
+```
+
+Available ChatGPT Ads write actions: `create_ad_unit`, `create_campaign`,
+`generate_ad_units`, `add_campaign_ad_units`, `replace_campaign_ad_units`,
+`update_campaign`, and `archive_ad_unit`. Treat `archive_ad_unit` as a toggle:
+verify current state before using it.
+
 ## Review Gate
 
 Review-gated commands return a review id:
@@ -132,6 +193,10 @@ soku review list
 soku review show <review_id>
 ```
 
-As an agent, show the review id and summary to the user. Do not approve on the
-user's behalf. Approval is single-use; failed approval is terminal, so create a
-fresh review for retry.
+As an agent, always show the review id and summary to the user first — a human
+must authorize the write. If your harness prompts for explicit human
+confirmation before each shell command (e.g. Claude Code's permission prompt),
+you MAY then run `soku review approve <id>` yourself: that prompt is the human
+gate, so never allowlist or auto-approve it. If your harness auto-runs commands
+without confirmation, do not self-approve — let the user run it. Approval is
+single-use; failed approval is terminal, so create a fresh review for retry.

package/skills/soku/references/auth-workspace.md

@@ -5,20 +5,36 @@ selected separately and sent on each workspace-scoped request.
 
 ## Agent Login: Non-Blocking Split Flow
 
+In a shell/container agent environment, prefix every `soku auth login` call —
+including the `--device-code` resume command below — with
+`SOKU_NO_KEYCHAIN=1`. The token is only written on the resume/poll step, so if
+each command runs in a fresh process (e.g. a new turn), an `export` on the
+first call alone will not cover it. The CLI's OS-keychain lookup can hang
+indefinitely with no output on boxes without a working keychain/D-Bus session
+— that hang never times out or errors, so there is nothing to catch and retry
+once it happens. The flag skips the OS keychain and stores the token in
+`~/.soku/credentials.json` (0600) instead; this has no downside for an agent
+session.
+
 Do not block a turn waiting for browser approval. Start login with:
 
 ```bash
-soku auth login --no-wait
+SOKU_NO_KEYCHAIN=1 soku auth login --no-wait
 ```
 
 Return the exact `verification_uri` and `user_code` to the user, then stop. Do
 not edit, re-encode, or reconstruct the URL. After the user approves, resume
-with the exact `next` command returned by the CLI:
+with the exact `next` command returned by the CLI, prefixed the same way:
 
 ```bash
-soku auth login --device-code <device_code>
+SOKU_NO_KEYCHAIN=1 soku auth login --device-code <device_code>
 ```
 
+If the browser approval page shows no workspace options (for example, a
+platform admin with no org memberships), the user can approve directly without
+selecting a workspace. Select a brand after login with
+`soku workspace use-brand`.
+
 For CI or headless contexts, use `SOKU_TOKEN`; do not echo it.
 
 ## Resources
@@ -54,6 +70,15 @@ soku brand list
 soku brand use <slug-or-id>
 ```
 
+## Platform Admins
+
+`soku auth status` reports `is_platform_admin`, which is `true` only for an
+active platform admin. An active platform admin can work across every active
+org without holding an org membership: `soku workspace use-brand`,
+`soku workspace resolve`, `soku org list`, and `soku brand list` cover the
+full set of active orgs and brands. Everyone else stays scoped to the orgs
+where they have a membership.
+
 ## Session State
 
 ```bash

package/skills/soku/references/data-capabilities.md

@@ -43,13 +43,35 @@ soku ads query-single-dimension \
   --date-end 2026-05-07
 ```
 
-ChatGPT Ads is synced reporting only — no campaign/ad write actions, and
-`query-multi-dimension` does not support it (use `query-single-dimension`
-instead).
+For reporting, ChatGPT Ads is still cached-first. `query-multi-dimension` does
+not support it (use `query-single-dimension` instead). Campaign/ad-unit writes
+now exist as review-gated `ads` actions; use `ads-write.md` for the write flow.
 
 ## Google Ads GAQL Fallback
 
-Use GAQL only when cached actions cannot answer the request:
+For common account, campaign, ad, keyword, search-term, and bidding-strategy
+reports, prefer the predefined report command over ad-hoc GAQL. It selects a
+stable set of columns and uses the last 30 days when dates are omitted:
+
+```bash
+soku ads get-google-ads-report \
+  --platform google \
+  --account-id <account_id> \
+  --report-type campaign \
+  --start-date 2026-06-01 \
+  --end-date 2026-06-30
+```
+
+Supported report types are `account`, `campaign`, `ad`, `keyword`,
+`search_term`, and `bidding_strategy`.
+
+Use GAQL only when cached actions cannot answer the request.
+
+`get-resource-metadata` needs a native Google credential; accounts connected
+through a proxy credential (Pipedream / Composio) fail with
+`field_metadata_unavailable` (400). In that case skip field discovery and run
+`gaql-search` directly — an unknown field fails with `gaql_invalid_query`
+naming the offending field.
 
 ```bash
 soku ads get-resource-metadata --platform google --account-id <account_id> --resource-name campaign

package/skills/soku/references/egress-security.md

@@ -43,7 +43,10 @@ success envelope. Soku-level failures use the normal CLI error envelope.
 
 - Never print the Soku access token.
 - Prefer `SOKU_TOKEN` for CI and headless agents.
-- Do not approve review-gated writes on behalf of the user.
+- Never approve a review-gated write the user has not seen, and never allowlist
+  or auto-approve `soku review approve`. Self-approving is allowed only when the
+  harness prompts for explicit human confirmation before each command (see the
+  review-gate rule in `references/ads-write.md`).
 - Avoid literal secret argv values. For Cloudflare Worker setup use
   `--cf-token-env` or `--cf-token-stdin`.
 - Pass user-provided values as separate argv elements.