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

package/skills/soku/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: soku
 description: >-
-  Use when calling Soku ads/GA4 marketing-data capabilities from the shell —
+  Use when calling Soku ads/GA4 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`, handling 401/403
+  errors, or installing/updating the Soku CLI.
 license: Proprietary
 metadata:
   author: nex-ad
@@ -14,10 +16,10 @@ metadata:
 
 # 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, 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
 
@@ -125,7 +127,7 @@ 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 resources list                       # what's granted (e.g. data-infra, seo-hosting)
 soku --help                               # namespaces: ads, ga4, …
 soku ads --help                           # actions in the ads namespace
 soku ads query-single-dimension --help    # flags, types, and usage for one action
@@ -176,6 +178,95 @@ soku call ads list_ad_accounts -p platform=google
 soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
 ```
 
+## 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 `posts` commands for the same SEO Hosting content actions exposed to
+runtime agents through `seo_hosting/*`. These create and manage owned-media web
+pages on the brand's connected domain; they are not social posts.
+
+Always check status first:
+
+```bash
+soku seo-hosting status
+```
+
+If `live` is false, do not create or publish posts yet; connect or fix a domain
+first. When hosting is live:
+
+```bash
+soku seo-hosting posts list --section blog --status draft
+soku seo-hosting posts get <post_id>
+soku seo-hosting posts create --title "How to ..." --section blog --body-file post.md
+soku seo-hosting posts update <post_id> --body-file revised.md
+soku seo-hosting posts publish <post_id>
+soku seo-hosting posts delete <post_id> --confirm
+```
+
+`create` requires `--title` plus exactly one body source: `--body`,
+`--body-file`, or `--body-stdin`. Optional metadata flags are `--slug`,
+`--excerpt`, `--cover-image-url`, `--author-name`, and `--seo '<json object>'`.
+`update` supports mutable fields only; section and slug are intentionally not
+editable through the CLI.
+
+Writes run immediately (the same no-review behavior as the first-party
+`seo_hosting` data actions), 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**.

package/README.md

@@ -1,129 +0,0 @@
-# @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
-
-```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 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:
-
-```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
-```
-
-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`.
-
-```bash
-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 |