@briancray/belte 0.8.0 → 0.9.0

package/bin/belte.ts

@@ -78,12 +78,12 @@ async function compileCmd(): Promise<void> {
     })
 }
 
-// Builds the standalone CLI binary — a thin remote client that talks to a
-// running server (manifest baked in, needs APP_URL at runtime). Discovery
-// walks the rpc registry to bake the manifest in. `--platforms a,b,c`
-// cross-compiles per target into dist/cli-thin/<platform>/ — the layout the
-// /__belte/cli download endpoint streams. For an embedded backend, use
-// `belte compile` (standalone server binary) instead.
+// Builds the standalone CLI binary — a thin remote client (manifest baked in)
+// that ships the compiled server beside it, so it can talk to a remote server
+// or spawn a local instance (`<name> start`). Discovery walks the rpc registry
+// to bake the manifest in. `--platforms a,b,c` cross-compiles per target into
+// dist/cli-thin/<platform>/ (cli + server) — the layout the /__belte/cli
+// download endpoint streams. For just the server, use `belte compile`.
 async function cliCmd(): Promise<void> {
     const targetFlag = parseFlag('target')
     const outFlag = parseFlag('out')
@@ -128,9 +128,10 @@ function usage(): never {
             '  belte compile [--target=<bun-...>] [--out=<path>]\n' +
             '                                       build a standalone server executable\n' +
             '  belte cli [--target=<bun-...>] [--out=<path>] [--platforms=<a,b,c>]\n' +
-            '                                       build the cli binary — a thin remote client\n' +
-            '                                       that talks to a running server (needs APP_URL;\n' +
-            '                                       --platforms cross-compiles per platform)\n' +
+            '                                       build the cli binary — a thin remote client that\n' +
+            '                                       ships the server beside it (connect to a remote\n' +
+            '                                       server or `start` a local instance; --platforms\n' +
+            '                                       cross-compiles per platform)\n' +
             '  belte bundle                         build a movable, self-contained app\n' +
             '                                       bundle for this platform (unsigned). Boots\n' +
             '                                       into a connect screen — start the embedded\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/buildCli.ts

@@ -1,3 +1,6 @@
+import { dirname, join } from 'node:path'
+import { build } from './build.ts'
+import { compile } from './compile.ts'
 import type { CompileTarget } from './lib/server/runtime/types/CompileTarget.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exeSuffix } from './lib/shared/exeSuffix.ts'
@@ -12,21 +15,21 @@ const DISCOVERY_ENTRY = new URL('./discoveryEntry.ts', import.meta.url).pathname
 const CLI_ENTRY = new URL('./cliEntry.ts', import.meta.url).pathname
 
 /*
-Two-pass CLI binary build. The CLI is always a thin remote client — it
-bakes in the per-rpc manifest and talks to a running server over HTTP
-(APP_URL at runtime); no handler code is bundled. For an embedded
-backend, `belte compile` produces the standalone server binary instead.
+CLI binary build. The CLI is a thin remote client — it bakes in the per-rpc
+manifest and talks to a running server over HTTP — but the **full** binary ships
+the compiled server beside it, so `/start` can spawn a local instance.
 
-  1. Discovery: build the discovery entry into a temporary JS bundle and
-     run it. It imports every rpc/socket module so defineVerb /
-     defineSocket populate the registries, then prints the CLI manifest
-     to stdout. The manifest is written to `dist/cli-manifest.json`.
-  2. Compile: build the CLI binary via `Bun.build({ compile })`. The
-     resolver plugin's `belte:cli-manifest` virtual reads the manifest
-     JSON written in step 1 and splices it into the bundle.
+  1. Client build (once): `build` produces the platform-independent `dist/_app`
+     the server binaries embed. It clears dist first, so it runs before everything.
+  2. Discovery: build the discovery entry into a temporary JS bundle and run it. It
+     imports every rpc/socket module so defineVerb / defineSocket populate the
+     registries, then prints the CLI manifest to stdout → `dist/cli-manifest.json`.
+  3. Per target: a server binary (`compile`, reusing the shared `dist/_app` via
+     `buildClient:false`) plus the CLI binary, written side by side. The resolver's
+     `belte:cli-manifest` virtual splices in the manifest from step 2.
 
-`platforms` cross-compiles per target into `dist/cli-thin/<platform>/`
-— the layout the /__belte/cli download endpoint serves.
+`platforms` cross-compiles per target into `dist/cli-thin/<platform>/` (the layout
+the /__belte/cli download endpoint serves): `<programName>` + `server` together.
 */
 export async function buildCli({
     cwd = process.cwd(),
@@ -40,17 +43,20 @@ export async function buildCli({
     platforms?: CompileTarget[]
 } = {}): Promise<string[]> {
     const distDir = `${cwd}/dist`
-    await Bun.$`mkdir -p ${distDir}`.quiet()
     const manifestPath = `${distDir}/cli-manifest.json`
     const discoveryOut = `${distDir}/_discovery.js`
 
     const svelteConfig = await loadSvelteConfig(cwd)
     const plugins = serverBuildPlugins({ cwd, svelteConfig })
 
+    // Step 1 — client build once (clears dist, writes _app). Every server binary
+    // embeds it, so it must precede discovery and the per-target compiles.
+    await build({ cwd, svelteConfig })
+
     /*
-    Step 1 — discovery. Build a runnable bundle, execute it under bun,
-    capture stdout. We don't `bun build --compile` here because the
-    discovery output is throwaway; a plain JS bundle runs faster.
+    Step 2 — discovery. Build a runnable bundle, execute it under bun, capture
+    stdout. We don't `bun build --compile` here because the discovery output is
+    throwaway; a plain JS bundle runs faster. Additive — does not clear dist.
     */
     const discoveryResult = await Bun.build({
         entrypoints: [DISCOVERY_ENTRY],
@@ -80,49 +86,41 @@ export async function buildCli({
     const entryCount = Object.keys(JSON.parse(stdout) as Record<string, unknown>).length
     log.info(`discovered ${entryCount} cli commands → ${manifestPath}`)
 
+    const programName = await readProgramName(cwd)
+
     /*
-    Step 2 — compile. The cliEntry imports the now-populated
-    belte:cli-manifest virtual; bun build --compile emits the standalone
-    binary. When `platforms` is set, loops once per target and writes
-    binaries into `dist/cli-thin/<platform>/<programName>` — the layout
-    the download route expects.
+    Step 3 — compile a CLI binary + sibling server binary for a single target,
+    written side by side so `resolveServerBinary()` finds the server next to the
+    running CLI. The server reuses the shared client build (buildClient:false).
     */
-    const programName = await readProgramName(cwd)
+    async function buildTargetPair(platformTarget: CompileTarget, cliOut: string): Promise<string> {
+        const serverOut = join(dirname(cliOut), `server${exeSuffix(platformTarget)}`)
+        await compile({ cwd, target: platformTarget, outfile: serverOut, buildClient: false })
+        const result = await Bun.build({
+            entrypoints: [CLI_ENTRY],
+            target: 'bun',
+            compile: { target: platformTarget, outfile: cliOut },
+            plugins,
+        })
+        exitOnBuildFailure(result)
+        log.success(`compiled cli + server: ${cliOut}`)
+        return cliOut
+    }
 
     if (platforms && platforms.length > 0) {
-        // Cross-compile every target in parallel — each build is independent.
+        // Cross-compile every target in parallel — each pair is independent.
         return Promise.all(
             platforms.map(async (platformTarget) => {
                 const shortName = platformTarget.replace(/^bun-/, '')
-                const suffix = exeSuffix(platformTarget)
-                const platformOut = `${distDir}/cli-thin/${shortName}/${programName}${suffix}`
+                const cliOut = `${distDir}/cli-thin/${shortName}/${programName}${exeSuffix(platformTarget)}`
                 await Bun.$`mkdir -p ${`${distDir}/cli-thin/${shortName}`}`.quiet()
-                const result = await Bun.build({
-                    entrypoints: [CLI_ENTRY],
-                    target: 'bun',
-                    compile: { target: platformTarget, outfile: platformOut },
-                    plugins,
-                })
-                exitOnBuildFailure(result)
-                log.success(`compiled thin cli binary: ${platformOut}`)
-                return platformOut
+                return buildTargetPair(platformTarget, cliOut)
             }),
         )
     }
 
-    const suffix = exeSuffix(target)
-    const outPath = outfile ?? `${distDir}/cli${suffix}`
-
-    const cliResult = await Bun.build({
-        entrypoints: [CLI_ENTRY],
-        target: 'bun',
-        compile: { target, outfile: outPath },
-        plugins,
-    })
-    exitOnBuildFailure(cliResult)
-
-    log.success(`compiled thin cli binary: ${outPath} (target: ${target})`)
-    return [outPath]
+    const cliOut = outfile ?? `${distDir}/cli${exeSuffix(target)}`
+    return [await buildTargetPair(target, cliOut)]
 }
 
 async function readProgramName(cwd: string): Promise<string> {

package/src/bundleApp.ts

@@ -61,15 +61,17 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     await compile({ cwd, target, outfile: `${binDir}/${serverBinaryFilename()}` })
 
     /*
-    Opt-in: ship the project's `.env.bundle` as the shipped `.env`, which the
+    Opt-in: ship the project's `bundle.env` as the shipped `.env`, which the
     server loads at boot (loadEnvFromBinaryDir) as its default config layer. A
     dedicated file, never the working `.env` — a compiled bundle is extractable,
     so only ship-safe defaults belong here; user-specific/secret values come from
-    the data-dir `.env` instead. bundleLayout places it under Contents/Resources
+    the data-dir `.env` instead. Named outside Bun's `.env.*` autoload family on
+    purpose: it's a build input, not a runtime overlay, so `bun dev`/`bun start`
+    never pick it up. bundleLayout places it under Contents/Resources
     in a macOS `.app` (sealed as a resource, so it survives codesign) and beside
     the binaries otherwise. Skipped when absent.
     */
-    const bundleEnv = Bun.file(`${cwd}/.env.bundle`)
+    const bundleEnv = Bun.file(`${cwd}/bundle.env`)
     if (await bundleEnv.exists()) {
         await Bun.$`mkdir -p ${dirname(envPath)}`.quiet()
         await Bun.write(envPath, bundleEnv)

package/src/compile.ts

@@ -21,13 +21,23 @@ export async function compile({
     cwd = process.cwd(),
     target = detectTarget(),
     outfile,
+    buildClient = true,
 }: {
     cwd?: string
     target?: CompileTarget
     outfile?: string
+    /*
+    Skip the client `build` (which clears dist). Set false when the caller already
+    built the platform-independent client once and is compiling several server
+    binaries against it — e.g. `belte cli` co-shipping a per-platform server beside
+    each CLI binary — so the shared `dist/_app` isn't wiped between targets.
+    */
+    buildClient?: boolean
 } = {}): Promise<string> {
     const svelteConfig = await loadSvelteConfig(cwd)
-    await build({ cwd, svelteConfig })
+    if (buildClient) {
+        await build({ cwd, svelteConfig })
+    }
 
     const outPath = outfile ?? `${cwd}/dist/app${exeSuffix(target)}`
 

package/src/controlServerWorker.ts

@@ -1,20 +1,20 @@
-import { mkdir, rm } from 'node:fs/promises'
+import { mkdir } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { bindConnectedFlag } from './lib/bundle/bindConnectedFlag.ts'
 import { bindRequestNavigate } from './lib/bundle/bindRequestNavigate.ts'
 import { listenLocalControlServer } from './lib/bundle/listenLocalControlServer.ts'
 import { probeBelteServer } from './lib/bundle/probeBelteServer.ts'
-import { resolveServerBinary } from './lib/bundle/resolveServerBinary.ts'
 import { resolveWebviewLib } from './lib/bundle/resolveWebviewLib.ts'
+import { spawnEmbeddedServer } from './lib/bundle/spawnEmbeddedServer.ts'
 import { stableLocalPort } from './lib/bundle/stableLocalPort.ts'
-import { waitForServer } from './lib/bundle/waitForServer.ts'
-import { findOpenPort } from './lib/server/runtime/findOpenPort.ts'
-import { parsePort } from './lib/server/runtime/parsePort.ts'
 import { appDataDir } from './lib/shared/appDataDir.ts'
 import { bundleLayout } from './lib/shared/bundleLayout.ts'
+import { clearLastConnection } from './lib/shared/clearLastConnection.ts'
 import { log } from './lib/shared/log.ts'
 import { readEnvFile } from './lib/shared/readEnvFile.ts'
+import { readLastConnection } from './lib/shared/readLastConnection.ts'
 import { serializeEnv } from './lib/shared/serializeEnv.ts'
+import { writeLastConnection } from './lib/shared/writeLastConnection.ts'
 
 /*
 The bundle's control server, run in a Worker so it owns its own thread.
@@ -158,57 +158,14 @@ function handleConnectionLost(url: string): void {
 }
 
 /*
-Spawns the sibling server binary on a free port and waits for it to answer,
-returning the URL to point the window at. Any previous child is reaped first so
-only one embedded server runs at a time.
+Boots the embedded server via the shared spawn helper and keeps the child so
+killServerChild can reap it. Any previous child is reaped first so only one
+embedded server runs at a time; returns the URL to point the window at.
 */
-/*
-The port the embedded server binds. A `PORT` configured in the data-dir `.env`
-(where the config form writes), the shipped binary-dir `.env`, or the launcher's
-own env is honored — so the server answers at a fixed, known address another
-machine can reliably connect to. With none set, the first open port at/above
-3000 is chosen (matching the standalone server's default). Precedence matches
-the server's own env stack: shell > data-dir > binary-dir. A configured port is
-used as-is and not second-guessed — if it's taken, the bind failure surfaces
-rather than silently moving.
-*/
-async function resolveEmbeddedPort(): Promise<number> {
-    const [dataDirEnv, binaryDirEnv] = await Promise.all([
-        readEnvFile(dataDirEnvPath()),
-        readEnvFile(binaryDirEnvPath()),
-    ])
-    return parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ?? findOpenPort(3000)
-}
-
 async function startEmbeddedServer(timeoutMs?: number): Promise<string> {
     killServerChild()
-    const port = await resolveEmbeddedPort()
-    const url = `http://localhost:${port}`
-    serverChild = Bun.spawn({
-        cmd: [resolveServerBinary()],
-        // BELTE_PARENT_PID lets the child exit if the launcher is force-quit
-        // (a clean window close reaps it directly; see exitWithParent). The
-        // server resolves its own config from its data-dir/binary-dir .env at
-        // boot (see serverEntry), so the launcher injects nothing else.
-        env: { ...process.env, PORT: String(port), BELTE_PARENT_PID: String(process.pid) },
-        stdio: ['inherit', 'inherit', 'inherit'],
-    })
-    /*
-    Race readiness against the child's exit. A misconfigured bundle (missing env
-    the server needs to bind) crashes immediately; without this the launcher
-    would wait out waitForServer's full timeout and report a generic stall
-    instead of the actual crash. The exit branch resolves (never rejects) so the
-    race loser still pending after a successful boot can't surface as an
-    unhandled rejection when the child is later reaped on disconnect.
-    */
-    const exited = serverChild.exited
-    const outcome = await Promise.race([
-        waitForServer(url, timeoutMs ? { timeoutMs } : undefined).then(() => undefined),
-        exited,
-    ])
-    if (outcome !== undefined) {
-        throw new Error(`[belte] embedded server exited (code ${outcome}) before binding`)
-    }
+    const { url, child } = await spawnEmbeddedServer({ programName, timeoutMs })
+    serverChild = child
     return url
 }
 
@@ -229,7 +186,7 @@ so a half-started server doesn't hold its port.
 */
 const AUTO_START_CEILING_MS = 3000
 async function resolveLaunchTarget(): Promise<string> {
-    const last = await readLastConnection()
+    const last = await readLastConnection(programName)
     if (!last) {
         return controlOrigin
     }
@@ -332,40 +289,6 @@ async function writeConfig(values: Record<string, string>): Promise<void> {
     await Bun.write(path, serializeEnv(merged))
 }
 
-/*
-The launcher-owned record of the last connection, in the data dir so it survives
-relaunch and is readable before the window opens — unlike the webview's
-localStorage, and unlike the embedded server's URL, which can't be persisted
-because it picks a fresh port each launch (so we record the intent, not the URL).
-resolveLaunchTarget reads it; /connect and /start write it; /disconnect clears it.
-*/
-type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }
-
-function lastConnectionPath(): string {
-    return join(appDataDir(programName), 'last-connection.json')
-}
-
-async function readLastConnection(): Promise<LastConnection | undefined> {
-    const file = Bun.file(lastConnectionPath())
-    if (!(await file.exists())) {
-        return undefined
-    }
-    try {
-        return (await file.json()) as LastConnection
-    } catch {
-        return undefined
-    }
-}
-
-async function writeLastConnection(value: LastConnection): Promise<void> {
-    await mkdir(appDataDir(programName), { recursive: true })
-    await Bun.write(lastConnectionPath(), JSON.stringify(value))
-}
-
-async function clearLastConnection(): Promise<void> {
-    await rm(lastConnectionPath(), { force: true })
-}
-
 // GET /__belte/config — the form's schema + current values, or null schema to skip the gate.
 async function handleConfigGet(): Promise<Response> {
     if (!configSchema) {
@@ -393,7 +316,7 @@ async function handleConnect(request: Request): Promise<Response> {
     flag?.setConnected(true)
     startLivenessWatch(target)
     // Record the choice so the next launch reconnects here before opening.
-    await writeLastConnection({ kind: 'url', url: target })
+    await writeLastConnection(programName, { kind: 'url', url: target })
     log.info(`connecting to ${identity.name} at ${target}`)
     return Response.json({ redirect: target })
 }
@@ -405,7 +328,7 @@ async function handleStart(): Promise<Response> {
         flag?.setConnected(true)
         startLivenessWatch(localUrl)
         // Record the choice so the next launch boots the embedded server first.
-        await writeLastConnection({ kind: 'embedded' })
+        await writeLastConnection(programName, { kind: 'embedded' })
         log.info(`started embedded server at ${localUrl}`)
         return Response.json({ redirect: localUrl })
     } catch (error) {
@@ -419,7 +342,7 @@ async function handleDisconnect(): Promise<Response> {
     stopLivenessWatch()
     killServerChild()
     flag?.setConnected(false)
-    await clearLastConnection()
+    await clearLastConnection(programName)
     return new Response(undefined, { status: 204 })
 }
 

package/src/lib/bundle/spawnEmbeddedServer.ts

@@ -0,0 +1,61 @@
+import { dirname, join } from 'node:path'
+import { findOpenPort } from '../server/runtime/findOpenPort.ts'
+import { parsePort } from '../server/runtime/parsePort.ts'
+import { appDataDir } from '../shared/appDataDir.ts'
+import { bundleLayout } from '../shared/bundleLayout.ts'
+import { readEnvFile } from '../shared/readEnvFile.ts'
+import { resolveServerBinary } from './resolveServerBinary.ts'
+import { waitForServer } from './waitForServer.ts'
+
+/*
+The port the embedded server binds. A `PORT` from the shell, the data-dir `.env`
+(where the config form writes), or the shipped binary-dir `.env` is honored — so
+the server answers at a fixed, known address another machine can reliably connect
+to. With none set, the first open port at/above 3000 is chosen (matching the
+standalone server's default). Precedence matches the server's own env stack:
+shell > data-dir > binary-dir. A configured port is used as-is — if it's taken,
+the bind failure surfaces rather than silently moving.
+*/
+async function resolveEmbeddedPort(programName: string): Promise<number> {
+    const [dataDirEnv, binaryDirEnv] = await Promise.all([
+        readEnvFile(join(appDataDir(programName), '.env')),
+        readEnvFile(bundleLayout(dirname(process.execPath)).envPath),
+    ])
+    return parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ?? findOpenPort(3000)
+}
+
+/*
+Spawns the sibling server binary on a free port and waits for it to answer,
+returning the live URL plus the child so the caller owns its lifetime (reaping on
+disconnect/exit). Readiness is raced against the child's exit so a server that
+crashes on boot (missing config) surfaces immediately instead of stalling out
+waitForServer's full timeout; the loser branch resolves (never rejects) so it
+can't surface as an unhandled rejection once the child is later reaped. Does not
+reap a previous child — the caller owns that.
+*/
+export async function spawnEmbeddedServer({
+    programName,
+    timeoutMs,
+}: {
+    programName: string
+    timeoutMs?: number
+}): Promise<{ url: string; child: ReturnType<typeof Bun.spawn> }> {
+    const port = await resolveEmbeddedPort(programName)
+    const url = `http://localhost:${port}`
+    const child = Bun.spawn({
+        cmd: [resolveServerBinary()],
+        // BELTE_PARENT_PID lets the child exit if the parent is force-quit (a clean
+        // shutdown reaps it directly). The server resolves its own config from its
+        // data-dir/binary-dir .env at boot, so nothing else is injected.
+        env: { ...process.env, PORT: String(port), BELTE_PARENT_PID: String(process.pid) },
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    const outcome = await Promise.race([
+        waitForServer(url, timeoutMs ? { timeoutMs } : undefined).then(() => undefined),
+        child.exited,
+    ])
+    if (outcome !== undefined) {
+        throw new Error(`[belte] embedded server exited (code ${outcome}) before binding`)
+    }
+    return { url, child }
+}

package/src/lib/cli/connectToServer.ts

@@ -0,0 +1,23 @@
+import { probeBelteServer } from '../bundle/probeBelteServer.ts'
+import { log } from '../shared/log.ts'
+import { writeLastConnection } from '../shared/writeLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Connects to a remote belte server: probes its identity endpoint first so we never
+record or talk to a non-belte URL, then persists the intent so the next bare run
+resumes here. Carries the env bearer token (baked or shell) for authed servers.
+Returns the target, or undefined when nothing belte answers.
+*/
+export async function connectToServer(
+    programName: string,
+    url: string,
+): Promise<CliTarget | undefined> {
+    const identity = await probeBelteServer(url)
+    if (!identity) {
+        log.warn(`no belte server responded at ${url}`)
+        return undefined
+    }
+    await writeLastConnection(programName, { kind: 'url', url })
+    return { url, token: process.env.APP_TOKEN, name: identity.name }
+}

package/src/lib/cli/dispatchCommand.ts

@@ -0,0 +1,71 @@
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { isStreamingResponse } from '../shared/isStreamingResponse.ts'
+import { responseErrorText } from '../shared/responseErrorText.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
+import { createClient } from './createClient.ts'
+import { parseArgvForRpc } from './parseArgvForRpc.ts'
+import { printValue } from './printValue.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Runs one RPC command against a target server and prints the result, returning a
+process exit code. Shared by the one-shot path (runCli) and the interactive
+session (runSession) so a command behaves identically typed at the shell or at
+the session prompt. Streaming responses (sse/jsonl — a streaming verb or a socket
+`tail`) print frame-by-frame as NDJSON; everything else decodes and prints once.
+*/
+export async function dispatchCommand({
+    programName,
+    manifest,
+    command,
+    argvTail,
+    url,
+    token,
+}: {
+    programName: string
+    manifest: CliManifest
+    command: string
+    argvTail: string[]
+    url: string
+    token?: string
+}): Promise<number> {
+    const entry = manifest[command]
+    if (!entry) {
+        console.error(
+            `${programName}: unknown command "${command}" — run \`${programName} --help\` for the list`,
+        )
+        return 1
+    }
+
+    let args: Record<string, unknown> | undefined
+    try {
+        args = await parseArgvForRpc(argvTail, entry.jsonSchema)
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+
+    const client = createClient({ url, token, manifest })
+    const fn = client[command]
+    if (!fn) {
+        console.error(`${programName}: command "${command}" not in client`)
+        return 1
+    }
+    try {
+        const response = await fn.raw(args)
+        if (isStreamingResponse(response)) {
+            for await (const frame of streamResponse(response)) {
+                printValue(frame, false)
+            }
+            return 0
+        }
+        if (!response.ok) {
+            throw new Error(await responseErrorText(response))
+        }
+        printValue(await decodeResponse(response), true)
+        return 0
+    } catch (error) {
+        console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)
+        return 1
+    }
+}

package/src/lib/cli/loadEnvFromBinaryDir.ts

@@ -7,7 +7,7 @@ Loads the bundle's shipped `.env` into `process.env`, resolved from the running
 binary's directory (`process.execPath`) via bundleLayout — beside the binary in
 the flat layout, under `Contents/Resources` in a macOS `.app`. This is the file the
 install tarball ships beside the executable — and, for a bundle, the one `bundleApp`
-copies from the project's `.env.bundle`. It carries the app's shipped defaults; the
+copies from the project's `bundle.env`. It carries the app's shipped defaults; the
 fill-when-unset merge (see loadEnvFile) lets per-shell exports, Bun's CWD
 `.env`, and the user's data-dir config all override it.
 */

package/src/lib/cli/printHelp.ts

@@ -1,3 +1,4 @@
+import { printTrimmed } from './printTrimmed.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 import type { CliManifestEntry } from './types/CliManifestEntry.ts'
 
@@ -37,7 +38,7 @@ export function printTopLevelHelp(
     footer = '',
 ): void {
     if (banner.trim()) {
-        console.log(banner.replace(/\n$/, ''))
+        printTrimmed(banner)
         console.log('')
     }
     const names = Object.keys(manifest).toSorted()
@@ -65,14 +66,19 @@ export function printTopLevelHelp(
             console.log(`  ${' '.repeat(20)} ${detail}`)
         }
     }
+    console.log(`\nconnection (\`/\` manages the connection, a bare word runs a command):`)
+    console.log(`  ${programName} /connect <url>   connect to a remote server`)
+    console.log(`  ${programName} /start           start a local instance`)
+    console.log(`  ${programName} /disconnect      forget the saved connection`)
+    console.log(`  ${programName}                  resume the saved connection (session)`)
     console.log(`\n  --help, -h           show this help`)
     console.log(`  <command> --help     show help for a specific command`)
     console.log(`\nenv:`)
-    console.log(`  APP_URL              remote server URL (required)`)
+    console.log(`  APP_URL              default server URL (baked at install; shell-overridable)`)
     console.log(`  APP_TOKEN            sent as Authorization: Bearer <value>`)
     if (footer.trim()) {
         console.log('')
-        console.log(footer.replace(/\n$/, ''))
+        printTrimmed(footer)
     }
 }
 

package/src/lib/cli/printSessionHelp.ts

@@ -0,0 +1,27 @@
+import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Session `/help`: with a command name, the per-command flag help; otherwise the
+meta-command list followed by the RPC command listing (no banner — already shown
+at session start).
+*/
+export function printSessionHelp(
+    programName: string,
+    manifest: CliManifest,
+    command?: string,
+): void {
+    if (command) {
+        printCommandHelp(programName, command, manifest)
+        return
+    }
+    console.log('session commands:')
+    console.log('  /connect <url>       connect to a remote server')
+    console.log('  /start               start a local instance')
+    console.log('  /disconnect          disconnect and forget the saved connection')
+    console.log('  /help [command]      show this help, or help for one command')
+    console.log('  /clear               clear the screen')
+    console.log('  /exit                leave the session')
+    console.log('')
+    printTopLevelHelp(programName, manifest)
+}

package/src/lib/cli/printSessionStatus.ts

@@ -0,0 +1,21 @@
+import { probeBelteServer } from '../bundle/probeBelteServer.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Prints the session's connection line. A local instance (spawned child) reads as
+"running a local instance"; a remote one reads as "connected to <name>", using the
+name the target already carries from its resolve-time probe and only re-probing
+when it doesn't. No target → the not-connected hint listing the verbs.
+*/
+export async function printSessionStatus(target: CliTarget | undefined): Promise<void> {
+    if (!target) {
+        console.log('(not connected — /connect <url> or /start)')
+        return
+    }
+    if (target.child) {
+        console.log(`running a local instance at ${target.url}`)
+        return
+    }
+    const name = target.name ?? (await probeBelteServer(target.url))?.name ?? target.url
+    console.log(`connected to ${name} at ${target.url}`)
+}