@webmate-studio/cli

Command-line tool for Webmate Studio component development and synchronisation.

npm install -g @webmate-studio/cli

Command overview

| Command | Purpose | |---|---| | wm init [dir] | Bootstrap a new component project | | wm generate [type] [name] | Scaffold a new component or island | | wm dev | Run the local preview server | | wm install | Install npm deps in the project and per-component package.jsons | | wm login / wm logout / wm whoami | CLI authentication | | wm components ls | Browse components in your org (or another, with --org) | | wm versions [component] | List published versions of a component | | wm status [dir] | Show local vs remote sync state of a component | | wm pull [dir] | Download a component version from the CMS | | wm push [dir] | Upload local changes as a new version | | wm clone --from <uuid>[@<ver>] | Duplicate a component into another (or the same) org |

Authentication

Most sync commands require a Webmate session. The CLI looks for credentials in this order:

1. WEBMATE_TOKEN environment variable (with optional WEBMATE_BASE_URL)
2. ~/.webmate/auth.json (created by wm login)
3. .webmate/config.json in the current workspace (with apiToken)

wm login itself resolves the target baseUrl in this order:

1. --base-url flag
2. WEBMATE_BASE_URL environment variable
3. baseUrl field in the nearest .webmate/config.json (workspace default)
4. The built-in default

A workspace-level .webmate/config.json with just { "baseUrl": "https://app.webmate-studio.com" } is enough to pin all subsequent wm login calls in that directory to the right environment.

Interactive login (recommended)

wm login

Opens your browser at the active Webmate instance, shows a verification code, and waits while you click Authorize. The resulting token is saved to ~/.webmate/auth.json with 0600 permissions.

wm login --base-url https://app.webmate-studio.io   # switch environment
wm login --force                                     # overwrite an existing session

Non-interactive (CI/CD)

export WEBMATE_TOKEN="wms_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
export WEBMATE_BASE_URL="https://app.webmate-studio.io"
wm push ./my-hero

Create tokens under Settings → API Tokens in the CMS.

The sync workflow

A typical component lifecycle:

# Start from an existing component
wm components ls                          # find the UUID you want
wm pull ./my-hero --id <uuid>             # download it
# … edit files …
wm status                                 # see what changed
wm push                                   # publish a new version

Or from scratch:

wm init my-components
cd my-components
wm generate my-hero                       # scaffolds component.json with a fresh UUID
wm dev                                    # iterate locally
wm push --force                           # first push needs --force (no baseVersion yet)

.webmate.json — local manifest

After wm pull, wm push, or wm clone the CLI writes a .webmate.json next to your component:

{
  "componentId": "f97e376c-f8bd-42e4-9b9a-c2d62d4dcc9a",
  "baseVersion": "cmn7b9r7p00014i013dk007hw",
  "version": "1.0.5",
  "pulledAt": "2026-05-20T18:31:46.791Z",
  "fileHashes": {
    "component.html": "c2689e…",
    "component.json": "088e8d…"
  }
}

The CLI uses baseVersion for optimistic locking on push and fileHashes for change detection. The Workbench desktop app shares the same file format.

Conflict handling

wm push checks the remote head before uploading. If the remote moved since your last pull, the push is refused:

[ERROR] Remote moved: your baseVersion is cmABC… but remote latest is cmDEF… (1.0.6).
  Run wm pull first, then push again.

Resolve by pulling, merging locally, and pushing again.

wm pull warns about uncommitted local changes and prompts before overwriting, unless --force is given.

Git snapshot

If the component directory is a git repo, wm pull and wm push automatically git add . && git commit a snapshot of the synced state. This is purely a local backup — nothing is pushed to a remote. Disable with --no-git.

Commands

wm login

wm login [--token <wms_...>] [--base-url <url>] [-f|--force]

Default flow opens the browser and waits for a verification click — no copy/paste needed. With --token it accepts a pre-generated token directly (useful when scripting or behind firewalls).

wm whoami

wm whoami [--local]

Shows the active token source, base URL, user, and organisation. --local skips the /api/auth/me round-trip.

wm components ls

wm components ls [--org <slug>] [--org-id <id>]
                 [--category <cat>] [--search <q>]

Lists components in your active org. With --org or --org-id you can browse another org you are a member of (gated server-side by UserOrganizationRole).

wm versions [component]

wm versions [<uuid> | <dir>] [--limit <n>]

Lists all published versions, newest first. The positional argument can be a UUID, a directory containing component.json or .webmate.json, or omitted to use the current directory.

wm status [component]

wm status [<dir>] [--offline]

Reports one of:

• in sync — local file hashes match the manifest and the manifest points at the remote head
• local changes — you have uncommitted edits
• behind remote — remote has moved past your baseVersion
• diverged — both local edits and a moved remote
• unlinked — no .webmate.json yet

--offline skips the network call and only reports the local diff.

wm pull [component]

wm pull [<dir>] [--id <uuid>] [--version <ver|cuid|latest>]
                 [--merge] [--force] [--no-git]

Downloads the source bundle of the requested version and rewrites .webmate.json. Defaults to latest. With --merge, local files not present in the remote bundle are kept; without it the directory is brought into a 1:1 match.

wm push [component]

wm push [<dir>] [-m|--message <msg>] [--force] [--no-git]

Uploads the current file tree as a new patch version. The server bumps SemVer automatically (e.g. 1.0.5 → 1.0.6). The CLI:

• runs a pre-flight GET /versions to detect a moved remote and refuses to upload on mismatch
• skips uploads when nothing changed since the last pull/push (override with --force)
• treats HTTP 409 as a late-conflict signal and HTTP 422 as a build failure

wm clone --from

wm clone --from <component-uuid>[@<version|cuid|latest>]
         [--target-org <slug>] [--target-org-id <id>]
         [--name <displayName>] [--category <category>]
         [--to <dir>] [--merge] [--force] [--no-git]

Duplicates an existing component into another (or the same) org. You must be a member of both the source and the target org. The server mints a fresh UUID, copies the source source.json into a patched file map (new id, optional new name), and creates the new component row without a published version yet. The CLI writes the files locally; the first real publish happens when you run wm push --force.

Where things live

• Token store: ~/.webmate/auth.json (chmod 0600)
• Workspace org config: <your-apps-root>/.webmate/config.json
• Per-component manifest: <component>/.webmate.json

Troubleshooting

Not logged in. → Run wm login, or check WEBMATE_TOKEN is set.

Remote moved: your baseVersion is … → Someone else (or the Workbench, or another machine) pushed a new version. Run wm pull to re-sync, resolve any conflicts, then wm push again.

Build failed (HTTP 422) → The build service rejected the artifact. Check the server logs in the CMS for details; common causes are island files that fail to bundle or invalid component.json.

Token rejected (HTTP 401) → The token has been revoked or expired. Run wm login --force to refresh it.

No .webmate.json found (wm push) → The directory has not been linked to a component yet. Either run wm pull --id <uuid> first, or push with --force to skip the safety check (useful right after wm generate or wm clone).