Weldr CLI Sync Guide

_Last updated: September 2025_

The Weldr CLI keeps your local workspace synced with the projects you build in the cloud. You can chat in the browser, preview in WebContainers, and code locally with the generated artifacts updating in real time.

---

1. Installation & Login

npm install -g @weldr/cli
weldr login

  • • weldr login opens a browser window for OAuth / magic link. Tokens are stored securely in your OS keychain.
  • • All subsequent commands reuse the session; run weldr logout to revoke.

    • ---

    2. Workspaces & Auto Sync

    The CLI maintains a home directory (default ~/weldr). Each project becomes a subfolder with a friendly slug. Within each project, individual chats are mirrored as nested workspaces:

    ~/weldr/
  ├─ crm-demo/
  │   ├─ contacts-app/
  │   │   ├─ app/
  │   │   ├─ drizzle/
  │   │   └─ codegen-manifest.json
  │   └─ marketing-dashboard/
  └─ task-manager/

    Quick start

    weldr start

  • • Downloads the IR, runs codegen into ~/weldr/projects/ by default.
  • • Re-runs generation whenever the IR changes (debounced) and prints a diff summary (added/updated/unchanged/conflict).
  • • Automatically runs pnpm install (if node_modules/ is missing) and starts pnpm dev unless you pass --no-dev.

    • Live output looks like:

    ▶ weldr watch 123e4567-e89b-12d3-a456-426614174000
Synced workspace -> /Users/you/weldr/projects/123e4567-e89b-12d3-a456-426614174000
  added: 12
  updated: 0
  unchanged: 0
Installing dependencies (pnpm install)…
Starting dev server (pnpm dev)…
Event stream closed. Reconnecting in 3s…
Synced workspace -> …
  updated: 3
  unchanged: 9

    Press Ctrl+C to stop watching. The CLI handles shutting down the dev server for you.

    Common options:

    | Option | Effect | |--------|--------| | --out

    | Override the output directory. | | --no-install | Skip pnpm install. Useful if you manage dependencies yourself. | | --no-dev | Generate files but do not start pnpm dev. |

    For a one-off export (no watcher), use:

    weldr sync <chat-id> [--out ./my-app]

    weldr sync runs generation once and exits.

    > Tip: weldr start --chat is an alias for weldr watch and will adopt smarter project selection in future releases.

    ---

    3. CLI Command Reference

    | Command | Description | |---------|-------------| | weldr login | Store an access token for future API calls. | | weldr logout | Remove local CLI credentials. | | weldr whoami | Show the active configuration (API base + token snippet). | | weldr sync | Generate code once for a chat. | | weldr watch | Continuous sync + dev server (auto-install and auto-reload). | | weldr start --chat | Alias for watch; future versions will offer chat selection. | | weldr fetch | Raw GET request for debugging (/api/dsl/, etc.). |

    Conflicts: Generated files contain // @generated begin markers. If you edit inside those blocks, the CLI writes .mosaic-conflict helpers and leaves the file untouched until you resolve them.

    ---

    4. Tokens & Security

  • • Tokens are scoped to your account and can be revoked from the Weldr web UI (“CLI access tokens”).
  • • Each local workspace stores token metadata in .weldr/config.json – do not commit this file to git.
  • • You can generate read-only tokens for CI workflows (e.g., automated codegen, linting).

    • IR delta API

    The CLI subscribes to a Server-Sent Events feed exposed at:

    GET /api/dsl/{chatId}/events?since=<epoch-ms>

    Events stream with event: dsl-event and include the IR change delta, messageId, confidence, and timestamp. Clients can reconnect using Last-Event-ID or the since query parameter.

    ---

    5. Database & Backend Access

    By default, generated code points at the Weldr cloud APIs and Postgres database. You don’t need to run a local DB to test your app.

    Optional (Pro/OSS): configure .env.local to use your own DB connection. The CLI provides helpers for applying IR-derived migrations locally:

    weldr migrate --chat <slug> --env .env.local

    ---

    6. WebContainer Preview Integration

  • • When you open the preview in the browser, you’ll see a “Connect CLI” button. It shows the project/chats slugs and the equivalent weldr start command.
  • • The CLI sends heartbeat events so the web UI can show “Synced locally” badges.
  • • You can run WebContainer and local dev server simultaneously; both read from the same IR.

    • ---

    7. Troubleshooting

    | Issue | Fix | |-------|-----| | CLI says “No chats found” | Make sure you’ve created a chat in the web app and you’re logged in with the same account. | | Conflicts keep reappearing | Move custom code outside @generated blocks or use weldr eject on files you want to own entirely. | | Dev server port in use | Run weldr dev --port 3001 or stop existing server. | | Slow install | Use weldr start --skip-install if dependencies are already installed. |

    For more help, run weldr --help or visit the End-to-End Tutorial.