@drip-apex/apex-cli 0.17.0 → 0.19.0

package/AGENTS.md

@@ -71,6 +71,8 @@ the first writes: `apex experiments create`, `apex goals create`,
 - Stale workspace or filesystem: pull fresh files, reapply your edits, and plan again.
 - Server limit errors: read the JSON error details; Apex includes server-owned limits when available.
 
+- Windows text corruption: use UTF-8 console settings; Apex repairs reversible Windows-1252 arguments and warns on stderr for U+FFFD. Set `APEX_ARGV_ENCODING=off` to disable repair.
+
 ## Platform Shop Administration
 
 - `apex admin shops archive <shopId>` archives a shop; headless callers must

package/README.md

@@ -185,7 +185,10 @@ including every subcommand, argument, option, and alias.
 - `apex triggers disable-capture` — disable setup capture and clear its expiry.
 - `apex domains` — manage install domains, and landing-page domains (`claim`, `register`, `status`, `unclaim`; registering asks for a price confirmation).
 - `apex handover` — manage cross-domain identity handover.
-- `apex install` — generate storefront installation snippets.
+- `apex install` — check storefront installation and generate a client guide.
+- `apex install kit` — print a ready-to-send installation guide as Markdown or JSON.
+- `apex install check` — verify the snippet, served config, and recent tracking.
+- `apex install steps` — show each installation step with when Apex first and last saw it (`--live` also checks the page and firewall access).
 - `apex funnels` — manage analytics funnels.
 - `apex webhooks` — manage shop webhooks.
 - `apex simulate` — simulate data-layer triggers without emitting events.
@@ -199,8 +202,40 @@ including every subcommand, argument, option, and alias.
 - `apex roadmap` — consume approved roadmap ideas and handoffs.
 - `apex harness` — develop AB Test Harness projects with live QA sessions.
 - `apex workspace` — check out, preview, and publish draft workspace files.
-- `apex goals` — manage conversion and revenue goals.
+- `apex goals` — manage conversion and revenue goals. Create/update accept `--page-id <id>` (UUID only, no lookup) or `--page <id-or-key>` (keys need `pages:read` for lookup); use one option.
 - `apex flags` — manage feature flags.
+- `apex surveys` — list, get, create, update, start, pause, complete, duplicate, and delete surveys.
+  Use `apex surveys list --status live` to filter, and `apex surveys create @survey.json`
+  or `apex surveys update <id> <body>` with inline JSON, `@file`, or a file path.
+  Both create and update also accept `--file survey.json` instead of a positional body;
+  providing both is an error. Their `--help` pages include the example and field defaults below.
+  `--json` returns the server body unchanged under `data`; publication warnings go to stderr.
+  Deleting a live or paused survey returns conflict exit code 5. Complete it before deleting.
+
+  Example `survey.json` for `apex surveys create --file survey.json` or
+  `apex surveys update <id> --file survey.json`:
+
+  ```json
+  {
+    "name": "Product feedback",
+    "questions": [{
+      "type": "single_choice",
+      "prompt": "What would help you decide?",
+      "options": [{"label": "More details"}, {"label": "Reviews"}, {"label": "Delivery info"}]
+    }],
+    "targeting": {"url": [{"type": "simple", "pattern": "/products/", "matchType": "contains"}]},
+    "sampling_rate": 0.5,
+    "frequency_cap": "once_per_visitor",
+    "card_style": "quiet",
+    "answer_goal": 100
+  }
+  ```
+
+  On create, `name` is required. Server defaults: `questions: []` (each question's
+  `required: true`), `targeting: null` (all pages/visitors), `sampling_rate: 1`,
+  `frequency_cap: "once_per_visitor"`, `card_style: "quiet"`, `answer_goal: null`,
+  `environment_key: "production"`, `placement: "sdk_page"`, `active_from: null`,
+  and `active_to: null`. Update accepts a partial body and keeps omitted fields unchanged.
 - `apex personalizations` — manage personalization deliveries.
 - `apex backlog` — manage experiment backlog items.
 - `apex signals` — inspect research and opportunity signals.
@@ -212,7 +247,7 @@ including every subcommand, argument, option, and alias.
 - `apex events export` — export all raw events in a fixed ISO 8601 window with automatic pagination.
 - `apex environments` — inspect delivery environments.
 - `apex analytics` — read shop analytics.
-- `apex pages` — manage page targeting resources.
+- `apex pages` — manage page targeting resources. Body keys are listed in `apex pages create --help` (and `update --help`); the CLI refuses a `url_pattern` or rule pattern whose shape contradicts `match_type` (`match_type_mismatch`) unless `--literal` is passed. `apex schema --json` carries the body schema.
 - `apex segments` — manage audience segments.
 - `apex exclusion-groups` — manage mutually exclusive experiment groups.
 - `apex targeting` — inspect targeting evaluation and coverage.
@@ -222,7 +257,7 @@ including every subcommand, argument, option, and alias.
 ### Shop configuration and operations
 
 - `apex external-pixels` — manage external pixel snippets.
-- `apex assets` — manage uploaded assets.
+- `apex assets` — manage uploaded assets. Upload returns `delivery_url`; embed that permanent URL in variation code. `public_url` expires after 300 seconds. Delivery is anonymous once the referencing experiment or snippet is published, and resolves through the owning shop's dashboard session or a QA preview before that. Only the absolute https form is recognized as an owned reference; protocol-relative or http forms are not granted at publication.
 - `apex landing-pages` — build landing pages with your own tools, then apply, preview, deploy and roll them back.
 - `apex brand` — manage brand context.
 - `apex shops` — manage shops and active-shop context.
@@ -526,6 +561,27 @@ latest/minimum policy is cached for seven days, so offline commands still enforc
 known floor. `APEX_NO_UPDATE_CHECK=1` disables the npm lookup and optional update
 notice, but never hides a required server-floor upgrade.
 
+### Windows: UTF-8 arguments
+
+A Windows console or launcher can decode UTF-8 as Windows-1252, turning `A – B · C`
+into `A – B · C`. On Windows, Apex automatically repairs reversible argument
+values at startup and writes a note to stderr. Set `APEX_ARGV_ENCODING=off` to
+keep arguments unchanged, or `APEX_ARGV_ENCODING=repair` to enable repair on
+another platform.
+
+Use UTF-8 in PowerShell:
+
+```powershell
+[Console]::InputEncoding = [Console]::OutputEncoding = [Text.Encoding]::UTF8
+```
+
+For Git Bash, set `LANG=C.UTF-8` and run `chcp 65001`.
+
+A replacement character (`�`, U+FFFD) means the shell already lost a character.
+Apex sends that value as given and warns on stderr. It also warns when stored
+experiment names, descriptions, variation names, or goal names contain U+FFFD.
+These notes leave JSON stdout unchanged.
+
 ## Usage telemetry
 
 Authenticated invocations send a process invocation ID, full command path, explicitly set
@@ -587,3 +643,7 @@ store ID (or null), invitation results and partial delivery status.
 ## Import past results
 
 Upload CSV or JSON exports with `apex results import --file results.csv --dry-run`. Apex suggests column and outcome-value mappings from the file; use repeated `--map 'Column=field'` and `--outcome-value 'Source value=won|lost|inconclusive'` overrides, then pass `--yes` for non-interactive confirmation. Files are inspected and previewed before any rows are written. `--source <name>` applies to the confirmed rows; the preview shows the uploaded file name.
+
+### Tracking health
+
+`apex tracking health [--json]` reads one tracking-health report for the current shop: every check with pass, warn, fail or unknown, a plain summary and the deciding numbers, plus each running test's first-hour verdict and traffic split overall and per device (`--json` carries visitors per arm per day). Exit code 0 is pass, 1 is warn or fail, 3 is unknown.