Local Development

Build and refine experiment variation code on your own machine, in your own IDE, with live preview in a real browser. Edit TypeScript and SCSS files, see changes instantly in Chrome, and push the finished code to the platform when you are ready.

Prerequisites

• Node.js 18+: required to run the CLI and compile TypeScript/SCSS.
• Personal access token: create one in Account Settings > Personal Access Tokens. See Personal Access Tokens.

Install the CLI

Install the CLI globally using npm:

npm install -g @avsbhq/cli

Verify by running avsb --version. Then authenticate:

$ avsb loginPaste your personal access token: ********Token verifiedLogged in to Acme Corp as jane@example.comToken saved in plain text at /Users/jane/.avsb/config.json (file mode 0600).

For scripts and CI, set AVSB_TOKEN instead of logging in. See CLI Authentication.

Install the Chrome extension

The Chrome extension connects to the CLI dev server and injects your local variation code into the real website. Install it from the Chrome Web Store. If the store listing is not available yet (it is currently under review), you can download the extension zip. Unzip it, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the unzipped folder.

After installing, click the puzzle-piece icon in the Chrome toolbar and pin the A vs B extension so it is always visible.

The workflow

The cloned experiment structure looks like this:

.├── .avsb.json           ← Manifest: experiment ID, variation IDs, languages├── trigger.ts           ← Page trigger logic. Editable, and uploaded by `avsb push`├── control/│   ├── control.ts       ← Control variation code│   └── control.scss     ← Control variation styles (usually empty)└── variant-a/    ├── variant-a.ts     ← Variant A code    └── variant-a.scss   ← Variant A styles

The clone, dev, and push commands run like this:

avsb clone 300015avsb devavsb push

The extension popup

Click the A vs B icon in the Chrome toolbar to open the popup. It shows:

• Connection status: only appears once you turn dev mode on for the current tab. Green once connected to your avsb dev server, grey while dev mode is on but no server has been found yet.
• Experiments on this page: every experiment the snippet found, including the one you are developing.
• Variation switcher: click any variation to switch to it immediately.
• Event log: a live feed of events tracked on the current page (exposures, conversions, revenue).

How live preview works

The extension receives compiled CSS and JS from the dev server and injects them into the page. It also sets a _avsb_dev cookie. While this cookie is present, the production snippet skips every experiment on the page, not only the one you are developing. The extension becomes the only thing changing the page while avsb dev runs. When you stop avsb dev, the extension clears the cookie right away, but the current page keeps showing no experiments until you reload it. The next page load has no cookie, so the production snippet resumes and runs every experiment as normal.

Conflict detection

If someone edits the variation code in the web editor while you are working locally, avsb push detects the conflict and warns you before overwriting. To pull the remote changes first:

avsb pull     # fetch latest from platform# manually merge any changesavsb push     # push your merged version

CLI command reference

This section covers the commands used while developing a variation locally. The full reference, including metrics, datasets, and codegen, is on the CLI Tool page.

avsb login

Saves a personal access token in ~/.avsb/config.json as plain text with file mode 0600. Pass --token <t> --no-input to skip the prompt, or set AVSB_TOKEN and skip logging in altogether. See CLI Authentication.

avsb logout

Deletes the saved logins. You will need to log in again. If AVSB_TOKEN is set in your shell, commands keep working until you unset it.

avsb whoami

Shows the account email, organization, role, API URL, and whether the token came from the config file or from AVSB_TOKEN. Pass --json to print the result as one JSON document. --quiet prints the result and nothing else: the answer still prints (for avsb whoami, one Email: … style line per field), while progress, headings and blank lines do not. Warnings and errors still go to stderr.

avsb org

Show, list, or switch your active organization.

avsb org                     # show the active org and where the token came fromavsb org list                # every org this token can reachavsb org switch              # pick one, interactivelyavsb org switch "Acme Corp"  # or name it: short ID, ID, or name

avsb org and avsb org list (but not avsb org switch) take the same --json and --quiet flags as avsb whoami.

avsb clone <experiment>

Download an experiment to a local directory. Accepts a short numeric ID, an EXP-123 ID, or the experiment's dashboard URL.

avsb clone 300015avsb clone EXP-300015avsb clone https://app.avsb.cloud/projects/123/experiments/300015

avsb dev

Start the file watcher and WebSocket server. It takes the first free port between 4400 and 4409 and prints it. Keep it running while you edit. Press Ctrl+C to stop.

avsb status

Show what the local manifest holds: experiment name, EXP- ID, status, variation count, script and style languages, when you last synced, and the platform URL. It does not contact the platform, so it does not report whether the platform copy has changed. avsb push checks that before uploading. Takes the same --json and --quiet flags as avsb whoami.

avsb pull

Fetch the latest code from the platform and overwrite local files. Pass -f, --force to skip the local-changes check and pull without being asked to confirm.

avsb push

Compile and upload local code. Compile errors are printed with file, line, and column, and nothing is uploaded until they are fixed. When the experiment is running or paused, the CLI asks whether to publish the change now or leave it pending for review. Pass --publish to publish without the question, or --no-publish to leave the change pending. Pass -f, --force to skip the remote-conflict check and push without being asked to confirm.

If the platform refuses the upload, each reason names the file in your folder and the field it was about:

✗ Request body failed validation  variant-a/variant-a.ts (variations.1.controlJs.source): Variation code must define an initVariation(options) function.

In a run that cannot ask questions (CI, a pipe, CI set), a remote conflict stops the push with exit code 4 and the two ways forward, and the change stays pending unless you pass --publish.