@drip-apex/apex-cli 0.15.3 → 0.15.4

package/AGENTS.md

@@ -2,6 +2,8 @@
 
 Use `apex` as the canonical command name. `drip` is a compatibility alias.
 
+Install the CLI once with `npm install -g @drip-apex/apex-cli` and call `apex`; `apex --help` and `apex schema --json` need no network. Do not run `npx @drip-apex/apex-cli@latest` per command: npx contacts the npm registry before the CLI starts and hangs with no output when the registry is slow or blocked.
+
 ## Choosing a workflow
 
 The default loop for agents building or editing a test is `apex experiments pull`, edit supported files, `apex experiments plan`, `apex experiments apply`, then `apex experiments qa status`.
@@ -58,6 +60,7 @@ the first writes: `apex experiments create`, `apex goals create`,
 - `3`: validation failure
 - `4`: confirmation required; inspect `error.details.retry`
 - `5`: conflict, including stale filesystem state where detected
+- `6`: a check command reported a definite failing verdict
 
 ## Recovery
 
@@ -133,11 +136,13 @@ Filesystem apply caches uploaded asset URLs by byte SHA-256 in `.apex/experiment
 
 ## Error recovery and update notices
 
+Every JSON envelope may carry update and warnings. If update.required is true, or a warning has code cli_upgrade_required, first check whether the command succeeded (ok is true). If it succeeded, do not rerun it: run apex upgrade (or the command in update.command) before any further work. If it failed with the upgrade-required error (code cli_upgrade_required), run apex upgrade, then rerun the same command. Tell your user you upgraded. If only cli_update_available is present, finish the current task, then upgrade before the next one.
+
 JSON errors keep the numeric `error.code` exit code and add `error.reason`,
 `error.next_steps` (an array of `{ command, why }`), and optional `error.request_id`.
 The request ID comes from `x-request-id`, falling back to `x-vercel-id` (the Apex app) and then `cf-ray`; include it
 when reporting an API failure. API-provided reason codes are preserved verbatim.
-Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`,
+Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`, `shop_context_mismatch`, `install_check_failed`,
 `validation_failed`, `confirmation_required`, `conflict`, `not_found`,
 `rate_limited`, `network_timeout`, `network_connect_timeout`, `network_dns`,
 `network_refused`, `network_reset`, `network_tls`, `network_unknown`,
@@ -153,12 +158,13 @@ command: authentication failures exit **2** (previously 4), invalid local input
 **3**, conflict **5**, anything else **1**). The `TRIGGERS_AUTH`, `TRIGGERS_CONFIG_ABSENT` and `TRIGGERS_NO_DATA`
 verdict prefixes are unchanged, so scripts can key on them instead of exit codes.
 
-When a newer CLI release is available, success and error JSON envelopes include
-`update: { current, latest, breaking, notes_url }`. `breaking` is true for a
-major-version change, or a minor-version change while the installed version is
-0.x. `notes_url` links to the published CLI command/output documentation. A one-line notice also goes
-to stderr, including in non-TTY agent runs; stdout remains one JSON document.
-The latest version is cached in `~/.drip/update-check.json` for 24 hours, and a
-failed lookup for one hour. The best-effort check has a 900 ms budget, never fails
-the command, and is skipped when the `CI` environment variable is set. Set
-`APEX_NO_UPDATE_CHECK=1` to disable both the check and the `update` field.
+Every JSON envelope may carry `update` and `warnings`. The update object includes
+`current`, `latest`, optional `minimum`, `required`, `breaking`, `command`, and
+`notes_url`; warnings use `{ code, message }`. The exact install command is
+`npm install -g @drip-apex/apex-cli@latest`, and `apex upgrade` runs it (`--dry-run`
+only prints it). Set `APEX_NPM_BIN` to choose the npm binary.
+
+The npm latest version is cached for 24 hours (failed lookups for one hour). Server
+latest/minimum policy is cached for seven days, so offline commands still enforce a
+known floor. `APEX_NO_UPDATE_CHECK=1` disables the npm lookup and optional update
+notice, but never hides a required server-floor upgrade.

package/README.md

@@ -25,14 +25,17 @@ apex install check --shop-id "$APEX_SHOP_ID"
 is `NO_DATA`, never a healthy result. Tracking verification renders compact event-property previews
 in human mode and preserves complete properties in `--json`. Install checks report the served
 `dataLayerTriggers` count and whether an enabled revenue trigger exists.
+`--shop-id` selects the shop for every install-check API request. A definite install-check or doctor failure exits `6`; install-check JSON lists `error.details.failed_checks`.
 
 ## 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).
+stored default with `apex use <org>[/<shop>]` or `apex use --org <org> --shop
+<shop>` (IDs and unambiguous name prefixes are accepted). When authentication
+comes only from an environment key, `apex use` returns `context_not_persistable`
+with the `DRIP_ORG` and `DRIP_SHOP` values to export instead of writing a credential file.
 
 Every command also accepts `--org <id>` and `--shop <id>`. Their precedence is
 command flag, then `DRIP_ORG` / `DRIP_SHOP`, then the context saved by
@@ -56,6 +59,8 @@ evidence, tracking checks, and agent handoffs.
 npm install -g @drip-apex/apex-cli
 ```
 
+Install the CLI once, then call `apex` directly. `apex --help` and `apex schema --json` answer without network access. Do not run `npx @drip-apex/apex-cli@latest` for every command: npx asks the npm registry for the package before the CLI starts, so it prints nothing and hangs when the registry is slow or blocked, which is common in agent sandboxes. Update with `npm install -g @drip-apex/apex-cli@latest`.
+
 ## Authenticate
 
 ```bash
@@ -158,6 +163,7 @@ including every subcommand, argument, option, and alias.
 - `apex logout` — remove stored credentials.
 - `apex whoami` — inspect the current credential and its validity.
 - `apex use` — select the current organization and shop context.
+- `apex upgrade` — install the latest Apex CLI; `--dry-run` prints the command.
 - `apex account` — manage the current user profile.
 - `apex keys` — manage shop API keys.
 - `apex org` — inspect and manage the organization.
@@ -486,7 +492,7 @@ JSON errors keep the numeric `error.code` exit code and add `error.reason`,
 `error.next_steps` (an array of `{ command, why }`), and optional `error.request_id`.
 The request ID comes from `x-request-id`, falling back to `x-vercel-id` (the Apex app) and then `cf-ray`; include it
 when reporting an API failure. API-provided reason codes are preserved verbatim.
-Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`,
+Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`, `shop_context_mismatch`, `install_check_failed`,
 `validation_failed`, `confirmation_required`, `conflict`, `not_found`,
 `rate_limited`, `network_timeout`, `network_connect_timeout`, `network_dns`,
 `network_refused`, `network_reset`, `network_tls`, `network_unknown`,
@@ -502,30 +508,46 @@ command: authentication failures exit **2** (previously 4), invalid local input
 **3**, conflict **5**, anything else **1**). The `TRIGGERS_AUTH`, `TRIGGERS_CONFIG_ABSENT` and `TRIGGERS_NO_DATA`
 verdict prefixes are unchanged, so scripts can key on them instead of exit codes.
 
-When a newer CLI release is available, success and error JSON envelopes include
-`update: { current, latest, breaking, notes_url }`. `breaking` is true for a
-major-version change, or a minor-version change while the installed version is
-0.x. `notes_url` links to the published CLI command/output documentation. A one-line notice also goes
-to stderr, including in non-TTY agent runs; stdout remains one JSON document.
-The latest version is cached in `~/.drip/update-check.json` for 24 hours, and a
-failed lookup for one hour. The best-effort check has a 900 ms budget, never fails
-the command, and is skipped when the `CI` environment variable is set. Set
-`APEX_NO_UPDATE_CHECK=1` to disable both the check and the `update` field.
+Every JSON envelope may carry `update` and `warnings`. The update object includes
+`current`, `latest`, optional `minimum`, `required`, `breaking`, `command`, and
+`notes_url`; warnings use `{ code, message }`. The exact install command is
+`npm install -g @drip-apex/apex-cli@latest`, and `apex upgrade` runs it (`--dry-run`
+only prints it). Set `APEX_NPM_BIN` to choose the npm binary.
+
+The npm latest version is cached for 24 hours (failed lookups for one hour). Server
+latest/minimum policy is cached for seven days, so offline commands still enforce a
+known floor. `APEX_NO_UPDATE_CHECK=1` disables the npm lookup and optional update
+notice, but never hides a required server-floor upgrade.
 
 ## Usage telemetry
 
-Authenticated invocations send a process invocation ID, command path, explicitly set
+Authenticated invocations send a process invocation ID, full command path, explicitly set
 option names (never values), JSON/TTY modes, credential kind, organization/shop IDs,
-CLI/Node versions, platform, exit code, error class, API response count, first failed
-response status/code/request ID and normalized route, and duration. Parse failures
-send `(parse)` and the first non-option token as `attempted`, redacted when it looks
-like a credential, URL or path, or is longer than 40 characters. No argument values beyond
-that attempted token, file contents, prompts, selectors, URLs, error messages, or secrets
-are sent. Login/logout, tests, the mock transport, and runs with no resolvable credentials
-(neither stored nor environment) skip telemetry. Environment-credential runs
-(`APEX_API_KEY` or `DRIP_API_KEY`) are recorded with credential kind `env` unless
-`APEX_TELEMETRY=0`. Set `APEX_TELEMETRY=0` to disable the beacon. The best-effort request has an
-800 ms timeout and never changes command output or exit status.
+CLI/Node versions, platform, exit code, error class and code, API response count, the first
+failed response's status/code/request ID and normalized route, and total duration. Up to the
+first 25 API calls include their method, normalized route, status, duration, and bounded
+`Server-Timing` header. Requests whose path contains an experiment or landing-page UUID also
+send that UUID and its entity type; slugs are not captured.
+
+Help commands are named `(help) <full command path>`. Parse failures are named `(parse)` and
+send the known command path plus only a mistyped subcommand as `attempted`. Potential
+credentials, URLs, paths, long keys, and other sensitive-looking attempted tokens are
+redacted; positional argument values are never sent.
+
+Agent hosts can be reported as a fixed label such as `claude-code`, `codex`, or `terminal`,
+never as an environment value. Set `APEX_AGENT_HOST` to one of `claude-code`, `codex`,
+`cursor`, `grok`, `gemini`, `copilot`, or `other` to override automatic detection.
+`APEX_SESSION_ID` may supply a 1–128 character identifier containing letters, digits, dots,
+underscores, colons, or hyphens; choose a non-secret value. When that variable is absent or
+invalid, supported agent session IDs are SHA-256 hashed locally and only the `h_`-prefixed
+first 32 hexadecimal characters are sent.
+
+No argument or option values, file contents or paths, prompts, selectors, URLs, error text,
+environment values, raw agent session IDs, or secrets are sent. Login/logout, tests, the mock
+transport, and runs with no resolvable credentials (neither stored nor environment) skip
+telemetry. Environment-credential runs (`APEX_API_KEY` or `DRIP_API_KEY`) are recorded with
+credential kind `env` unless `APEX_TELEMETRY=0`. Set `APEX_TELEMETRY=0` to disable the beacon.
+The best-effort request has an 800 ms timeout and never changes command output or exit status.
 
 MP4 (`video/mp4`) and WebM (`video/webm`) videos are hosted directly by Apex.
 Each version holds at most 300 files and 100 MB; each video is limited to 50 MB,