@drip-apex/apex-cli 0.2.1 → 0.4.0

package/AGENTS.md

@@ -20,7 +20,21 @@ Use `apex` as the canonical command name. `drip` is a compatibility alias.
 - JSON output is a stable contract: top level is `{ ok, version, command, data | error }`.
 - Diagnostics, prompts, progress, and update notices go to stderr.
 - Do not parse human tables. Use `apex schema --json` first if you need flags.
-- Keep command names exact. Do not infer fuzzy suggestions.
+- Keep command names exact. Do not infer or guess names from the CLI's
+  "did you mean" hints — those are stderr diagnostics for humans; machine
+  callers resolve names via `apex schema --json`.
+
+
+## Zero-Experiment Shop Bootstrap
+
+CLI-only bootstrap is supported for a fresh shop before any experiments exist.
+External tools should prove identity with the user credential only: run
+`apex org get --json`, then `apex shops get <shop-id> --json` (or
+`apex shops list --json` to select the shop). Do not invent separate identity
+proofs or infer access from experiment reads on an empty shop. After the user
+credential confirms the organization and shop, the shop credential can perform
+the first writes: `apex experiments create`, `apex goals create`,
+`apex workspace checkout`, and `apex workspace publish`.
 
 ## Exit Codes
 

package/README.md

@@ -1,5 +1,23 @@
 # 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`. 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.
 
@@ -28,15 +46,17 @@ DRIP_API_KEY=apx_your_key_here apex experiments list --json
 
 ```bash
 apex experiments list
+apex experiments list --include-archived
 apex experiments create --name "Redirect test" --type redirect \
   --source-url "https://shop.example/products/source" \
   --destination "https://landing.example/products/treatment"
-apex experiments pull <id-or-slug> --dir ./my-test
+apex experiments pull <id-or-slug> --out ./my-test
 apex experiments plan ./my-test --json
 apex experiments apply ./my-test --json
 apex experiments qa status ./my-test --json
+apex experiments screenshots <id-or-slug> --out ./screenshots
 
-apex workspace checkout <experimentId> --variation <variationId> --dir ./workspace
+apex workspace checkout <experimentId> --variation <variationId> --out ./workspace
 apex workspace dev ./workspace --no-open
 apex workspace publish ./workspace
 
@@ -46,6 +66,72 @@ apex schema --json
 
 Use `apex` as the canonical command name. `drip` is a compatibility alias.
 
+`apex experiments list` hides archived experiments by default. Pass
+`--include-archived` to include them; archived rows display their archive date
+when the API provides `archived_at`.
+
+## Command index
+
+Use `apex schema --json` to emit the complete machine-readable command surface,
+including every subcommand, argument, option, and alias.
+
+### Authentication and account
+
+- `apex login` — authenticate with a shop or user API key.
+- `apex logout` — remove stored credentials.
+- `apex whoami` — inspect the current credential and its validity.
+- `apex account` — manage the current user profile.
+- `apex keys` — manage shop API keys.
+- `apex org` — inspect and manage the organization.
+- `apex team` — manage organization members and invitations.
+
+### Experiments and delivery
+
+- `apex experiments` — create, inspect, operate, and synchronize experiments.
+  Use `apex experiments screenshots <id-or-slug>` to force-assign every capture, including control, to its variation server-side for deterministic screenshots; choose devices with `--devices`, filter treatments with `--variations`, and use `--json` for the signed result payload.
+- `apex push` — synchronize `.drip.config.ts` with Apex.
+- `apex preview` — open a variation QA preview.
+- `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 flags` — manage feature flags.
+- `apex personalizations` — manage personalization deliveries.
+- `apex backlog` — manage experiment backlog items.
+- `apex signals` — inspect research and opportunity signals.
+
+### Analytics, targeting, and tracking
+
+- `apex tracking` — diagnose storefront tracking.
+- `apex environments` — inspect delivery environments.
+- `apex analytics` — read shop analytics.
+- `apex pages` — manage page targeting resources.
+- `apex segments` — manage audience segments.
+- `apex exclusion-groups` — manage mutually exclusive experiment groups.
+- `apex targeting` — inspect targeting evaluation and coverage.
+- `apex audit-log` — inspect auditable account activity.
+- `apex inbox` — use the operator inbox.
+
+### Shop configuration and operations
+
+- `apex external-pixels` — manage external pixel snippets.
+- `apex assets` — manage uploaded assets.
+- `apex landing-pages` — discover landing pages.
+- `apex brand` — manage brand context.
+- `apex sos` — run operational diagnostics.
+- `apex shops` — manage shops and active-shop context.
+- `apex skills` — inspect agent skill guidance.
+- `apex admin` — run authorized administrative operations.
+- `apex schema` — emit the machine-readable CLI schema.
+
+## Which local format am I in?
+
+Inspect the marker under `.apex/`: `experiment-filesystem.json` means the
+folder belongs to `apex experiments pull/plan/apply`, while `session.json`
+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.
+
 ## Full documentation
 
 Read the CLI reference on the docs site: