@avsbhq/cli 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+# @avsbhq/cli
+
+CLI tool for local A/B experiment and project script development with the [A vs B](https://app.avsb.cloud) platform.
+
+Clone experiments, edit variation code locally in your preferred editor, manage project-level scripts, and push changes back to the platform.
+
+## Install
+
+```bash
+npm install -g @avsbhq/cli
+```
+
+Verify the installation:
+
+```bash
+avsb --version
+```
+
+## Authentication
+
+Before using the CLI, you need to generate a personal API token from the platform.
+
+### Step 1: Generate a token
+
+1. Log in to the [A vs B platform](https://app.avsb.cloud)
+2. Go to **Account Settings** (click your avatar in the top bar)
+3. Open the **Personal Auth Tokens** tab
+4. Click **Generate Token**, give it a name (e.g. "CLI access"), and click **Generate**
+5. Copy the token immediately -- it won't be shown again
+
+> You need the **Developer** role or higher in your organization to generate tokens.
+
+### Step 2: Log in with the CLI
+
+```bash
+avsb login
+```
+
+You'll be prompted for:
+
+- **API token** -- paste the token you copied
+- **Default script language** -- JavaScript or TypeScript
+- **Default style language** -- CSS or SCSS
+
+### Logout
+
+To remove stored credentials:
+
+```bash
+avsb logout
+```
+
+## Quick start
+
+### Experiments
+
+```bash
+# 1. Log in (see Authentication above)
+avsb login
+
+# 2. Clone an experiment
+avsb clone EXP-42
+
+# 3. Edit the variation code in your editor
+cd exp-42
+
+# 4. Start dev server with live reload
+avsb dev
+
+# 5. Push changes back to the platform
+avsb push
+```
+
+### Project scripts
+
+```bash
+# 1. Pull a project script
+avsb project pull PRJ-10
+
+# 2. Edit the project script in your editor
+cd project-10
+
+# 3. Start dev server with live reload
+avsb project dev
+
+# 4. Push changes back to the platform
+avsb project push
+```
+
+## Commands
+
+### General
+
+| Command        | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `avsb login`   | Authenticate with the A vs B platform                 |
+| `avsb logout`  | Log out and remove stored credentials                 |
+| `avsb org`     | Show current organization                             |
+| `avsb org list`   | List all organizations accessible with your token  |
+| `avsb org switch` | Switch to a different organization                 |
+
+### Experiments
+
+| Command                   | Description                                                       |
+| ------------------------- | ----------------------------------------------------------------- |
+| `avsb clone <experiment>` | Clone an experiment locally (accepts URL, EXP-123, or numeric ID) |
+| `avsb status`             | Show the status of the current experiment                         |
+| `avsb dev`                | Start dev server with live reload for the browser extension       |
+| `avsb pull`               | Pull latest experiment data from the platform                     |
+| `avsb push`               | Compile and push local changes to the platform                    |
+
+### Project scripts
+
+| Command                      | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `avsb project pull <project>` | Pull a project script (accepts PRJ-42 or numeric ID)          |
+| `avsb project push`           | Compile and push project script to the platform               |
+| `avsb project dev`            | Watch project script and hot-reload via browser extension     |
+
+## Experiment workflow
+
+### Clone
+
+Fetches experiment data and scaffolds a local directory with editable files.
+
+```bash
+avsb clone EXP-42          # by experiment ID
+avsb clone 42              # by numeric ID
+avsb clone <platform-url>  # by URL
+```
+
+### Push
+
+Compiles your local TypeScript/SCSS and pushes the built output to the platform.
+
+Before pushing, the CLI checks if the remote experiment has changed since your last sync. If changes are detected, you'll be prompted before overwriting.
+
+```bash
+avsb push           # push with conflict check
+avsb push --force   # skip conflict check
+```
+
+After a successful push, if the experiment is running, you'll be offered the option to publish changes immediately.
+
+### Pull
+
+Fetches the latest experiment data and updates your local files.
+
+If you have local edits that would be overwritten, you'll be prompted before proceeding.
+
+```bash
+avsb pull           # pull with local change check
+avsb pull --force   # skip local change check
+```
+
+### Dev
+
+Starts a WebSocket dev server that watches your local files for changes and hot-reloads them in the browser via the A vs B Chrome extension.
+
+```bash
+avsb dev
+```
+
+### Status
+
+Shows the current experiment's metadata: name, ID, status, variations, languages, last sync time, and platform URL.
+
+```bash
+avsb status
+```
+
+## Project script workflow
+
+Project scripts run on every page where your snippet is active, independent of any experiment.
+
+### Pull
+
+Fetches the project script and scaffolds a local directory. Supports both JavaScript and TypeScript projects.
+
+```bash
+avsb project pull PRJ-10     # by project ID
+avsb project pull 10         # by numeric ID
+```
+
+The CLI creates a `project-<id>/` directory containing:
+
+```
+project-10/
+  project.ts              # or project.js (based on project language)
+  .avsb-project.json      # manifest (project metadata, do not delete)
+  tsconfig.json            # TypeScript config (TS projects only)
+  avsb.d.ts                # type definitions for avsb APIs (TS projects only)
+```
+
+Re-running `project pull` in an existing directory updates the local file from the platform.
+
+### Push
+
+Compiles (if TypeScript) and pushes the project script to the platform. The script is pushed to the correct field based on the project's language setting -- JavaScript code goes to `projectJs`, TypeScript code goes to `projectTs`.
+
+```bash
+avsb project push           # push with conflict check
+avsb project push --force   # skip conflict check
+```
+
+### Dev
+
+Watches the project script for changes and hot-reloads via the browser extension.
+
+```bash
+avsb project dev
+```
+
+## Experiment project structure
+
+After cloning an experiment, your directory looks like this:
+
+```
+exp-42/
+  .avsb.manifest.json      # manifest (experiment metadata, do not delete)
+  trigger.ts                # trigger code (when to activate the experiment)
+  control/
+    control.ts              # control variation script
+    control.scss            # control variation styles
+  my-variant/
+    my-variant.ts           # variant script
+    my-variant.scss         # variant styles
+```
+
+File extensions depend on the experiment's script/style language setting (`.js`/`.ts`, `.css`/`.scss`).
+
+## Uninstall
+
+```bash
+npm uninstall -g @avsbhq/cli
+```
+
+## Requirements
+
+- Node.js >= 18

package/bin/avsb.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'