Command-line interface

The Build Me Web CLI scaffolds, previews, and deploys from your terminal or CI pipeline. This reference covers install, login, deploy commands, and CI patterns.

Install

npm install -g @buildmeweb/cli
bmw --version

Pin the CLI version in CI for reproducibility. Locally, keep reasonably current for new environment features. Node LTS is required; see the package README for the supported range.

Optional: install as a project devDependency and invoke via npx bmw so teammates share the same version.

Login

Run bmw login to authenticate via browser or device flow. In CI, prefer a short-lived token stored as a secret: bmw auth token --token $BMW_TOKEN (or the documented env var injection).

Confirm context with bmw whoami and bmw projects list. Switch projects explicitly in scripts so deploys never hit the wrong workspace.

• Do not commit tokens.
• Rotate CI tokens on a schedule.
• Use least-privilege tokens scoped to deploy only when possible.

Deploy

bmw preview          # deploy current branch to a preview URL
bmw deploy --prod    # promote after checks
bmw env pull         # sync env shape (secrets remain in vault)
bmw logs --follow    # stream recent runtime logs

bmw preview uploads the build or triggers a remote build depending on project settings. Capture the preview URL in CI annotations for reviewers. bmw deploy --prod should run only on protected branches after tests.

Configuration lives in bmw.toml — build command, output directory, and framework hints. Keep it committed; keep secrets out.

CI

Cache dependencies, run tests, then deploy on the main branch with required approvals. Never print secrets in logs. Example flow:

1. Install dependencies with the lockfile.
2. Run lint and unit tests.
3. Run bmw preview on pull requests.
4. On main, run bmw deploy --prod after approvals.

• CLI version pinned in CI
• Token stored as a masked secret
• Production deploy limited to main
• Preview URLs posted to the PR

Troubleshooting

Auth errors: token expired or wrong project context.

Build mismatch: local Node version differs from CI — align engines.

Silent fail in CI: ensure the CLI exits non-zero on deploy failure and that your pipeline checks exit codes.

Prerequisites & preparation

Before changing production settings for the CLI, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.

Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.

Pin CLI version in CI; prepare a least-privilege deploy token as a masked secret.

Detailed walkthrough

Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.

1. Install globally or as a devDependency for version alignment.
2. Login locally; configure token auth in CI.
3. Verify whoami and project context before deploys.
4. Run bmw preview on pull requests; post the URL.
5. Deploy production only from protected main after tests.

Edge cases & failure modes

Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.

• Wrong project context deploying to the unintended workspace.
• Local Node differing from CI causing build skew.
• Pipelines ignoring non-zero CLI exit codes.

QA checklist before you announce

• Happy path verified on mobile and desktop
• Failure path messaging reviewed
• Owners named for the first hour after launch
• Rollback or freeze path documented

Operating the change

After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.

Rotate CI tokens and review who can create them quarterly.

bmw.toml belongs in git; secrets never do.

Corporate proxies may require HTTPS_PROXY for login and deploy.

Preview annotations on PRs reduce “works on my machine” review cycles.

Exit codes must fail the pipeline — silent green is worse than noisy red.

Document the difference between preview and prod commands in the engineering handbook.

Prefer short-lived tokens over long-lived personal credentials in automation.

Implementation checklist

Confirm CLI version pinning in CI on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.

Document masked short-lived deploy tokens where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.

Operating it with your team

Rehearse explicit project context before deploy against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.

Measure preview URLs posted to pull requests with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.

When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.