@siteoshq/cli 1.6.0 → 1.8.0

package/README.md

@@ -1,7 +1,7 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace, SEO and Integrations. This source prepares version 1.6.0; publishing is a separate release.
+Search, Trace, SEO and Integrations. This source prepares version 1.8.0; publishing is a separate release.
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -125,12 +125,28 @@ siteos project connect trace --json
 siteos trace environments --json
 siteos trace installation show --environment production --json
 siteos trace report --environment production --json
+siteos trace destinations --environment production --json
+siteos trace events --environment production --provider ga4 --period 7d --json
+siteos trace issues --environment production --state active --json
+siteos trace observations --environment production --provider ga4 --event purchase --json
 siteos integrations status --json
 siteos integrations connect --json
 ```
 
 Cookie/Trace draft editing and publication are separate commands with separate authorization
 scopes. Save commands take versioned JSON input; inspect `--help` and the focused plugin skill.
+
+Trace explorer commands require CLI 1.8.0 and the corresponding Trace server release. They return
+one page with `items`, `total`, `nextCursor`, `from` and `to`. Repeat the same filters with
+`--cursor <nextCursor>` to continue; omit the cursor to refresh the window. `trace issue show --id
+<uuid>` reads finding history, and `trace observation show --batch-id <uuid> --event-id <uuid>`
+reads a specific observation. These commands use read authority and the explicit Project
+environment binding. `custom` means the data layer source, not a confirmed destination.
+
+After reviewing a tracking plan, use `trace tracking-plan publish --expected-draft-version
+<number>` to publish that version. A conflict must be reread and reviewed; do not retry without
+the version guard. Existing installation and report commands remain compatible. Deployment of
+the Trace server and runtime precedes announcing the new explorer commands in the public plugin.
 Installation commands return the service-owned snippet and actual publication state. A Trace
 snippet is unavailable until runtime publication succeeds. Integrations connections belong to the
 Organization; provider authorization opens the shared browser flow, and notification destinations
@@ -281,3 +297,26 @@ Definitions include a generated SHA-256 `sourceExportId`; runtime sends it as `c
 A changed field requires a normal build/release, not a second hand-edited validation schema.
 `forms deployment-key list|revoke` manages release keys; submission keys cannot publish.
 See the SiteOS Forms skill for the portable generator and version serialization contract.
+
+
+## Website Analytics
+
+The source CLI includes `siteos analytics` for an explicitly connected Project environment. Check
+`siteos analytics --help` against the installed package and server before use; source availability
+does not establish publication. Start with `project status`, `analytics status` and
+`analytics installation`. Use `--environment <slug>` when selecting the target explicitly.
+
+`analytics settings show` returns the current revision. `analytics settings set --revision <n>`
+accepts partial `--enabled true|false`, `--cookie-events true|false` and
+`--minimal-realtime true|false` updates. Analytics collects independently by default. Native consent
+control belongs to Cookie's published `integrations.siteosAnalytics` switch in the same Project
+environment; attachment or a draft save does not enable it. External CMP gating is optional and
+must be configured before runtime initialization. Privacy signals and full opt-out still apply.
+Reload the website after configuration changes.
+
+`analytics events list|create|snippet`, campaigns, goals and funnels manage reviewed categorical
+definitions. Creation uses `--file <definition.json>`; reports and realtime read accepted data.
+`analytics monitoring prepare` prepares a Trace draft without publishing it. Auth grants are scoped
+to Analytics and the operation, with editor roles required for writes. Analytics is Unlimited in
+Usage during early access. See the canonical plugin's website Analytics skill for event contracts
+and the browser-to-report verification workflow; Search reports use `search analytics` separately.