@variantlab/cli 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,118 @@
 # @variantlab/cli
 
-Command-line tool for variantlab: init, generate, validate, eval.
+> Command-line tool for variantlab — scaffold, generate types, validate configs, and evaluate experiments.
 
-> **Status:** Phase 1 — Pre-alpha. Not ready for production use.
+![npm version](https://img.shields.io/npm/v/@variantlab/cli/alpha?label=npm&color=blue)
 
-See the [root README](../../README.md) for project overview, motivation, and roadmap.
+## Install
+
+```bash
+# Use via npx (no install needed)
+npx @variantlab/cli@alpha init
+
+# Or install globally
+npm install -g @variantlab/cli@alpha
+```
+
+## Commands
+
+### `variantlab init`
+
+Scaffold an `experiments.json` file with starter experiments.
+
+```bash
+variantlab init           # Creates experiments.json
+variantlab init --force   # Overwrite existing file
+```
+
+### `variantlab generate`
+
+Generate TypeScript types from your `experiments.json`. Experiment IDs and variant IDs become literal types — typos become compile errors.
+
+```bash
+variantlab generate                          # Default: reads experiments.json, writes variantlab.d.ts
+variantlab generate --config ./config.json   # Custom config path
+variantlab generate --out ./types/vl.d.ts    # Custom output path
+variantlab generate --watch                  # Regenerate on file changes
+```
+
+The generated `.d.ts` file provides:
+- `VariantLabExperiments` interface with all experiment IDs
+- `ExperimentId` union type
+- `VariantId<E>` mapped type per experiment
+- `VariantValueType<E>` for value experiments
+- Module augmentation for type-safe hooks
+
+### `variantlab validate`
+
+Validate an experiments config file against the schema.
+
+```bash
+variantlab validate                    # Validates ./experiments.json
+variantlab validate ./custom-path.json # Validate a specific file
+```
+
+Reports:
+- JSON parse errors
+- Schema violations (missing fields, wrong types)
+- Duplicate experiment IDs
+- Invalid default variant references
+- Invalid targeting predicates
+
+### `variantlab eval`
+
+Evaluate an experiment against a targeting context — useful for debugging why a user gets a specific variant.
+
+```bash
+# Inline context
+variantlab eval --experiment hero-layout --context '{"platform":"ios","screenSize":"small"}'
+
+# Context from file
+variantlab eval --experiment hero-layout --context-file ./test-context.json
+
+# Custom config path
+variantlab eval ./config.json --experiment hero-layout --context '{"userId":"user-123"}'
+```
+
+Shows:
+- Step-by-step targeting trace (pass/fail per field)
+- Final resolved variant
+- Assignment strategy used
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | File not found |
+| 2 | Validation error / invalid config |
+| 3 | I/O error |
+| 4 | Invalid arguments |
+
+## Global options
+
+```
+--help      Show help for any command
+--version   Show version
+--verbose   Enable verbose output
+```
+
+## Programmatic API
+
+All commands are also available as functions:
+
+```ts
+import { init, generate, validate, evalCommand } from "@variantlab/cli";
+
+await init({ force: true });
+await generate({ config: "./experiments.json", out: "./variantlab.d.ts" });
+await validate("./experiments.json");
+await evalCommand("./experiments.json", {
+  experiment: "hero-layout",
+  context: '{"platform":"ios"}',
+});
+```
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Command-line tool for variantlab: init, generate, validate, eval.",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "provenance": false
   },
   "dependencies": {
-    "@variantlab/core": "0.1.0"
+    "@variantlab/core": "0.1.1"
   },
   "keywords": [
     "ab-testing",