websim-cli

CLI tool for working with Websim projects — clone a project locally, edit it in your own editor, and sync changes back.

Installation

npm install -g websim-cli

Quick Start

1. Log in (opens your browser to authenticate):

websim-cli login

2. Clone a project into a new directory:

websim-cli clone <project-id>

3. Edit the files locally with your editor of choice, then sync them back:

cd <project-name>
websim-cli sync

That's it. The project ID is saved on clone (see Project Configuration), so sync/pull/push don't need it again when run from the project directory.

Commands

Run websim-cli <command> --help for full options on any command.

Auth

• websim-cli login — browser-based login. The token is stored in ~/.websim-cli.json.

Projects

clone, pull, push, sync, and promote are available both at the top level and under websim-cli projects.

• clone <project-id> [version] — clone a project into a new directory named after it.
• pull [project-id] [version] — download files from a project revision into the current directory.
• sync [project-id] [parent-version] — upload the current directory as a new finalized revision and promote it to current. Use --no-promote to sync without going live, then promote later.
• push [project-id] [version] — update an existing revision in place (no new revision).
• promote [project-id] [version] — make a revision the current (live) one.
• create — create a new project with an initial draft revision.
• list [user] / list-current — list projects for a user or the logged-in account.
• get [project-id] / get-lineage [project-id] — fetch project info, or walk its parent lineage.
• revisions [project-id] — list a project's revisions.

Only changed files are uploaded on sync — content hashes are tracked in .websim-manifest.json.

Sites

websim-cli sites <command>:

• create — create a new site.
• get <site-id> / get-lineage <site-id> — fetch a site, or walk its parent lineage.
• list [user] / list-current — list sites for a user or the logged-in account.

Experiments

websim-cli experiment <command> — run multi-arm A/B experiments across a project's revisions:

• start [project-id] — bucket visitors across the given revision versions.
• stop [project-id] — end the active experiment (visitors return to current).
• status [project-id] — show the active experiment, if any.
• stats [project-id] — per-arm playtime stats (visitors, avg/median playtime).

Local dev

• websim-cli dev — serve the current directory locally with a standalone Websim SDK, proxying AI / comments / identity to the real API. Run websim-cli dev --help for options.

Project Configuration

On clone, a .websim.json file is created in the project directory storing the project ID (and the base revision version), so subsequent commands don't need it specified. It's added to .gitignore automatically.