@drip-apex/apex-cli 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,26 @@
 # Apex CLI
 
+## Authentication and context
+
+Run `apex login` once to authenticate your account. Interactive login opens
+the browser and then lets you select an organization and shop. Inspect the
+credential and every accessible context with `apex whoami`, and switch the
+stored default with `apex use <org>[/<shop>]` (IDs and unambiguous name
+prefixes are accepted).
+
+Every command also accepts `--org <id>` and `--shop <id>`. Their precedence is
+command flag, then `DRIP_ORG` / `DRIP_SHOP`, then the context saved by
+`apex use`. Falling back to the stored `apex use` context emits one warning on
+stderr so scripts can see the implicit selection without corrupting JSON
+stdout. Flags and environment variables are explicit choices and stay silent.
+JSON envelopes echo the effective org, shop, and credential kind.
+
+Automation should continue injecting a narrow shop key per process with
+`DRIP_API_KEY`; it takes precedence over a stored user credential and does not
+change the stored login. Use `apex login --api-key apx_uk_...` for a headless
+account login or `apex login --api-key apx_...` to store a shop key. The old
+`apex login --user` spelling is a deprecated alias for `apex login`.
+
 Command-line tools for Apex experiments, draft workspaces, GitOps pushes, QA
 evidence, tracking checks, and agent handoffs.
 
@@ -114,6 +135,52 @@ means it is an `apex workspace checkout/status/publish` workspace. Keep the two
 formats in different folders; when the wrong command is run, Apex points to the
 matching status command.
 
+## Push config format
+
+Run `apex push -c <config>` to load a JavaScript or TypeScript config. The
+module's default export may be an experiment array, an object with an
+`experiments` array, or one experiment object. TypeScript (`.ts` or `.tsx`) is
+compiled and bundled on the fly with esbuild into a temporary ESM module;
+JavaScript (`.js`, `.mjs`, or `.cjs`) is imported directly.
+
+Each experiment accepts these fields:
+
+| Field | Format and mapping |
+| --- | --- |
+| `slug` | Required string and unique within the config; identifies the upsert. |
+| `name` | String sent as the experiment name. |
+| `id` | Optional string accepted in the config; it is not sent by `push`. |
+| `trafficAllocation` | Optional number sent as `traffic_allocation`; defaults to `1`. |
+| `targeting` | Optional value sent as targeting; defaults to `null`. |
+| `variations` | Array of variation objects described below. |
+| `goals` | Optional array of `{ id: string }`, mapped to `goal_ids`. |
+| `description` | Optional string; defaults to `null`. |
+| `storeUrl` / `store_url` | Optional string aliases sent as `store_url`; camelCase wins when both are present. |
+
+Each variation accepts:
+
+| Field | Format and mapping |
+| --- | --- |
+| `id` | Optional string, used as the fallback slug and name. |
+| `slug` | Optional string; falls back to `id`. |
+| `name` | Optional string; falls back to `id`, then `"Unnamed"`. |
+| `weight` | Number sent as the variation weight. |
+| `isControl` / `is_control` | Optional boolean aliases; defaults to `false`. |
+| `mutations` | Optional array; defaults to `[]`. |
+| `css` / `custom_css` | Optional string aliases sent as `custom_css`; defaults to `null`. |
+| `js` / `custom_js` | Optional string aliases sent as `custom_js`; defaults to `null`. |
+| `resetJs` / `reset_js` | Optional string aliases sent as `reset_js`; defaults to `null`. |
+| `antiFlickerSelectors` / `anti_flicker_selectors` | Optional string-array aliases; defaults to `[]`. |
+
+Push validates only that every experiment has a truthy `slug`, that slugs are
+not duplicated within the loaded config, and that the top-level export has one
+of the accepted shapes. It does **not** runtime-validate the other field types,
+required TypeScript fields (`name`, `variations`, or variation `weight`), nested
+goal/variation shapes, value ranges, or API-level constraints. The command
+upserts each experiment by slug with
+`PUT /api/v1/experiments/by-slug/:slug`; an existing slug is updated and a new
+slug is created.
+
 ## Full documentation
 
 Read the CLI reference on the docs site: