@drip-apex/apex-cli 0.1.1 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,48 @@
+# Apex CLI Agent Contract
+
+Use `apex` as the canonical command name. `drip` is a compatibility alias.
+
+## Canonical Loop
+
+1. `apex experiments pull <id-or-slug> --dir <folder>`
+2. Edit only supported files in the pulled folder.
+3. `apex experiments plan <folder> --json`
+4. `apex experiments apply <folder> --json`
+5. `apex experiments qa status <folder> --json`
+6. Update QA with `apex experiments qa check`, `notes`, and `approve`.
+7. Publish or launch only through the dashboard approval surface.
+
+## Invariants
+
+- Never hand-edit `qa.json` or `launch.json`.
+- Launch is dashboard-only. The API and CLI do not start traffic.
+- Prefer `--json`; piped stdout defaults to JSON automatically.
+- 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.
+
+## Exit Codes
+
+- `0`: success
+- `1`: general failure
+- `2`: auth or permission failure
+- `3`: validation failure
+- `4`: confirmation required; inspect `error.details.retry`
+- `5`: conflict, including stale filesystem state where detected
+
+## Recovery
+
+- Missing auth: run `apex login` interactively, or set `DRIP_API_KEY`.
+- Headless login: pass `--api-key` or set `DRIP_API_KEY`; do not wait for prompts.
+- Do not wait for prompts in CI or agent runs. If a command returns exit `4`, rerun with the exact flag named in the JSON error details only after checking the plan or destructive action.
+- Apply invalidates QA: inspect `apex experiments plan`, then rerun apply with `--force` if intended.
+- 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.
+
+## Filesystem Rules
+
+- Treat `.apex/` as CLI-owned metadata.
+- Edit experiment files, variation code, metrics, and targeting only through supported paths.
+- Do not bypass the variation artifact persistence path with direct API writes.
+- Keep generated evidence outside `qa.json`; attach it through QA commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drip Trading GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,7 @@
 # Apex CLI
 
-Command-line tools for Apex experiments, approved roadmap ideas, and draft workspaces.
+Command-line tools for Apex experiments, draft workspaces, GitOps pushes, QA
+evidence, tracking checks, and agent handoffs.
 
 ## Install
 
@@ -8,45 +9,45 @@ Command-line tools for Apex experiments, approved roadmap ideas, and draft works
 npm install -g @drip-apex/apex-cli
 ```
 
-## Login
+## Authenticate
 
-Create an Apex API key at:
-
-```text
-https://app.drip-apex.com/api-keys
+```bash
+apex login
+apex whoami
 ```
 
-Then run:
+`apex login` opens the default browser OAuth flow at Apex `/cli/login`. For
+headless environments, use an existing API key:
 
 ```bash
-apex login
+apex login --api-key apx_your_key_here
+DRIP_API_KEY=apx_your_key_here apex experiments list --json
 ```
 
-Check auth:
+## Common usage
 
 ```bash
-apex whoami
 apex experiments list
-```
+apex experiments pull <id-or-slug> --dir ./my-test
+apex experiments plan ./my-test --json
+apex experiments apply ./my-test --json
+apex experiments qa status ./my-test --json
 
-## Approved Roadmap Ideas
+apex workspace checkout <experimentId> --variation <variationId> --dir ./workspace
+apex workspace dev ./workspace --no-open
+apex workspace publish ./workspace
 
-```bash
-apex roadmap approved --unbuilt
-apex roadmap handoff <roadmapItemId> --instructions
+apex push --dry-run
+apex schema --json
 ```
 
-## Draft Workspace Preview
+Use `apex` as the canonical command name. `drip` is a compatibility alias.
 
-```bash
-apex workspace checkout <experimentId> --variation <variationId> --dir ./my-test
-apex workspace dev ./my-test
-```
+## Full documentation
 
-Publish back to Apex after QA:
+Read the CLI reference on the docs site:
 
-```bash
-apex workspace publish ./my-test
-```
+- https://docs.drip-apex.com/cli/install-auth
+- https://docs.drip-apex.com/cli/commands-output
 
-The preview URL includes a short-lived `drip_harness=apx_hs_...` token. Treat it like a secret.
+Maintainers: see the [CLI release runbook](../../docs/cli-releases.md).