@mesh-tech/mesh-cli/README.md

CLI for Mesh platform development utilities

# @mesh-tech/mesh-cli

`mesh` is the command-line entry point to the **Mesh platform** — Trabian's
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 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 5](#5-read-the-full-docs).

---

## Requirements

| Need | Why |
|---|---|
| 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 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

```bash
npm i -g @mesh-tech/mesh-cli
mesh --version
```

`mesh --version` must print **0.12.0 or newer**. If it prints `0.1.x`, or the
install fails with `E401`, see [Troubleshooting](#troubleshooting) — both are
known, one-command fixes.

## 2. Get registry access

```bash
mesh registry login
mesh registry status
```

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 — it re-mints your sign-in so the
new role is in the token the broker sees. If it still says not authorized,
start a fresh sign-in: `mesh registry logout && mesh registry login`.

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. Set up your tenant

```bash
mesh init
```

Run it in your `<tenant>-mesh-apps` clone, or in a brand-new empty folder — the
wizard runs `git init` there for you. It 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:

```bash
mesh init --tenant acme --local --yes         # no prompts; --json for a machine-readable summary
```

## 4. Create an app

```bash
mesh create-app --tenant acme --name billing --primitives service,database,temporal
```

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. 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).

### Run it locally

Two commands, in this order:

```bash
mesh start          # the full-local Mesh platform — Docker only, no AWS, no VPN
mesh dev            # from inside your app repo: run the app against it
```

- `mesh status` — component health, endpoints, and ports.
- `mesh stop` — stop the local platform (`--destroy` also drops volumes).
- `mesh dev doctor` — diagnoses a dev session (credentials, tunnels, config,
  ports, Temporal) and names the fix.
- `mesh dev logs <service>` / `mesh dev restart <service>` — per-service control.
- `mesh dev --externals` — also realize the app's declared external services,
  mocked from their OpenAPI spec, run locally, or pointed at the real vendor.

`mesh start` brings up the platform's own services in Docker (the Hub included,
when its images are available — `--no-hub` skips it); `mesh dev` runs *your*
app's processes against them.

Where things are once it is up (printed at the end of `mesh start` and first
by `mesh status`):

- **Hub** — <http://localhost:9000>. Sign in as `dev@local.mesh` / `LocalDev1!`.
  The account is seeded; there is no need to register one.
- **Mailbox** — <http://localhost:8025>. Every email the local platform sends
  (sign-up confirmation, password reset) lands here; nothing leaves your machine.
- `mesh login local` logs the CLI in against the same local identity.

If `mesh start` stops on `already in use`, it names the container or process
holding the port; stop that (or move it) and run `mesh start` again.

## 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:

```bash
mesh docs start     # → http://localhost:4400
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 2](#2-get-registry-access) to have succeeded. Useful flags:

| Flag | Effect |
|---|---|
| `-p, --port <port>` | serve on another port (`0` picks a free one) |
| `-v, --version <version>` | pin a docs version (default: latest) |
| `--foreground` | serve in the foreground (automatic for agents/CI) |

`mesh docs list` shows the published versions. The full `mesh` CLI reference —
every command, every flag, generated from the binary itself — is a page inside
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`

This machine already points the `@mesh-tech` scope at the private registry with
an **expired** token, and npm maps registries per *scope*, never per package —
so it tried the private registry for a package that is published publicly.
Override the scope for this one command:

```bash
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`) 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
no fork to reconcile. Every *other* `@mesh-tech/*` package is private-registry
only, so keep the scope mapping for `pnpm install` in an app repo; only the CLI
bootstrap needs the override.

### The install works, but `mesh --version` prints `0.1.x`

You got an abandoned public package from February 2026 that predates the current
CLI — nothing after it will work. Reinstall:

```bash
npm rm -g @mesh-tech/mesh-cli
npm i -g @mesh-tech/mesh-cli
```

### `mesh: not inside a Mesh workspace (no node_modules/.bin/mesh found)`

An old launcher shim at `~/.local/bin/mesh` is shadowing the global CLI on your
`PATH`. The package is installed and fine — just unreachable.

```bash
which -a mesh          # the shim is listed above the npm global bin
rm ~/.local/bin/mesh   # if you don't develop the platform itself
```

If you *do* work in a `mesh-platform` checkout, run
`pnpm exec mesh install-shim --force` there instead — the current shim runs the
checkout's source inside a checkout and falls through to the global CLI
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 (or the admin to ask) — see
[step 2](#2-get-registry-access). Once granted, `mesh registry login` again —
it re-mints your sign-in so the new role reaches the broker (a role only rides
in tokens issued after it was granted). Still refused?
`mesh registry logout && mesh registry login` starts a fresh sign-in.

### `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`.

### `Registry broker unavailable (…)`

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>`.

### `Could not resolve the Mesh package registry`

You are offline, or the platform's discovery document is unreachable. Retry
once you are online: `mesh registry login`.

---

## Getting help

- `mesh --help`, and `--help` on any subcommand.
- `mesh docs start` — the full documentation, locally.
- Anything else: your Mesh contact.

## License

UNLICENSED — © Trabian. Access to the Mesh platform and its packages is granted
per account.