@mesh-tech/mesh-cli 0.18.2 → 0.19.0

package/README.md

@@ -5,12 +5,12 @@ platform for building and running financial-services applications.
 
 It is the one `@mesh-tech/*` package published to public npm, so a clean laptop
 can install it with **no registry auth at all**, and the CLI then bootstraps
-everything else: your platform login, your package-registry access, a new app,
-a full local stack, and the documentation.
+everything else: your package-registry access, a new app, a full local stack,
+the documentation — and, only when you deploy somewhere, your platform login.
 
 This page is the getting-started path. Every command below also answers
 `--help`, and the complete reference ships inside the docs you start in
-[step 6](#6-read-the-full-docs).
+[step 5](#5-read-the-full-docs).
 
 ---
 
@@ -20,13 +20,18 @@ This page is the getting-started path. Every command below also answers
 |---|---|
 | Node 22+ and `pnpm` (`corepack enable`) | Everything below |
 | Docker Desktop (or equivalent) | Only for `mesh start` / `mesh dev` |
-| A Mesh account | Issued by your Mesh contact; used by `mesh login` |
+| A Mesh account | Issued by your Mesh contact; used by `mesh registry login` |
 | `registry` access on that account | The grant that unlocks `@mesh-tech/*` packages and the docs |
 
 **You do not need an AWS account** to install packages, run an app locally, or
 read the docs. AWS credentials only come into play if you *deploy*
 (`mesh deploy`, `mesh stack`).
 
+**You do not need a platform context either.** Package-registry access is one
+global identity, separate from any deployed platform. `mesh login <tenant>.<env>`
+is only for people who deploy to (or operate) a platform — see
+[Deploying to a platform](#deploying-to-a-platform).
+
 ---
 
 ## 1. Install
@@ -40,40 +45,47 @@ mesh --version
 install fails with `E401`, see [Troubleshooting](#troubleshooting) — both are
 known, one-command fixes.
 
-## 2. Sign in
+## 2. Get registry access
 
 ```bash
-mesh login mesh.dev
+mesh registry login
+mesh registry status
 ```
 
-A browser opens; sign in with your Mesh identity. The session is cached under
-`~/.config/mesh/`. `mesh login --status` shows who you are; `mesh logout <context>`
-clears it.
+One command, one browser round-trip. `mesh registry login` knows which registry
+it is talking to; it signs you in with your Mesh identity (a browser opens —
+add `--device` on a headless box or over SSH), asks the platform's
+registry-auth broker for a package-read token, and writes the `@mesh-tech`
+scope + token into your `~/.npmrc`. No AWS credential is created on your
+machine, and the token is short-lived by design (12 hours) — re-run
+`mesh registry login` when it expires (your sign-in is kept; no second browser
+trip).
+
+**If your account does not hold the grant yet**, the command tells you so and
+prints the access-request URL the platform returned (or names the admin to
+ask). Contact your Mesh contact to have **registry access granted to your
+user**, then run `mesh registry login` again.
 
-`mesh login` finishes by refreshing your registry auth automatically, so in the
-happy path step 3 is already done.
+Everything after this point — installing `@mesh-tech/*` packages, scaffolding
+an app, and the local docs server — depends on this step. `mesh init` (next)
+runs it for you.
 
-## 3. Get registry access
+## 3. Set up your tenant
 
 ```bash
-mesh registry login mesh.dev
-mesh registry status
+mesh init
 ```
 
-`mesh registry login` asks the platform's registry-auth broker for a
-package-read token using the session from step 2, and writes the `@mesh-tech`
-scope + token into your `~/.npmrc`. No AWS credential is created on your
-machine, and the token is short-lived by design (12 hours) — re-run
-`mesh login mesh.dev` when it expires.
-
-**If your account does not hold the grant yet**, the command tells you so and
-**sends the access request** — it prints the request URL the platform returned.
-Contact your Mesh contact to have **registry access granted to your user**, then
-run `mesh registry login mesh.dev` again (a token minted before the grant does
-not carry it, so a fresh login is required).
+Run it in your `<tenant>-mesh-apps` clone (an empty one is fine). The wizard
+asks which tenant this repo belongs to and where it runs — *local only*
+(`mesh start` / `mesh dev`) or *a deployed Mesh platform* — then checks your
+registry access (signing you in if step 2 was skipped), bootstraps the repo
+layout, installs the agent skills, and prints a summary with the next command.
+Every answer has a flag, so a headless run is one line:
 
-Everything after this point — installing `@mesh-tech/*` packages, and the local
-docs server — depends on this step.
+```bash
+mesh init --tenant acme --local --yes         # no prompts; --json for a machine-readable summary
+```
 
 ## 4. Create an app
 
@@ -84,9 +96,13 @@ mesh create-app --tenant acme --name billing --primitives service,database,tempo
 Scaffolds a new tenant application. `--primitives` selects what the app gets
 (`service`, `database`, `temporal`, `bucket`; default `service`). Run
 `mesh create-app --help` for the full option list, or omit the flags to be
-prompted.
+prompted. After `mesh init`, `--tenant` defaults to the tenant it recorded.
+
+`create-app` checks your registry access **before** it writes anything: with
+no usable token it stops and points at `mesh init` (add
+`--skip-registry-check` to scaffold offline anyway).
 
-## 5. Run it locally
+### Run it locally
 
 Two commands, in this order:
 
@@ -107,24 +123,7 @@ mesh dev            # from inside your app repo: run the app against it
 when its images are available — `--no-hub` skips it); `mesh dev` runs *your*
 app's processes against them.
 
-### Setting up a platform of your own
-
-Most app developers never need this — the platform is already running for you.
-If you are standing one up:
-
-```bash
-mesh init platform acme --domain example.com
-```
-
-scaffolds a tenant **platform** repo (the core + platform Pulumi layers on
-`@mesh-tech/infra-components`) that deploys with `mesh deploy` unmodified.
-
-For an existing app repo, `mesh init app-tenant` is the **doctor**, not a
-scaffolder: it checks auth, registry access, tenant registration, repo shape,
-and agent skills, and repairs what it can with `--fix`. Re-run it any time
-something looks wrong.
-
-## 6. Read the full docs
+## 5. Read the full docs
 
 The Mesh documentation is served **locally, by the CLI** — same access grant as
 the packages, no public site to keep in sync:
@@ -137,7 +136,7 @@ mesh docs stop
 `mesh docs start` runs detached (in a tmux session named `mesh-docs`) and prints
 the URL once the server answers. Outside a `mesh-platform` checkout it fetches
 the published docs artifact from the role-gated registry, so it needs
-[step 3](#3-get-registry-access) to have succeeded. Useful flags:
+[step 2](#2-get-registry-access) to have succeeded. Useful flags:
 
 | Flag | Effect |
 |---|---|
@@ -151,6 +150,46 @@ that site.
 
 ---
 
+## Deploying to a platform
+
+Most app developers never need this section — the platform is already running
+for you, and everything above works without it.
+
+If your tenant has a **deployed** Mesh platform (a `<tenant>.<env>` context
+such as `acme.dev`), sign in to it:
+
+```bash
+mesh login acme.dev            # browser; --device over SSH
+mesh login acme.dev --status   # who you are there
+mesh logout acme.dev
+```
+
+That session is what `mesh deploy`, `mesh stack`, the Hub, and the VPN use. It
+has nothing to do with package access — a platform login never touches your
+`~/.npmrc` — which is why `mesh init` asks *where the tenant runs* and only
+signs you in to a platform on the "deployed" branch.
+
+Deploying also needs AWS credentials that can reach the tenant's account. If
+your deployer account can read the registry as well, `mesh registry login
+--profile <aws-profile>` refreshes the package token through that profile
+instead of the broker — that flag is for deployers only.
+
+### Setting up a platform of your own
+
+```bash
+mesh init platform acme --domain example.com
+```
+
+scaffolds a tenant **platform** repo (the core + platform Pulumi layers on
+`@mesh-tech/infra-components`) that deploys with `mesh deploy` unmodified.
+
+For an existing app repo, `mesh init app-tenant` is the **doctor**, not a
+scaffolder: it checks auth, registry access, tenant registration, repo shape,
+and agent skills, and repairs what it can with `--fix`. Re-run it any time
+something looks wrong.
+
+---
+
 ## Troubleshooting
 
 ### `npm i -g @mesh-tech/mesh-cli` fails with `E401`
@@ -165,7 +204,7 @@ npm i -g @mesh-tech/mesh-cli --@mesh-tech:registry=https://registry.npmjs.org
 ```
 
 `--registry=…` alone does **not** work: a scope mapping outranks it. Refreshing
-the token (`mesh registry login mesh.dev`) fixes it too.
+the token (`mesh registry login`) fixes it too.
 
 The release publishes the same version of `@mesh-tech/mesh-cli` to both
 registries in the same job, so the two copies are the same artifact — there is
@@ -201,17 +240,33 @@ everywhere else.
 ### `Your Mesh account (…) is not authorized to read @mesh-tech packages.`
 
 Your account and session are fine; you don't hold the registry grant yet. The
-message names the request URL — see [step 3](#3-get-registry-access).
+message names the request URL (or the admin to ask) — see
+[step 2](#2-get-registry-access). Once granted, `mesh registry login` again;
+your sign-in is kept.
+
+### `No registry access on this machine — @mesh-tech packages cannot be installed.`
+
+`mesh create-app` checked before scaffolding and found no usable token. Run
+`mesh init` (or just `mesh registry login`), then re-run `create-app`.
+
+### `AWS profile '…' cannot read the Mesh registry`
+
+You passed `--profile` to `mesh registry login`. That flag skips the broker and
+uses the profile's AWS identity, which is only right for deployers whose AWS
+account is allowed to read the registry. To install packages you do not need
+AWS at all — drop the flag: `mesh registry login`.
 
-### `No valid Mesh session …`
+### `Registry broker unavailable (…)`
 
-Your session expired. Run `mesh login mesh.dev` again.
+The broker could not be reached, and the CLI fell back to the AWS credential
+chain, which this machine does not have. Retry in a minute:
+`mesh registry login`. If you deploy and have an AWS account:
+`mesh registry login --profile <aws-profile>`.
 
-### `No configuration found for "mesh.dev"`
+### `Could not resolve the Mesh package registry`
 
-Either you are offline, or the platform is not publishing its discovery document
-yet. Use the platform's full domain instead, e.g.
-`mesh login dev.platform.meshtech.io`.
+You are offline, or the platform's discovery document is unreachable. Retry
+once you are online: `mesh registry login`.
 
 ---