@mercury-fw/cli 0.28.4 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @mercury-fw/cli
 
+## 0.29.0
+
+### Minor Changes
+
+- e498dad: `mfw` is meant to be installed globally (`bun add -g @mercury-fw/cli`) and used as a plain command. Inside an app, a global `mfw` at another version hands the command over to the app's own CLI, so the app's commands always match its framework. `mfw upgrade` installs the registry's latest globally, and `mfw create` run by a stale `mfw` says to. The CLI's messages, the generated app and the docs say `mfw` instead of `bunx mfw`.
+
+### Patch Changes
+
+- @mercury-fw/core@0.29.0
+
 ## 0.28.4
 
 ### Patch Changes

package/README.md

@@ -20,17 +20,21 @@
   - [`mfw credentials set <plugin> [--from <dir>] [--print]`](#mfw-credentials-set-plugin---from-dir---print)
   - [`mfw credentials reset <plugin>`](#mfw-credentials-reset-plugin)
   - [`mfw google-chat set-key <key-file> [--subscription <name>]`](#mfw-google-chat-set-key-key-file---subscription-name)
+  - [`mfw upgrade`](#mfw-upgrade)
 - [Help](#help)
 
 ## Getting it
 
-A new app comes from `bun create mercury-agent`, which is `mfw create` under the `create` convention:
+Install it once, globally, and `mfw` works from anywhere (Bun puts it in `~/.bun/bin`, which its installer adds to the `PATH`):
 
 ```bash
-bun create mercury-agent my-agent
+bun add -g @mercury-fw/cli
+mfw create my-agent
 ```
 
-The app it writes lists `@mercury-fw/cli` among its devDependencies, at the same version as the framework it depends on, so after `bun install` in the app every other command runs as `bunx mfw <command>`, with no global install.
+`mfw upgrade` keeps it current. Every app also lists `@mercury-fw/cli` among its devDependencies, at the framework's version, and inside an app the global `mfw` hands its commands over to that one when the two differ (it says so in one line; `mfw --version` and `mfw --help` stay the global one's), so an app's commands always match the framework it runs, whatever version is installed globally. An app not installed yet (no `bun install`) runs on the global one.
+
+Without a global install: `bun create mercury-agent my-agent` creates an app, and `bunx mfw <command>` runs the app's own CLI from inside it.
 
 ## Usage
 
@@ -54,8 +58,8 @@ It writes the `mercury.config.ts` for that selection, the persona, the service a
 | `-y`, `--yes` | No questions: the flags, and the defaults for the rest. |
 
 ```bash
-bun create mercury-agent my-agent
-bunx @mercury-fw/cli create my-agent --assistant-name Hermes --channels http --plugins jira --yes
+mfw create my-agent
+mfw create my-agent --assistant-name Hermes --channels http --plugins jira --yes
 ```
 
 The framework packages get the CLI's own version (they're released together); each chosen plugin or channel gets its latest version on the registry, `https://registry.npmjs.org` unless `MFW_REGISTRY` names another.
@@ -67,8 +71,8 @@ Before anything else it asks the registry for the latest `@mercury-fw/cli`: a ne
 Builds the app's image and starts the app and Qdrant in the background (`docker compose up -d --build`). Docker's cache means only what changed gets rebuilt, and a running container is recreated only if its image or configuration changed, so it's also the command to run after changing a dependency, the Dockerfile or `.env`. `--no-cache` rebuilds everything from scratch (`docker compose build --no-cache`, then `up -d`), which is what refetches a tool plugin's CLI binary when a new release is out: a normal build keeps the cached one.
 
 ```bash
-bunx mfw start
-bunx mfw start --no-cache
+mfw start
+mfw start --no-cache
 ```
 
 ### `mfw stop`
@@ -76,7 +80,7 @@ bunx mfw start --no-cache
 Stops the app and Qdrant and removes their containers (`docker compose down`). The volumes stay, so memory, the wiki and the CLI credentials are all there on the next start.
 
 ```bash
-bunx mfw stop
+mfw stop
 ```
 
 ### `mfw restart [--no-cache]`
@@ -84,8 +88,8 @@ bunx mfw stop
 Like `start`, but recreates the containers even when nothing changed (`--force-recreate`): a clean restart, for a process that got stuck. A changed `.env` doesn't need it, `start` already recreates what the change touches. `--no-cache` as in `start`.
 
 ```bash
-bunx mfw restart
-bunx mfw restart --no-cache
+mfw restart
+mfw restart --no-cache
 ```
 
 ### `mfw logs [service]`
@@ -93,8 +97,8 @@ bunx mfw restart --no-cache
 Follows the logs of every service, interleaved, or only of the one you name, `mercury` or `qdrant` (`docker compose logs -f`). One service at most. `Ctrl+C` stops following, the app keeps running.
 
 ```bash
-bunx mfw logs
-bunx mfw logs mercury
+mfw logs
+mfw logs mercury
 ```
 
 ### `mfw repl`
@@ -102,7 +106,7 @@ bunx mfw logs mercury
 Opens the dev REPL, a conversation with the assistant in the terminal, in a one-off container (`docker compose run --rm mercury bun run repl`). The REPL has no user identity by design, so what you try there never lands in anyone's memory; ending it (`Ctrl+D`) removes the one-off container and leaves a running app alone.
 
 ```bash
-bunx mfw repl
+mfw repl
 ```
 
 ### `mfw shell`
@@ -110,7 +114,7 @@ bunx mfw repl
 Opens a shell in the app's container: the running one if the app is up (`docker compose exec mercury bash`), a one-off one otherwise (`docker compose run --rm mercury bash`). The tool plugins' CLIs are on `PATH` there with their credentials, so it's where you check that a command works before blaming the model.
 
 ```bash
-bunx mfw shell
+mfw shell
 ```
 
 ### `mfw vault <command>`
@@ -126,10 +130,10 @@ Maintains the wiki vault, which lives on a Docker volume and not in the app's fo
 | `write-raw <path>` | Writes raw material for the nightly review to triage, the body read from stdin. |
 
 ```bash
-bunx mfw vault list
-bunx mfw vault read curated/standards/jira-fields.md
-bunx mfw vault grep "story points"
-cat note.md | bunx mfw vault write-curated curated/standards/new-note.md --author luca
+mfw vault list
+mfw vault read curated/standards/jira-fields.md
+mfw vault grep "story points"
+cat note.md | mfw vault write-curated curated/standards/new-note.md --author luca
 ```
 
 There's no command writing inferred notes on purpose: those are the agent's own, written only by its consolidation.
@@ -139,7 +143,7 @@ There's no command writing inferred notes on purpose: those are the agent's own,
 Lists the collections of the memory on Qdrant with how many points each holds, in a one-off container that reaches Qdrant the way the app does. Read-only.
 
 ```bash
-bunx mfw memory list
+mfw memory list
 ```
 
 ```
@@ -154,19 +158,19 @@ verbatim_archive  0 points
 Prints a collection's points, each as its id followed by one line per payload field. Newest first where the collection has a timestamp index (episodic memory and the verbatim archive do); in Qdrant's own order otherwise, and it says so. `--limit` defaults to 20. Read-only.
 
 ```bash
-bunx mfw memory read episodic_memory
-bunx mfw memory read semantic_facts --limit 5
+mfw memory read episodic_memory
+mfw memory read semantic_facts --limit 5
 ```
 
 ### `mfw reset <memory|wiki>`
 
 Deletes for good what the assistant remembers: `memory` is every collection on Qdrant, `wiki` the whole vault. It reads the volume's real name from the compose file, tells you which one is about to go, and asks you to type the app's name (the `name` in `package.json`); anything else, an empty answer, a `y` or closing the input included, deletes nothing and exits 1. Once confirmed it stops the service using the volume, removes its container and the volume, and starts the service again on an empty one (`docker compose stop`, `rm -f`, `docker volume rm`, `up -d`). After `memory`, a running app is restarted too (`docker compose restart mercury`), since it sets up its collections only when it starts.
 
-If a step fails once the service is stopped (the volume still in use by a one-off container, say), it stops there and says the service is down: `bunx mfw start` brings it back.
+If a step fails once the service is stopped (the volume still in use by a one-off container, say), it stops there and says the service is down: `mfw start` brings it back.
 
 ```bash
-bunx mfw reset memory
-bunx mfw reset wiki
+mfw reset memory
+mfw reset wiki
 ```
 
 Useful for clearing out test data; the other layer isn't touched.
@@ -178,9 +182,9 @@ Hands a tool plugin's CLI its login. Every such CLI keeps it in a config folder
 When the container starts, the app's `docker-entrypoint.sh` unpacks the variable onto the credentials volume, but only if that CLI's folder isn't there yet: what the CLI writes back while running, like a refreshed token, stays on the volume across redeploys, and an older value in `.env` never overwrites it. `<plugin>` has to be a tool plugin the app depends on.
 
 ```bash
-bunx mfw credentials set jira
-bunx mfw credentials set bitbucket --from ~/work/bitbucket-login
-bunx mfw credentials set jira --print
+mfw credentials set jira
+mfw credentials set bitbucket --from ~/work/bitbucket-login
+mfw credentials set jira --print
 ```
 
 ### `mfw credentials reset <plugin>`
@@ -188,18 +192,26 @@ bunx mfw credentials set jira --print
 Deletes the plugin's CLI folder from the credentials volume, so the variable in `.env` is unpacked again at the next start: what to run after correcting a variable whose folder is already on the volume, since the entrypoint never touches an existing folder. It asks you to type the plugin's name first, because a token the CLI refreshed on the volume goes too (and with a CLI that rotates its refresh token, the one in `.env` may no longer work). Once confirmed it stops the app, removes the folder in a one-off container of the app's own image, and starts the app again (`docker compose stop mercury`, `run --rm --no-deps -T mercury rm -rf …`, `up -d mercury`).
 
 ```bash
-bunx mfw credentials reset jira
+mfw credentials reset jira
 ```
 
 ### `mfw google-chat set-key <key-file> [--subscription <name>]`
 
 Writes the Google Chat channel's credentials into the app's `.env`, from the service account's JSON key (the file `gcloud iam service-accounts keys create` writes): `GOOGLE_CHAT_APP_CLIENT_EMAIL`, and `GOOGLE_CHAT_APP_PRIVATE_KEY` on one line with literal `\n`, the way the channel reads it. With `--subscription` (`projects/<project>/subscriptions/<name>`) it sets `GOOGLE_CHAT_PUBSUB_SUBSCRIPTION` too; without it, that line stays as it is, which is what you want when only the key changes. Older values and the empty lines `mfw create` leaves are replaced, the other lines stay alone, and the key is never printed.
 
-It checks everything before writing: the app has to depend on `@mercury-fw/channel-google-chat`, the file has to be a service account key and the subscription has to have that shape, otherwise it exits 1 saying why and `.env` stays as it was. Delete the key file afterwards; `bunx mfw start` applies the change to a running app. The whole setup of the Chat app is in the [channel's README](https://github.com/lucabro81/mercury-fw/tree/main/packages/channels/channel-google-chat#setting-up-the-chat-app).
+It checks everything before writing: the app has to depend on `@mercury-fw/channel-google-chat`, the file has to be a service account key and the subscription has to have that shape, otherwise it exits 1 saying why and `.env` stays as it was. Delete the key file afterwards; `mfw start` applies the change to a running app. The whole setup of the Chat app is in the [channel's README](https://github.com/lucabro81/mercury-fw/tree/main/packages/channels/channel-google-chat#setting-up-the-chat-app).
+
+```bash
+mfw google-chat set-key key.json --subscription projects/my-project/subscriptions/mercury-chat-sub
+mfw google-chat set-key new-key.json
+```
+
+### `mfw upgrade`
+
+Installs the registry's latest `mfw` globally (`bun add -g @mercury-fw/cli@<latest>`) when it's newer than the one running, and says it's already the latest otherwise; a registry that doesn't answer exits 1. It's about the global `mfw` only: an app's framework, its own CLI included, moves with `bun update` in the app. `mfw create` run by a stale global `mfw` creates the app with the latest one anyway, and says to run this.
 
 ```bash
-bunx mfw google-chat set-key key.json --subscription projects/my-project/subscriptions/mercury-chat-sub
-bunx mfw google-chat set-key new-key.json
+mfw upgrade
 ```
 
 ## Help

package/dist/src/main.d.ts

@@ -1,13 +1,16 @@
 import { type AppDeps } from "./app/commands.ts";
 /** Runs `argv` with stdio inherited and `env` on top of this process's
  * environment; returns its exit code. */
-export type Relaunch = (argv: string[], env: Record<string, string>) => Promise<number>;
+export type Relaunch = (argv: string[], env: Record<string, string>, opts?: {
+    quiet?: boolean;
+}) => Promise<number>;
 /** Runs `mfw` with `argv` (the arguments after the command name) and returns
  * the exit code, printing to stdout/stderr. `bin.ts` and `create-mercury-agent`
  * both call it; the app commands look for the app from `cwd` and run docker
  * through `deps`; `relaunch` is how `create` hands over to a newer CLI. */
-export declare function main(argv: string[], { cwd, deps, relaunch }?: {
+export declare function main(argv: string[], { cwd, deps, relaunch, globalInstall, }?: {
     cwd?: string;
     deps?: AppDeps;
     relaunch?: Relaunch;
+    globalInstall?: boolean;
 }): Promise<number>;

package/dist/src/program.d.ts

@@ -13,6 +13,8 @@ export type AppCommands = ReturnType<typeof appCommands>;
 export type ProgramHandlers = {
     /** `mfw create`; returns the exit code. */
     create: (args: CreateArgs) => Promise<number>;
+    /** `mfw upgrade`; returns the exit code. */
+    upgrade: () => Promise<number>;
     /** The app the app commands act on; throws outside one. */
     app: () => AppCommands;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.28.4",
+  "version": "0.29.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,13 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.28.4",
+    "@mercury-fw/core": "0.29.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
     "@mercury-fw/channel-google-chat": "0.1.2",
     "@mercury-fw/channel-http": "0.1.0",
-    "@mercury-fw/formatter": "0.28.4",
+    "@mercury-fw/formatter": "0.29.0",
     "@mercury-fw/plugin-atlassian-admin": "0.1.0",
     "@mercury-fw/plugin-bitbucket": "0.1.0",
     "@mercury-fw/plugin-jira": "0.1.1",

package/src/app/commands.ts

@@ -128,7 +128,7 @@ export function appCommands(app: App, deps: AppDeps) {
       setEnvVar(envFile, variable, value);
       deps.print(`${variable} set in ${envFile}, from ${source}.`);
       deps.print(
-        `The app unpacks it at its next start, if the volume has no ${folder} folder yet; if it has one, run bunx mfw credentials reset ${plugin} first.`,
+        `The app unpacks it at its next start, if the volume has no ${folder} folder yet; if it has one, run mfw credentials reset ${plugin} first.`,
       );
       return 0;
     },
@@ -171,7 +171,7 @@ export function appCommands(app: App, deps: AppDeps) {
           ? "GOOGLE_CHAT_APP_CLIENT_EMAIL and GOOGLE_CHAT_APP_PRIVATE_KEY"
           : "GOOGLE_CHAT_APP_CLIENT_EMAIL, GOOGLE_CHAT_APP_PRIVATE_KEY and GOOGLE_CHAT_PUBSUB_SUBSCRIPTION";
       deps.print(`${written} set in ${envFile}, from ${source}.`);
-      deps.print(`Delete ${source} now, the env file holds the key. bunx mfw start applies it to a running app.`);
+      deps.print(`Delete ${source} now, the env file holds the key. mfw start applies it to a running app.`);
       return 0;
     },
   };
@@ -184,7 +184,7 @@ export function appCommands(app: App, deps: AppDeps) {
     for (const [i, argv] of all.entries()) {
       const code = await deps.run(argv, { cwd: app.dir });
       if (code === 0) continue;
-      if (i > 0) deps.print(`The ${service} service was stopped and not restarted: bunx mfw start brings it back.`);
+      if (i > 0) deps.print(`The ${service} service was stopped and not restarted: mfw start brings it back.`);
       return code;
     }
     return 0;

package/src/main.ts

@@ -5,6 +5,7 @@
  * commands operate an existing app from inside its folder (see
  * `app/commands.ts`). The command line itself is declared in `program.ts`.
  */
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import type { CreateArgs } from "./args.ts";
 import { CATALOG } from "./catalog.ts";
@@ -13,7 +14,7 @@ import { runProgram } from "./program.ts";
 import { renderApp, selectionError } from "./render.ts";
 import { appVersions, cliVersion, newerCli, registryFrom } from "./versions.ts";
 import { appCommands, terminalDeps, type AppDeps } from "./app/commands.ts";
-import { findApp } from "./app/find-app.ts";
+import { findApp, type App } from "./app/find-app.ts";
 import { askAnswers, DEFAULT_ASSISTANT_NAME, DEFAULT_ROLE, type Answers } from "./wizard.ts";
 import { targetError, writeApp } from "./write.ts";
 
@@ -30,14 +31,30 @@ function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
 
 /** Runs `argv` with stdio inherited and `env` on top of this process's
  * environment; returns its exit code. */
-export type Relaunch = (argv: string[], env: Record<string, string>) => Promise<number>;
+export type Relaunch = (argv: string[], env: Record<string, string>, opts?: { quiet?: boolean }) => Promise<number>;
 
-/** The real relaunch: a child process on the user's terminal. */
-const spawnRelaunch: Relaunch = async (argv, env) => {
-  const proc = Bun.spawn(argv, { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: { ...process.env, ...env } });
-  return await proc.exited;
+/** The real relaunch: a child process on the user's terminal (its output
+ * dropped with `quiet`). While it runs, Ctrl+C is the child's to handle: this
+ * process ignores SIGINT, so it doesn't exit ahead of the child and lose its
+ * exit code. */
+const spawnRelaunch: Relaunch = async (argv, env, opts) => {
+  const output = opts?.quiet ? "ignore" : "inherit";
+  const proc = Bun.spawn(argv, { stdin: "inherit", stdout: output, stderr: output, env: { ...process.env, ...env } });
+  const ignore = () => {};
+  process.on("SIGINT", ignore);
+  try {
+    return await proc.exited;
+  } finally {
+    process.off("SIGINT", ignore);
+  }
 };
 
+/** Whether this CLI runs from Bun's global install (`bun add -g`), the one
+ * `mfw upgrade` updates, rather than from `bunx`'s cache or an app. */
+function isGlobalInstall(): boolean {
+  return /[\\/]install[\\/]global[\\/]node_modules[\\/]/.test(import.meta.dir);
+}
+
 /** When the registry has a newer `@mercury-fw/cli` than this one (a stale copy
  * out of Bun's bunx cache), installs it (`bunx … --version`), then runs
  * `create` again through it with the same arguments as typed and returns its
@@ -45,7 +62,7 @@ const spawnRelaunch: Relaunch = async (argv, env) => {
  * carry on here: no newer CLI, a check skipped inside a relaunch
  * (`MFW_SELF_UPDATED`), a registry that can't answer, or a newer CLI that
  * can't be installed; the last two with a warning. */
-async function relaunchIfStale(rawArgs: string[], relaunch: Relaunch): Promise<number | undefined> {
+async function relaunchIfStale(rawArgs: string[], relaunch: Relaunch, globalInstall: boolean): Promise<number | undefined> {
   if (process.env.MFW_SELF_UPDATED) return undefined;
   const registry = registryFrom(process.env.MFW_REGISTRY).replace(/\/+$/, "");
   let newer: string | undefined;
@@ -60,7 +77,7 @@ async function relaunchIfStale(rawArgs: string[], relaunch: Relaunch): Promise<n
   const env = { MFW_SELF_UPDATED: newer, NPM_CONFIG_REGISTRY: registry };
   let installed: number;
   try {
-    installed = await relaunch(["bunx", cli, "--version"], env);
+    installed = await relaunch(["bunx", cli, "--version"], env, { quiet: true });
   } catch {
     installed = -1;
   }
@@ -69,13 +86,14 @@ async function relaunchIfStale(rawArgs: string[], relaunch: Relaunch): Promise<n
     return undefined;
   }
   console.error(`mfw ${cliVersion()} is behind the registry's ${newer}: running ${newer} instead.`);
+  if (globalInstall) console.error("update your mfw: mfw upgrade");
   return relaunch(["bunx", cli, "create", ...rawArgs], env);
 }
 
 /** `mfw create`: returns the exit code. `rawArgs` are the arguments after
  * `create` as typed, for a relaunch. */
-async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch): Promise<number> {
-  const relaunched = await relaunchIfStale(rawArgs, relaunch);
+async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, globalInstall: boolean): Promise<number> {
+  const relaunched = await relaunchIfStale(rawArgs, relaunch, globalInstall);
   if (relaunched !== undefined) return relaunched;
   // The folder is created in kebab case, only its own name: the parent path is
   // taken as typed. Its name is also the app name's default.
@@ -106,21 +124,90 @@ Next:
   cd ${dir}
   bun install
   cp .env.example .env    # then fill it in
-  bunx mfw start`);
+  mfw start`);
   return 0;
 }
 
+/** `mfw upgrade`: installs the registry's latest `@mercury-fw/cli` globally
+ * when it's newer than this one; returns the install's exit code, 0 when
+ * there's nothing newer, 1 when the registry can't answer. */
+async function upgrade(relaunch: Relaunch): Promise<number> {
+  const registry = registryFrom(process.env.MFW_REGISTRY).replace(/\/+$/, "");
+  let newer: string | undefined;
+  try {
+    newer = await newerCli({ registry });
+  } catch (err) {
+    console.error(`couldn't check for a newer mfw: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  if (newer === undefined) {
+    console.log(`mfw ${cliVersion()} is the latest.`);
+    return 0;
+  }
+  const code = await relaunch(["bun", "add", "-g", `@mercury-fw/cli@${newer}`], { NPM_CONFIG_REGISTRY: registry });
+  if (code === 0) console.log(`mfw upgraded from ${cliVersion()} to ${newer}.`);
+  return code;
+}
+
+/** The commands that belong to the CLI itself, wherever it runs: never
+ * handed over to an app's CLI. */
+const OWN_COMMANDS = new Set(["create", "upgrade"]);
+
+/** Inside an app whose own CLI (its devDependency) is installed at another
+ * version than this one, as a global `mfw` can be, runs `argv` through that
+ * CLI and returns its exit code: the app's commands then always match the
+ * framework the app runs. `undefined` means run here: not an app command, not
+ * inside an app, the app not installed yet, the same version, or already
+ * handed over (`MFW_DEFERRED`). */
+async function handOverToAppCli(argv: string[], cwd: string, relaunch: Relaunch): Promise<number | undefined> {
+  const command = argv[0];
+  if (command === undefined || command.startsWith("-") || OWN_COMMANDS.has(command)) return undefined;
+  if (process.env.MFW_DEFERRED) return undefined;
+  let app: App;
+  try {
+    app = findApp(cwd);
+  } catch {
+    return undefined;
+  }
+  const local = join(app.dir, "node_modules", "@mercury-fw", "cli");
+  const manifest = join(local, "package.json");
+  if (!existsSync(manifest)) return undefined;
+  let version: unknown;
+  try {
+    version = (JSON.parse(readFileSync(manifest, "utf-8")) as { version?: unknown } | null)?.version;
+  } catch (err) {
+    console.error(`couldn't read the app's mfw (${manifest}): ${err instanceof Error ? err.message : String(err)}; running mfw ${cliVersion()}`);
+    return undefined;
+  }
+  if (typeof version !== "string" || version === cliVersion()) return undefined;
+  console.error(`mfw ${cliVersion()}: running the app's ${version}`);
+  try {
+    return await relaunch(["bun", join(local, "src", "bin.ts"), ...argv], { MFW_DEFERRED: "1" });
+  } catch (err) {
+    console.error(`couldn't run the app's mfw: ${err instanceof Error ? err.message : String(err)}; running mfw ${cliVersion()}`);
+    return undefined;
+  }
+}
+
 /** Runs `mfw` with `argv` (the arguments after the command name) and returns
  * the exit code, printing to stdout/stderr. `bin.ts` and `create-mercury-agent`
  * both call it; the app commands look for the app from `cwd` and run docker
  * through `deps`; `relaunch` is how `create` hands over to a newer CLI. */
 export async function main(
   argv: string[],
-  { cwd = process.cwd(), deps, relaunch = spawnRelaunch }: { cwd?: string; deps?: AppDeps; relaunch?: Relaunch } = {},
+  {
+    cwd = process.cwd(),
+    deps,
+    relaunch = spawnRelaunch,
+    globalInstall = isGlobalInstall(),
+  }: { cwd?: string; deps?: AppDeps; relaunch?: Relaunch; globalInstall?: boolean } = {},
 ): Promise<number> {
+  const handedOver = await handOverToAppCli(argv, cwd, relaunch);
+  if (handedOver !== undefined) return handedOver;
   const rawCreateArgs = argv.slice(argv.indexOf("create") + 1);
   return runProgram(argv, {
-    create: (args) => create(args, rawCreateArgs, relaunch),
+    create: (args) => create(args, rawCreateArgs, relaunch, globalInstall),
+    upgrade: () => upgrade(relaunch),
     app: () => appCommands(findApp(cwd), deps ?? terminalDeps()),
   });
 }

package/src/program.ts

@@ -18,6 +18,8 @@ export type AppCommands = ReturnType<typeof appCommands>;
 export type ProgramHandlers = {
   /** `mfw create`; returns the exit code. */
   create: (args: CreateArgs) => Promise<number>;
+  /** `mfw upgrade`; returns the exit code. */
+  upgrade: () => Promise<number>;
   /** The app the app commands act on; throws outside one. */
   app: () => AppCommands;
 };
@@ -74,6 +76,16 @@ Examples:
       result.code = await handlers.create(toCreateArgs(folder, opts));
     });
 
+  program
+    .command("upgrade")
+    .summary("updates the global mfw")
+    .description(
+      "Installs the registry's latest mfw globally (bun add -g @mercury-fw/cli@<latest>), when it's newer than this one. An app's own framework, its CLI included, is upgraded with bun update in the app.",
+    )
+    .action(async () => {
+      result.code = await handlers.upgrade();
+    });
+
   // commander reads --no-cache as "cache: false"; the commands take noCache.
   const cacheOff = (opts: { cache: boolean }) => ({ noCache: !opts.cache });
 

package/src/render.ts

@@ -113,10 +113,10 @@ function renderEntrypoint(tools: Array<CatalogEntry & { credentials: CliCredenti
   return `#!/usr/bin/env bash
 # Starts the service, first materializing each tool plugin's CLI credentials
 # onto the cli-credentials volume: its variable in the env file is the CLI's
-# config folder as a base64 tar.gz (bunx mfw credentials set <plugin> writes
+# config folder as a base64 tar.gz (mfw credentials set <plugin> writes
 # it). Only when that CLI's folder isn't on the volume yet: what a CLI writes
 # back while running, like a refreshed token, stays there across redeploys,
-# and an older value in the env file never overwrites it. bunx mfw credentials
+# and an older value in the env file never overwrites it. mfw credentials
 # reset <plugin> clears one folder so its variable is materialized again.
 set -euo pipefail
 
@@ -275,8 +275,8 @@ function renderPackageJson(
     private: true,
     scripts: { start: "bun src/index.ts", repl: "bun src/repl.ts", typecheck: "tsc --noEmit" },
     dependencies,
-    // The CLI in the app itself, so `bunx mfw` runs the version that matches
-    // the framework the app depends on.
+    // The CLI in the app itself, at the framework's version: a global `mfw`
+    // hands the app's commands over to it.
     devDependencies: { "@mercury-fw/cli": `^${cli}`, "@types/bun": "^1.4.2", typescript: "^6.0.3" },
   };
   const trusted = [...new Set([...tools.map((t) => t.package), ...[...channels, ...tools].flatMap((e) => e.trusts ?? [])])];
@@ -307,7 +307,7 @@ function renderEnv(channels: CatalogEntry[], tools: CatalogEntry[]): string {
     if (entry.credentials !== undefined) {
       vars.push({
         name: entry.credentials.variable,
-        comment: `${entry.credentials.folder}'s config folder, packed: bunx mfw credentials set ${entry.id} writes it; materialized on the credentials volume at the first start without that folder`,
+        comment: `${entry.credentials.folder}'s config folder, packed: mfw credentials set ${entry.id} writes it; materialized on the credentials volume at the first start without that folder`,
       });
     }
     if (vars.length > 0) {
@@ -388,14 +388,22 @@ A Mercury app, scaffolded by \`mfw create\`.
 
 ## Running it
 
+\`mfw\` is Mercury's command-line tool. Install it once, globally (\`mfw upgrade\` keeps it current), or put \`bunx\` in front of every command instead (\`bunx mfw start\`):
+
+\`\`\`bash
+bun add -g @mercury-fw/cli
+\`\`\`
+
+Then, in the app:
+
 \`\`\`bash
 bun install
 cp .env.example .env
-bunx mfw start
-bunx mfw repl
+mfw start
+mfw repl
 \`\`\`
 
-\`bun install\` here gives your editor, \`bun run typecheck\` and \`mfw\` the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`bunx mfw start\` builds the image and starts the app with Qdrant in the background, \`bunx mfw repl\` opens a terminal conversation with the assistant. \`bunx mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
+\`bun install\` here gives your editor, \`bun run typecheck\` and the app's own \`mfw\` (the one a global \`mfw\` runs inside the app) the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`mfw start\` builds the image and starts the app with Qdrant in the background, \`mfw repl\` opens a terminal conversation with the assistant. \`mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
 ${renderHttpSection(channels)}${renderCredentialsSection(withCredentials(tools))}`;
 }
 
@@ -422,7 +430,7 @@ function renderCredentialsSection(tools: Array<CatalogEntry & { credentials: Cli
 Each tool plugin runs its own CLI, and each CLI keeps its login in a folder of its own: ${list}. Log in with the CLI on your machine first (its own README says how), then hand that folder to the app:
 
 \`\`\`bash
-bunx mfw credentials set ${first.id}
+mfw credentials set ${first.id}
 \`\`\`
 
 It packs the folder into its variable in \`.env\` (\`--from <folder>\` if it isn't where the CLI usually keeps it, \`--print\` to get the line to paste on another host instead). When the container starts, \`docker-entrypoint.sh\` unpacks it onto the \`cli-credentials\` volume, but only if that CLI's folder isn't there yet: what the CLI writes back afterwards, like a refreshed token, stays on the volume across redeploys, and the older value in \`.env\` never overwrites it.
@@ -430,7 +438,7 @@ It packs the folder into its variable in \`.env\` (\`--from <folder>\` if it isn
 That same rule means a corrected variable does nothing while the old folder is on the volume. Clear it, and the next start unpacks the variable again:
 
 \`\`\`bash
-bunx mfw credentials reset ${first.id}
+mfw credentials reset ${first.id}
 \`\`\`
 `;
 }