@pellux/goodvibes-agent 0.1.91 → 0.1.93

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to GoodVibes Agent will be recorded here.
 
+## 0.1.93 - 2026-06-01
+
+- 7f802e5 Add external runtime URL override
+
+## 0.1.92 - 2026-06-01
+
+- f52b62e Fix copied CLI executable guidance
+
 ## 0.1.91 - 2026-06-01
 
 - efbb82a Expand Agent Knowledge CLI management

package/README.md

@@ -89,6 +89,8 @@ Starting a routine records local usage and prints its steps; it does not spawn b
 
 Start or restart the GoodVibes runtime from GoodVibes TUI or the owning host before launching Agent. Agent status and companion/knowledge routes connect to that external runtime, normally on `http://127.0.0.1:3421`.
 
+Use `--runtime-url http://host:port` for a one-off launch, or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` when the runtime API is not on the default local port. The legacy `GOODVIBES_AGENT_BASE_URL` env var is also accepted as an alias. These only change the external runtime connection target; Agent still does not host or start the runtime.
+
 Agent reports unavailable, unauthenticated, or incompatible runtime state through `goodvibes-agent status`, `goodvibes-agent doctor`, and the TUI status views. It does not provide runtime hosting commands.
 
 ## Product Boundary

package/docs/README.md

@@ -17,6 +17,7 @@ Important baseline constraints:
 - Agent does not start, stop, restart, install, uninstall, or own runtime hosting.
 - Agent Knowledge/Wiki uses only `/api/goodvibes-agent/knowledge/*`; there is no default Knowledge/Wiki or non-Agent product fallback.
 - Agent supports isolated runtime homes with `GOODVIBES_AGENT_HOME=<path>` and named profile homes with `goodvibes-agent profiles create <name> --template <starter> --yes` plus `--agent-profile <name>`.
+- Agent supports external runtime URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these do not make Agent own runtime hosting.
 - Agent ships starter profile templates for household, research, travel, operations, and personal productivity local state; `profiles templates export/import` and `/agent-profile guide` support local custom starters.
 - Local personas, routines, and Agent skills are stored under the Agent home and are injected only into the serial Agent conversation.
 - Normal assistant chat is not coding-session delegation.

package/docs/getting-started.md

@@ -97,6 +97,8 @@ Start the runtime from GoodVibes TUI or the owning host before using runtime-bac
 - `/api/goodvibes-agent/knowledge/search`
 - `/api/goodvibes-agent/knowledge/ingest/url`
 
+If the runtime API is not on `http://127.0.0.1:3421`, use `goodvibes-agent --runtime-url http://host:port status` for a one-off check or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` before launching the TUI.
+
 Agent Knowledge/Wiki is an Agent-owned product segment. Agent commands must not fall back to default Knowledge/Wiki or other product-specific knowledge spaces.
 
 Runtime-hosting commands are not part of GoodVibes Agent. Use `goodvibes-agent status`, `goodvibes-agent doctor`, and the Agent TUI status views for diagnostics.

package/docs/runtime-connection.md

@@ -24,6 +24,20 @@ http://127.0.0.1:3421
 /api/goodvibes-agent/knowledge/search
 ```
 
+If the runtime API is on a different host or port, use a one-off override:
+
+```sh
+goodvibes-agent --runtime-url http://127.0.0.1:3421 status
+```
+
+For a persistent shell/session override, set:
+
+```sh
+export GOODVIBES_AGENT_RUNTIME_URL=http://127.0.0.1:3421
+```
+
+`GOODVIBES_AGENT_BASE_URL` is accepted as a legacy alias. These values only select the external runtime API root; they do not enable runtime hosting inside Agent.
+
 If the runtime is unavailable, unauthenticated, or on an incompatible SDK version, Agent commands report actionable diagnostics without printing token values.
 
 ## Product Boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",

package/src/cli/bundle-command.ts

@@ -125,7 +125,7 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
 
   if (sub === 'inspect') {
     const path = rest[0];
-    if (!path) return { output: 'Usage: goodvibes bundle inspect <path>', exitCode: 2 };
+    if (!path) return { output: `Usage: ${runtime.cli.binary} bundle inspect <path>`, exitCode: 2 };
     const sourcePath = shellPaths.resolveWorkspacePath(path);
     const parsed = readJsonFile(sourcePath);
     if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
@@ -199,7 +199,7 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
 
   if (sub === 'import') {
     const path = rest[0];
-    if (!path) return { output: 'Usage: goodvibes bundle import <path>', exitCode: 2 };
+    if (!path) return { output: `Usage: ${runtime.cli.binary} bundle import <path>`, exitCode: 2 };
     const sourcePath = shellPaths.resolveWorkspacePath(path);
     const parsed = readJsonFile(sourcePath);
     if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
@@ -223,5 +223,5 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
     };
   }
 
-  return { output: 'Usage: goodvibes bundle export [path]|inspect <path>|import <path>', exitCode: 2 };
+  return { output: `Usage: ${runtime.cli.binary} bundle export [path]|inspect <path>|import <path>`, exitCode: 2 };
 }

package/src/cli/completion.ts

@@ -19,12 +19,9 @@ const COMMANDS = [
   'subscription',
   'secrets',
   'sessions',
-  'tasks',
   'pair',
   'qrcode',
   'bundle',
-  'remote',
-  'bridge',
   'completion',
   'version',
   'help',
@@ -36,6 +33,7 @@ const OPTIONS = [
   '--model',
   '--provider',
   '--agent-profile',
+  '--runtime-url',
   '--cd',
   '--working-dir',
   '--config',

package/src/cli/config-overrides.ts

@@ -21,6 +21,38 @@ function parseConfigOverrideValue(value: string): unknown {
   }
 }
 
+function parseRuntimeUrl(rawValue: string, source: string): { readonly host: string; readonly port: number } {
+  const trimmed = rawValue.trim();
+  if (trimmed.length === 0) {
+    throw new ConfigError(`${source} requires a non-empty http://host:port value.`);
+  }
+
+  const value = /^[a-z][a-z\d+.-]*:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConfigError(`${source} must be a valid http://host:port URL.`);
+  }
+
+  if (url.protocol !== 'http:') {
+    throw new ConfigError(`${source} must use http:// because Agent connects to the local GoodVibes runtime API.`);
+  }
+  if (!url.hostname) {
+    throw new ConfigError(`${source} must include a hostname.`);
+  }
+  if ((url.pathname && url.pathname !== '/') || url.search || url.hash) {
+    throw new ConfigError(`${source} must point at the runtime root, not a path, query, or hash.`);
+  }
+
+  const port = url.port ? Number.parseInt(url.port, 10) : 3421;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new ConfigError(`${source} port must be from 1 to 65535.`);
+  }
+
+  return { host: url.hostname, port };
+}
+
 function getRuntimeConfig(configManager: ConfigManager): GoodVibesConfig {
   const mutable = configManager as unknown as { config?: GoodVibesConfig };
   if (!mutable.config || typeof mutable.config !== 'object') {
@@ -93,6 +125,22 @@ export function applyRuntimeConfigOverrides(
   return errors;
 }
 
+export function applyRuntimeUrlOverride(
+  configManager: ConfigManager,
+  rawValue: string,
+  source = '--runtime-url',
+): readonly string[] {
+  try {
+    const parsed = parseRuntimeUrl(rawValue, source);
+    applyRuntimeConfigValue(configManager, 'controlPlane.hostMode', hostModeForHostname(parsed.host));
+    applyRuntimeConfigValue(configManager, 'controlPlane.host', parsed.host);
+    applyRuntimeConfigValue(configManager, 'controlPlane.port', parsed.port);
+    return [];
+  } catch (error) {
+    return [error instanceof Error ? error.message : `Invalid ${source}`];
+  }
+}
+
 export function applyRuntimeFeatureFlagOverrides(
   configManager: ConfigManager,
   options: {

package/src/cli/entrypoint.ts

@@ -11,6 +11,7 @@ import {
   applyRuntimeConfigOverrides,
   applyRuntimeConfigValue,
   applyRuntimeFeatureFlagOverrides,
+  applyRuntimeUrlOverride,
   buildCliStatusSnapshot,
   handleGoodVibesCliCommand,
   parseGoodVibesCli,
@@ -31,6 +32,14 @@ type ShellEntrypointOwnership = {
   readonly homeDirectory: string;
 };
 
+function readEnvRuntimeUrl(): { readonly source: string; readonly value: string } | null {
+  const runtimeUrl = process.env['GOODVIBES_AGENT_RUNTIME_URL'];
+  if (runtimeUrl !== undefined) return { source: 'GOODVIBES_AGENT_RUNTIME_URL', value: runtimeUrl };
+  const legacyBaseUrl = process.env['GOODVIBES_AGENT_BASE_URL'];
+  if (legacyBaseUrl !== undefined) return { source: 'GOODVIBES_AGENT_BASE_URL', value: legacyBaseUrl };
+  return null;
+}
+
 export type ShellEntrypointRoots = {
   readonly defaultWorkingDirectory: string;
   readonly homeDirectory: string;
@@ -112,6 +121,15 @@ export async function prepareShellCliRuntime(
   });
   new GlobalNetworkTransportInstaller().install(configManager);
 
+  const envRuntimeUrl = readEnvRuntimeUrl();
+  const envRuntimeUrlErrors = envRuntimeUrl
+    ? applyRuntimeUrlOverride(configManager, envRuntimeUrl.value, envRuntimeUrl.source)
+    : [];
+  if (envRuntimeUrlErrors.length > 0) {
+    console.error(envRuntimeUrlErrors.join('\n'));
+    process.exit(2);
+  }
+
   const overrideErrors = applyRuntimeConfigOverrides(configManager, cli.flags.configOverrides);
   if (overrideErrors.length > 0) {
     console.error(overrideErrors.join('\n'));
@@ -128,6 +146,13 @@ export async function prepareShellCliRuntime(
     const model = cli.flags.model ?? getModelIdFromProviderModel(currentModel);
     applyRuntimeConfigValue(configManager, 'provider.model', formatProviderModel(provider, model));
   }
+  if (cli.flags.runtimeUrl !== undefined) {
+    const runtimeUrlErrors = applyRuntimeUrlOverride(configManager, cli.flags.runtimeUrl);
+    if (runtimeUrlErrors.length > 0) {
+      console.error(runtimeUrlErrors.join('\n'));
+      process.exit(2);
+    }
+  }
   const endpointOverrideErrors = applyRuntimeCommandEndpointFlagOverrides(configManager, cli.command, cli.flags);
   if (endpointOverrideErrors.length > 0) {
     console.error(endpointOverrideErrors.join('\n'));

package/src/cli/help.ts

@@ -57,6 +57,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  -m, --model <registryKey>       Override model. provider:model infers --provider',
     '      --provider <id>            Override provider',
     '      --agent-profile <name>     Use an isolated Agent profile home',
+    '      --runtime-url <url>        External GoodVibes runtime API root',
     '  -C, --cd <dir>                 Set working directory for this launch',
     '      --working-dir <dir>        Alias for --cd',
     '  -c, --config <key=value>       Override a config value for this launch',
@@ -82,6 +83,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     `  ${binary} onboarding`,
     `  ${binary} onboarding status`,
     `  ${binary} status`,
+    `  ${binary} --runtime-url http://127.0.0.1:3421 status`,
     `  ${binary} models current`,
     `  ${binary} models use openai:gpt-5.2`,
     `  ${binary} providers inspect openai`,
@@ -125,14 +127,14 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     examples: ['onboarding', 'onboarding status'],
   },
   status: {
-    usage: ['status', 'status --json'],
+    usage: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
     summary: 'Print Agent config, provider, auth, runtime connection, and onboarding posture.',
-    examples: ['status', 'status --json'],
+    examples: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
   },
   doctor: {
-    usage: ['doctor', 'doctor --json'],
+    usage: ['doctor', 'doctor --json', '--runtime-url http://127.0.0.1:3421 doctor'],
     summary: 'Print status plus actionable setup warnings with cause, impact, and next action.',
-    examples: ['doctor', 'doctor --json'],
+    examples: ['doctor', 'doctor --json', '--runtime-url http://127.0.0.1:3421 doctor'],
   },
   providers: {
     usage: ['providers [list]', 'providers current', 'providers inspect <provider>', 'providers use <provider> [modelRegistryKey]'],
@@ -222,7 +224,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     ],
   },
   subscription: {
-    usage: ['subscription list', 'subscription providers', 'subscription inspect <provider>', 'subscription login <provider> start|finish', 'subscription logout <provider>'],
+    usage: ['subscription list', 'subscription providers', 'subscription inspect <provider>', 'subscription login <provider> start [--open]', 'subscription login <provider> finish <code-or-url>', 'subscription logout <provider>'],
     summary: 'Manage OAuth/subscription-backed provider sessions such as OpenAI subscription access.',
     examples: ['subscription providers', 'subscription login openai start --open', 'subscription inspect openai'],
   },

package/src/cli/management-commands.ts

@@ -14,6 +14,7 @@ import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
 
 export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
+    const binary = runtime.cli.binary;
     const [sub = 'list', ...rest] = runtime.cli.commandArgs;
     const subscriptions = services.subscriptionManager.list();
     const pending = services.subscriptionManager.listPending();
@@ -26,7 +27,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
     }
     if (sub === 'inspect' || sub === 'show') {
       const provider = rest[0];
-      if (!provider) return 'Usage: goodvibes subscription inspect <provider>';
+      if (!provider) return `Usage: ${binary} subscription inspect <provider>`;
       const resolved = getSubscriptionProviderConfig(provider, services.serviceRegistry.get(provider));
       if (!resolved && !services.subscriptionManager.get(provider) && !services.subscriptionManager.getPending(provider)) {
         return `No stored or available subscription provider named ${provider}.`;
@@ -59,7 +60,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
     if (sub === 'login' || sub === 'start') {
       const provider = sub === 'start' ? rest[0] : rest[0];
       const mode = sub === 'start' ? 'start' : rest[1]?.toLowerCase();
-      if (!provider || mode !== 'start') return 'Usage: goodvibes subscription login <provider> start [--open]';
+      if (!provider || mode !== 'start') return `Usage: ${binary} subscription login <provider> start [--open]`;
       const resolved = getSubscriptionProviderConfig(provider, services.serviceRegistry.get(provider));
       if (!resolved) return `No subscription provider found: ${provider}`;
       if (provider === 'openai' && resolved.source === 'builtin') {
@@ -78,7 +79,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
           `  state: ${started.state}`,
           `  redirectUri: ${started.redirectUri}`,
           ...(openResult ? [`  open: ${openResult}`] : []),
-          `  next: goodvibes subscription login ${provider} finish <code-or-url>`,
+          `  next: ${binary} subscription login ${provider} finish <code-or-url>`,
           '  authorizationUrl:',
           `  ${started.authorizationUrl}`,
         ].join('\n');
@@ -91,7 +92,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
         `  state: ${started.pending.state}`,
         `  redirectUri: ${started.pending.redirectUri}`,
         ...(openResult ? [`  open: ${openResult}`] : []),
-        `  next: goodvibes subscription login ${provider} finish <code-or-url>`,
+        `  next: ${binary} subscription login ${provider} finish <code-or-url>`,
         '  authorizationUrl:',
         `  ${started.authorizationUrl}`,
       ].join('\n');
@@ -99,7 +100,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
     if (sub === 'finish' || (sub === 'login' && rest[1]?.toLowerCase() === 'finish')) {
       const provider = sub === 'finish' ? rest[0] : rest[0];
       const codeInput = sub === 'finish' ? rest[1] : rest[2];
-      if (!provider || !codeInput) return 'Usage: goodvibes subscription login <provider> finish <code-or-url>';
+      if (!provider || !codeInput) return `Usage: ${binary} subscription login <provider> finish <code-or-url>`;
       const resolved = getSubscriptionProviderConfig(provider, services.serviceRegistry.get(provider));
       if (!resolved) return `No subscription provider found: ${provider}`;
       const code = extractAuthorizationCode(codeInput);
@@ -127,7 +128,7 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
     }
     if (sub === 'refresh') {
       const provider = rest[0];
-      if (!provider) return 'Usage: goodvibes subscription refresh <provider>';
+      if (!provider) return `Usage: ${binary} subscription refresh <provider>`;
       const resolved = getSubscriptionProviderConfig(provider, services.serviceRegistry.get(provider));
       if (!resolved) return `No subscription provider found: ${provider}`;
       const record = await services.subscriptionManager.refreshOAuthToken(provider, resolved.oauth);
@@ -135,12 +136,12 @@ export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<s
     }
     if (sub === 'logout' || sub === 'remove') {
       const provider = rest[0];
-      if (!provider) return 'Usage: goodvibes subscription logout <provider>';
+      if (!provider) return `Usage: ${binary} subscription logout <provider>`;
       const removed = services.subscriptionManager.logout(provider);
       return removed ? `Subscription removed: ${provider}` : `No stored subscription session existed for ${provider}.`;
     }
     if (sub !== 'list' && sub !== 'status' && sub !== 'review') {
-      return 'Usage: goodvibes subscription [list|providers|inspect <provider>|login <provider> start|finish <code-or-url>|refresh <provider>|logout <provider>]';
+      return `Usage: ${binary} subscription [list|providers|inspect <provider>|login <provider> start|finish <code-or-url>|refresh <provider>|logout <provider>]`;
     }
     const value = {
       subscriptions: subscriptions.map((sub) => ({
@@ -180,7 +181,7 @@ export async function handleSecrets(runtime: CliCommandRuntime): Promise<string>
   if (sub === 'test') {
     const ref = rest.join(' ').trim();
     if (!ref || !ref.startsWith('goodvibes://secrets/') || !isSecretRefInput(ref)) {
-      return 'Usage: goodvibes secrets test goodvibes://secrets/<source>/...';
+      return `Usage: ${runtime.cli.binary} secrets test goodvibes://secrets/<source>/...`;
     }
     const resolved = await resolveSecretRef(ref, { resolveLocalSecret: (key) => secrets.get(key) });
     const value = { ref: describeSecretRef(ref), resolved: Boolean(resolved.value) };
@@ -191,7 +192,7 @@ export async function handleSecrets(runtime: CliCommandRuntime): Promise<string>
     const values = rest.filter((arg) => !arg.startsWith('--'));
     const [key, ...rawValueParts] = values;
     const value = rawValueParts.join(' ');
-    if (!key || !value) return `Usage: goodvibes secrets ${sub} <KEY> <value> [--user|--project] [--secure|--plaintext]`;
+    if (!key || !value) return `Usage: ${runtime.cli.binary} secrets ${sub} <KEY> <value> [--user|--project] [--secure|--plaintext]`;
     if (sub === 'link' && (!value.startsWith('goodvibes://secrets/') || !isSecretRefInput(value))) {
       return 'Invalid secret reference. Use goodvibes://secrets/<source>/...';
     }
@@ -203,7 +204,7 @@ export async function handleSecrets(runtime: CliCommandRuntime): Promise<string>
   }
   if (sub === 'delete') {
     const key = rest.find((arg) => !arg.startsWith('--'));
-    if (!key) return 'Usage: goodvibes secrets delete <KEY> [--user|--project] [--secure|--plaintext]';
+    if (!key) return `Usage: ${runtime.cli.binary} secrets delete <KEY> [--user|--project] [--secure|--plaintext]`;
     const flags = new Set(rest.filter((arg) => arg.startsWith('--')));
     await secrets.delete(key, {
       scope: flags.has('--user') ? 'user' : flags.has('--project') ? 'project' : undefined,
@@ -226,6 +227,7 @@ export async function handleSecrets(runtime: CliCommandRuntime): Promise<string>
 
 export async function handleSessions(runtime: CliCommandRuntime): Promise<string | null> {
   return await withRuntimeServices(runtime, (services) => {
+    const binary = runtime.cli.binary;
     const [sub = 'list', ...rest] = runtime.cli.commandArgs;
     const sessions = services.sessionManager.list();
     if (sub === 'list') {
@@ -237,7 +239,7 @@ export async function handleSessions(runtime: CliCommandRuntime): Promise<string
     }
     if (sub === 'show' || sub === 'info') {
       const target = rest.join(' ').trim();
-      if (!target) return 'Usage: goodvibes sessions show <id|name>';
+      if (!target) return `Usage: ${binary} sessions show <id|name>`;
       const found = sessions.find((session) => session.name === target || session.name.startsWith(target) || session.title.toLowerCase() === target.toLowerCase());
       if (!found) return `Session not found: ${target}`;
       return formatJsonOrText(runtime.cli)(found, [
@@ -252,7 +254,7 @@ export async function handleSessions(runtime: CliCommandRuntime): Promise<string
     if (sub === 'export') {
       const target = rest[0];
       const outputPath = rest[1];
-      if (!target) return 'Usage: goodvibes sessions export <id|name> [path]';
+      if (!target) return `Usage: ${binary} sessions export <id|name> [path]`;
       const found = sessions.find((session) => session.name === target || session.name.startsWith(target) || session.title.toLowerCase() === target.toLowerCase());
       if (!found) return `Session not found: ${target}`;
       const data = services.sessionManager.load(found.name);
@@ -267,9 +269,9 @@ export async function handleSessions(runtime: CliCommandRuntime): Promise<string
     }
     if (sub === 'resume') {
       const target = rest.join(' ').trim();
-      return target ? null : 'Usage: goodvibes sessions resume <id|name>';
+      return target ? null : `Usage: ${binary} sessions resume <id|name>`;
     }
-    return 'Usage: goodvibes sessions list|show <id>|export <id> [path]|resume <id>';
+    return `Usage: ${binary} sessions list|show <id>|export <id> [path]|resume <id>`;
   });
 }
 
@@ -291,11 +293,11 @@ export async function handleTasks(runtime: CliCommandRuntime): Promise<string> {
         : ['GoodVibes tasks', ...tasks.map((task) => `  ${task.id} ${task.status} ${task.kind} ${task.title}`)].join('\n');
     }
     if (sub === 'show') {
-      if (!rest[0]) return 'Usage: goodvibes tasks show <taskId>';
+      if (!rest[0]) return `Usage: ${runtime.cli.binary} tasks show <taskId>`;
       const task = tasks.find((candidate) => candidate.id === rest[0]);
       return task ? JSON.stringify(task, null, 2) : `Unknown task: ${rest[0] ?? ''}`;
     }
-    return 'Usage: goodvibes tasks list|show <taskId>';
+    return `Usage: ${runtime.cli.binary} tasks list|show <taskId>`;
   });
 }
 

package/src/cli/management.ts

@@ -244,7 +244,7 @@ export function readAuthPaths(runtime: CliCommandRuntime) {
 export async function runNonInteractiveAgent(runtime: CliCommandRuntime): Promise<number> {
   const prompt = runtime.cli.flags.prompt ?? runtime.cli.positionals.join(' ').trim();
   if (!prompt) {
-    console.error('Usage: goodvibes run|exec [prompt]');
+    console.error(`Usage: ${runtime.cli.binary} run|exec [prompt]`);
     return 2;
   }
 
@@ -329,6 +329,7 @@ export async function runNonInteractiveAgent(runtime: CliCommandRuntime): Promis
 
 async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
+    const binary = runtime.cli.binary;
     const [sub = 'list', ...rest] = runtime.cli.commandArgs;
     const snapshots = await listProviderRuntimeSnapshots(services.providerRegistry);
     const current = services.providerRegistry.getCurrentModel();
@@ -354,7 +355,7 @@ async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
     }
     if (sub === 'use' || sub === 'set') {
       const provider = rest[0];
-      if (!provider) return 'Usage: goodvibes providers use <provider> [modelRegistryKey]';
+      if (!provider) return `Usage: ${binary} providers use <provider> [modelRegistryKey]`;
       const providerModels = services.providerRegistry
         .getSelectableModels()
         .filter((model) => model.provider === provider || model.registryKey.startsWith(`${provider}:`));
@@ -377,7 +378,7 @@ async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
     }
     if (sub === 'inspect' || sub === 'show') {
       const provider = rest[0];
-      if (!provider) return 'Usage: goodvibes providers inspect <provider>';
+      if (!provider) return `Usage: ${binary} providers inspect <provider>`;
       const snapshot = snapshots.find((candidate) => candidate.providerId === provider);
       if (!snapshot) return `No provider found: ${provider}`;
       const setup = classifyProviderSetup({
@@ -404,7 +405,7 @@ async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
         `  detail: ${snapshot.runtime.auth?.detail ?? snapshot.runtime.notes?.join('; ') ?? ''}`,
       ].join('\n'));
     }
-    if (sub !== 'list') return 'Usage: goodvibes providers [list|current|inspect <provider>|use <provider> [modelRegistryKey]]';
+    if (sub !== 'list') return `Usage: ${binary} providers [list|current|inspect <provider>|use <provider> [modelRegistryKey]]`;
     const value = snapshots.map((snapshot) => ({
       ...classifyProviderSetup({
         providerId: snapshot.providerId,
@@ -433,6 +434,7 @@ async function renderProviders(runtime: CliCommandRuntime): Promise<string> {
 
 async function renderModels(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
+    const binary = runtime.cli.binary;
     const [subOrFilter, ...rest] = runtime.cli.commandArgs;
     const current = services.providerRegistry.getCurrentModel().registryKey;
     const providerSnapshots = await listProviderRuntimeSnapshots(services.providerRegistry);
@@ -469,7 +471,7 @@ async function renderModels(runtime: CliCommandRuntime): Promise<string> {
     }
     if (subOrFilter === 'use' || subOrFilter === 'set') {
       const modelKey = rest[0];
-      if (!modelKey) return 'Usage: goodvibes models use <registryKey>';
+      if (!modelKey) return `Usage: ${binary} models use <registryKey>`;
       const model = services.providerRegistry
         .getSelectableModels()
         .find((candidate) => candidate.registryKey === modelKey || candidate.id === modelKey);
@@ -485,7 +487,7 @@ async function renderModels(runtime: CliCommandRuntime): Promise<string> {
     }
     if (subOrFilter === 'pin' || subOrFilter === 'unpin') {
       const modelKey = rest[0];
-      if (!modelKey) return `Usage: goodvibes models ${subOrFilter} <registryKey>`;
+      if (!modelKey) return `Usage: ${binary} models ${subOrFilter} <registryKey>`;
       if (subOrFilter === 'pin') await services.favoritesStore.pinModel(modelKey);
       else await services.favoritesStore.unpinModel(modelKey);
       return `Model ${subOrFilter === 'pin' ? 'pinned' : 'unpinned'}: ${modelKey}`;

package/src/cli/parser.ts

@@ -59,6 +59,7 @@ function createDefaultFlags(): GoodVibesCliFlags {
     model: undefined,
     agentProfile: undefined,
     daemonHome: undefined,
+    runtimeUrl: undefined,
     workingDir: undefined,
     help: false,
     version: false,
@@ -276,6 +277,12 @@ export function parseGoodVibesCli(
       if (consumed.value !== undefined) flags = withFlag(flags, 'daemonHome', consumed.value);
       continue;
     }
+    if (name === '--runtime-url' || name === '--runtime') {
+      const consumed = getValue(argv, index, inlineValue, name, errors);
+      index = consumed.nextIndex;
+      if (consumed.value !== undefined) flags = withFlag(flags, 'runtimeUrl', consumed.value);
+      continue;
+    }
     if (name === '--working-dir' || name === '--cd' || name === '-C') {
       const consumed = getValue(argv, index, inlineValue, name, errors);
       index = consumed.nextIndex;

package/src/cli/types.ts

@@ -37,6 +37,7 @@ export interface GoodVibesCliFlags {
   readonly model: string | undefined;
   readonly agentProfile: string | undefined;
   readonly daemonHome: string | undefined;
+  readonly runtimeUrl: string | undefined;
   readonly workingDir: string | undefined;
   readonly help: boolean;
   readonly version: boolean;

package/src/cli-flags.ts

@@ -6,6 +6,7 @@ export {
   applyRuntimeCommandEndpointFlagOverrides,
   applyRuntimeEndpointFlagOverrides,
   applyRuntimeFeatureFlagOverrides,
+  applyRuntimeUrlOverride,
   handleGoodVibesCliCommand,
   parseGoodVibesCli,
   renderGoodVibesCommandHelp,

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.1.91';
+let _version = '0.1.93';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {