oma-coding-agent 1.1.4

package/src/commands/auth-gateway.ts

@@ -0,0 +1,69 @@
+/**
+ * `omp auth-gateway` — run a forward proxy that injects auth from the broker.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
+import {
+	AUTH_GATEWAY_ACTIONS,
+	type AuthGatewayAction,
+	type AuthGatewayCommandArgs,
+	runAuthGatewayCommand,
+} from "../cli/auth-gateway-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class AuthGateway extends Command {
+	static description = "Run an auth-gateway forward proxy backed by the configured broker";
+
+	static args = {
+		action: Args.string({
+			description: "Sub-command",
+			required: false,
+			options: [...AUTH_GATEWAY_ACTIONS],
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON (token/status/check)" }),
+		bind: Flags.string({ description: "Bind address for `serve` (host:port)", char: "b" }),
+		regenerate: Flags.boolean({ description: "Regenerate the gateway bearer token (token)" }),
+		"no-auth": Flags.boolean({
+			description:
+				"Disable inbound bearer-token auth (serve). Useful when bound to loopback — any caller is allowed.",
+		}),
+		strict: Flags.boolean({
+			description:
+				"For `check`: additionally probe each credential against its provider's chat-completion endpoint. Slower; consumes a tiny amount of quota per credential.",
+		}),
+	};
+
+	static examples = [
+		"# Boot the gateway against the configured broker\n  omp auth-gateway serve",
+		"# Boot on a non-default port\n  omp auth-gateway serve --bind=127.0.0.1:4000",
+		"# Print the gateway bearer token (creates one on first run)\n  omp auth-gateway token",
+		"# Rotate the gateway bearer token\n  omp auth-gateway token --regenerate",
+		"# Run on loopback without any bearer (anyone on this host can call)\n  omp auth-gateway serve --no-auth",
+		"# Show local gateway + broker config status\n  omp auth-gateway status",
+		"# Probe each broker credential to see which one is producing 401s\n  omp auth-gateway check",
+		"# Same, machine-readable for scripts\n  omp auth-gateway check --json",
+		"# Strict check — also exercises each credential with a real chat-completion ping\n  omp auth-gateway check --strict",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(AuthGateway);
+		if (!args.action) {
+			renderCommandHelp("omp", "auth-gateway", AuthGateway);
+			return;
+		}
+		const cmd: AuthGatewayCommandArgs = {
+			action: args.action as AuthGatewayAction,
+			flags: {
+				json: flags.json,
+				bind: flags.bind,
+				regenerate: flags.regenerate,
+				noAuth: flags["no-auth"],
+				strict: flags.strict,
+			},
+		};
+		await initTheme();
+		await runAuthGatewayCommand(cmd);
+	}
+}

package/src/commands/bench.ts

@@ -0,0 +1,42 @@
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { runBenchCommand } from "../cli/bench-cli";
+
+export default class Bench extends Command {
+	static description =
+		"Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)";
+
+	static args = {
+		models: Args.string({
+			description: "Model selectors (provider/model or fuzzy id, e.g. opus)",
+			required: true,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		runs: Flags.integer({ description: "Requests per model (results are averaged)", default: 1 }),
+		"max-tokens": Flags.integer({ description: "Max output tokens per request", default: 512 }),
+		prompt: Flags.string({ description: "Custom prompt text (default: bundled bench prompt)" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	static examples = [
+		"# Compare two models\n  omp bench anthropic/claude-opus-4-5 openai/gpt-5.2",
+		"# Fuzzy selectors work\n  omp bench opus sonnet",
+		"# Average over 3 runs each\n  omp bench opus gpt-5.2 --runs 3",
+		"# Machine-readable output\n  omp bench opus --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Bench);
+		await runBenchCommand({
+			models: args.models ?? [],
+			flags: {
+				runs: flags.runs,
+				maxTokens: flags["max-tokens"],
+				prompt: flags.prompt,
+				json: flags.json,
+			},
+		});
+	}
+}

package/src/commands/commit.ts

@@ -0,0 +1,46 @@
+/**
+ * Generate and optionally push a commit with changelog updates.
+ */
+import { postmortem } from "@oh-my-pi/pi-utils";
+import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { runCommitCommand } from "../commit";
+import type { CommitCommandArgs } from "../commit/types";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Commit extends Command {
+	static description = "Generate a commit message and update changelogs";
+
+	static flags = {
+		push: Flags.boolean({ description: "Push after committing" }),
+		"dry-run": Flags.boolean({ description: "Preview without committing" }),
+		"no-changelog": Flags.boolean({ description: "Skip changelog updates" }),
+		legacy: Flags.boolean({ description: "Use legacy deterministic pipeline" }),
+		context: Flags.string({ char: "c", description: "Additional context for the model" }),
+		model: Flags.string({ char: "m", description: "Override model selection" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Commit);
+
+		const cmd: CommitCommandArgs = {
+			push: flags.push ?? false,
+			dryRun: flags["dry-run"] ?? false,
+			noChangelog: flags["no-changelog"] ?? false,
+			legacy: flags.legacy,
+			context: flags.context,
+			model: flags.model,
+		};
+
+		await initTheme();
+		// The agentic commit flow opens keep-alive sockets to the model provider
+		// and spins up an AgentSession with background async-job + extension
+		// machinery. `session.dispose()` releases what it can, but Bun's fetch
+		// keeps idle connections warm and a few timers (Settings autosave, OAuth
+		// refresh) stay armed long enough to pin the event loop after the commit
+		// is already written. Mirror the `runPrintMode` exit pattern from
+		// `main.ts` so the CLI returns to the shell instead of stranding the user
+		// on Ctrl+C (issue #1041).
+		await runCommitCommand(cmd);
+		await postmortem.quit(0);
+	}
+}

package/src/commands/complete.ts

@@ -0,0 +1,66 @@
+/**
+ * `omp __complete <kind> [-- <prefix>]` — dynamic completion candidates.
+ *
+ * Hidden helper invoked by the generated shell completion scripts to resolve
+ * values that can't be baked into the script: the live model catalog and
+ * on-disk sessions. Output is one `value\tdescription` line per candidate
+ * (tab-separated); shells that show descriptions parse the tab, bash uses the
+ * first field. The import surface is kept deliberately narrow so a TAB press
+ * doesn't pay for the full agent boot.
+ */
+import { type GeneratedProvider, getBundledModels, getBundledProviders } from "@oh-my-pi/pi-catalog/models";
+import { Command } from "@oh-my-pi/pi-utils/cli";
+import { SessionManager } from "../session/session-manager";
+
+export default class Complete extends Command {
+	static hidden = true;
+	static strict = false;
+
+	async run(): Promise<void> {
+		const argv = this.argv.filter(token => token !== "--");
+		const kind = argv[0];
+		const prefix = argv.length > 1 ? argv[argv.length - 1] : "";
+		if (kind === "models") {
+			completeModels(prefix);
+		} else if (kind === "sessions") {
+			await completeSessions(prefix);
+		}
+	}
+}
+
+/** Strip control chars that would corrupt the tab-separated line protocol. */
+function clean(text: string): string {
+	return text.replace(/[\t\r\n]+/g, " ").trim();
+}
+
+function completeModels(prefix: string): void {
+	const needle = prefix.toLowerCase();
+	const seen = new Set<string>();
+	const lines: string[] = [];
+	for (const provider of getBundledProviders()) {
+		for (const model of getBundledModels(provider as GeneratedProvider)) {
+			// Offer both the fully-qualified `provider/id` and the bare `id`
+			// (matches the fuzzy resolution `--model` accepts).
+			const candidates = [`${model.provider}/${model.id}`, model.id];
+			for (const candidate of candidates) {
+				if (seen.has(candidate)) continue;
+				seen.add(candidate);
+				if (needle && !candidate.toLowerCase().includes(needle)) continue;
+				lines.push(`${candidate}\t${model.provider}`);
+			}
+		}
+	}
+	lines.sort();
+	if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+async function completeSessions(prefix: string): Promise<void> {
+	const sessions = await SessionManager.list(process.cwd());
+	const lines: string[] = [];
+	for (const session of sessions) {
+		if (prefix && !session.id.startsWith(prefix)) continue;
+		const label = clean(session.title ?? session.firstMessage ?? "").slice(0, 72);
+		lines.push(`${session.id}\t${label}`);
+	}
+	if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/commands/completions.ts

@@ -0,0 +1,60 @@
+/**
+ * `omp completions <bash|zsh|fish>` — print a shell completion script.
+ *
+ * The script is derived entirely from the declarative command/flag metadata
+ * (see `cli/completion-gen.ts`), so it never drifts from the actual CLI surface.
+ */
+import { APP_NAME, VERSION } from "@oh-my-pi/pi-utils";
+import { Args, type CliConfig, Command, type CommandCtor } from "@oh-my-pi/pi-utils/cli";
+import { buildSpec, generateCompletion, type Shell } from "../cli/completion-gen";
+import { commands } from "../cli-commands";
+
+/** Entry name of the default command whose flags become top-level completions. */
+const ROOT_COMMAND = "launch";
+const SHELLS = ["bash", "zsh", "fish"] as const;
+
+export default class Completions extends Command {
+	static description = "Print a shell completion script (bash, zsh, or fish)";
+
+	static args = {
+		shell: Args.string({
+			description: "Target shell",
+			required: true,
+			options: SHELLS,
+		}),
+	};
+
+	static examples = [
+		`# zsh — eval at startup, or write to a file in $fpath\n  eval "$(${APP_NAME} completions zsh)"`,
+		`# bash\n  eval "$(${APP_NAME} completions bash)"`,
+		`# fish\n  ${APP_NAME} completions fish > ~/.config/fish/completions/${APP_NAME}.fish`,
+	];
+
+	async run(): Promise<void> {
+		const shell = this.argv[0];
+		if (!isShell(shell)) {
+			process.stderr.write(`Usage: ${APP_NAME} completions <${SHELLS.join("|")}>\n`);
+			process.exitCode = 1;
+			return;
+		}
+
+		// Load every command class so we can read its static flag/arg descriptors,
+		// and collect aliases from both the registration table and the class.
+		const loaded = await Promise.all(commands.map(async entry => ({ entry, Cmd: await entry.load() })));
+		const map = new Map<string, CommandCtor>();
+		const aliasMap = new Map<string, readonly string[]>();
+		for (const { entry, Cmd } of loaded) {
+			map.set(entry.name, Cmd);
+			const merged = new Set<string>([...(Cmd.aliases ?? []), ...(entry.aliases ?? [])]);
+			aliasMap.set(entry.name, [...merged]);
+		}
+
+		const config: CliConfig = { bin: APP_NAME, version: VERSION, commands: map };
+		const spec = buildSpec(config, ROOT_COMMAND, aliasMap);
+		await Bun.write(Bun.stdout, generateCompletion(shell, spec));
+	}
+}
+
+function isShell(value: string | undefined): value is Shell {
+	return value === "bash" || value === "zsh" || value === "fish";
+}

package/src/commands/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage configuration settings.
+ */
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
+
+export default class Config extends Command {
+	static description = "Manage configuration settings";
+
+	static args = {
+		action: Args.string({
+			description: "Config action",
+			required: false,
+			options: ACTIONS,
+		}),
+		key: Args.string({
+			description: "Setting key",
+			required: false,
+		}),
+		value: Args.string({
+			description: "Value (for set/reset)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Config);
+		const action = (args.action ?? "list") as ConfigAction;
+		const value = Array.isArray(args.value) ? args.value.join(" ") : args.value;
+
+		const cmd: ConfigCommandArgs = {
+			action,
+			key: args.key,
+			value,
+			flags: {
+				json: flags.json,
+			},
+		};
+
+		await initTheme();
+		await runConfigCommand(cmd);
+	}
+}

package/src/commands/dry-balance.ts

@@ -0,0 +1,43 @@
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { runDryBalanceCommand } from "../cli/dry-balance-cli";
+
+export default class DryBalance extends Command {
+	static description = "Dry-run OAuth account balancing across random session ids";
+
+	static args = {
+		model: Args.string({
+			description: "Model selector (provider/model or fuzzy id). Defaults to the configured default model.",
+			required: false,
+		}),
+	};
+
+	static flags = {
+		model: Flags.string({ description: "Model selector (same syntax as --model on omp)" }),
+		count: Flags.integer({ description: "Number of random session ids to try", default: 100 }),
+		concurrency: Flags.integer({ description: "Maximum concurrent credential resolutions", default: 32 }),
+		json: Flags.boolean({ description: "Output JSON" }),
+		bench: Flags.boolean({ description: "Send one live benchmark request per OAuth account" }),
+	};
+
+	static examples = [
+		"# Dry-run the configured default model with 100 random session ids\n  omp dry-balance",
+		"# Dry-run a specific model\n  omp dry-balance anthropic/claude-sonnet-4-5",
+		"# Larger run with bounded concurrency\n  omp dry-balance --model openai-codex/gpt-5-codex --count 1000 --concurrency 64",
+		"# Benchmark every OAuth account in parallel\n  omp dry-balance --bench",
+		"# Machine-readable output\n  omp dry-balance --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(DryBalance);
+		await runDryBalanceCommand({
+			model: args.model,
+			flags: {
+				model: flags.model,
+				count: flags.count,
+				concurrency: flags.concurrency,
+				json: flags.json,
+				bench: flags.bench,
+			},
+		});
+	}
+}

package/src/commands/gallery.ts

@@ -0,0 +1,52 @@
+/**
+ * Render every built-in tool's renderer across its lifecycle states.
+ */
+import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { GALLERY_STATES, type GalleryState, runGalleryCommand } from "../cli/gallery-cli";
+
+export default class Gallery extends Command {
+	static description = "Preview tool renderers across streaming, in-progress, success, and failure states";
+
+	static flags = {
+		tool: Flags.string({ char: "t", description: "Render a single tool by name" }),
+		state: Flags.string({
+			char: "s",
+			description: "Render only the given lifecycle state(s)",
+			options: [...GALLERY_STATES],
+			multiple: true,
+		}),
+		width: Flags.integer({ char: "w", description: "Render width in columns" }),
+		expanded: Flags.boolean({
+			char: "e",
+			description: "Render the expanded variant of each renderer",
+			default: false,
+		}),
+		plain: Flags.boolean({ description: "Strip ANSI styling from the output", default: false }),
+		screenshot: Flags.boolean({
+			description:
+				"Capture the rendered output as PNG screenshot(s) via VHS instead of printing ANSI (requires vhs)",
+			default: false,
+		}),
+		out: Flags.string({
+			char: "o",
+			description: "Screenshot output path (with --screenshot); suffixed per image when split across multiple",
+		}),
+		font: Flags.string({ description: "Screenshot font family (default: JetBrainsMono Nerd Font)" }),
+		"font-size": Flags.integer({ description: "Screenshot font size in points (default: 18)" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Gallery);
+		await runGalleryCommand({
+			tool: flags.tool,
+			states: flags.state as GalleryState[] | undefined,
+			width: flags.width,
+			expanded: flags.expanded,
+			plain: flags.plain,
+			screenshot: flags.screenshot,
+			out: flags.out,
+			font: flags.font,
+			fontSize: flags["font-size"],
+		});
+	}
+}

package/src/commands/grep.ts

@@ -0,0 +1,48 @@
+/**
+ * Test grep tool.
+ */
+import { GrepOutputMode } from "@oh-my-pi/pi-natives";
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { type GrepCommandArgs, runGrepCommand } from "../cli/grep-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Grep extends Command {
+	static description = "Test grep tool";
+
+	static args = {
+		pattern: Args.string({ description: "Regex pattern to search for", required: false }),
+		path: Args.string({ description: "Directory or file to search", required: false }),
+	};
+
+	static flags = {
+		glob: Flags.string({ char: "g", description: "Filter files by glob pattern" }),
+		limit: Flags.integer({ char: "l", description: "Max matches", default: 20 }),
+		context: Flags.integer({ char: "C", description: "Context lines", default: 2 }),
+		files: Flags.boolean({ char: "f", description: "Output file names only" }),
+		count: Flags.boolean({ char: "c", description: "Output match counts per file" }),
+		"no-gitignore": Flags.boolean({ description: "Include files excluded by .gitignore" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Grep);
+
+		const mode: GrepCommandArgs["mode"] = flags.count
+			? GrepOutputMode.Count
+			: flags.files
+				? GrepOutputMode.FilesWithMatches
+				: GrepOutputMode.Content;
+
+		const cmd: GrepCommandArgs = {
+			pattern: args.pattern ?? "",
+			path: args.path ?? ".",
+			glob: flags.glob,
+			limit: flags.limit,
+			context: flags.context,
+			mode,
+			gitignore: !flags["no-gitignore"],
+		};
+
+		await initTheme();
+		await runGrepCommand(cmd);
+	}
+}

package/src/commands/grievances.ts

@@ -0,0 +1,51 @@
+/**
+ * View, clean, and push reported tool issues from automated QA.
+ */
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { cleanGrievances, listGrievances, pushGrievances } from "../cli/grievances-cli";
+
+export default class Grievances extends Command {
+	static description = "View, clean, or push reported tool issues (auto-QA grievances)";
+
+	static args = {
+		// Positional action: "list" (default), "clean", or "push". A positional
+		// arg keeps the historical `omp grievances` invocation working unchanged
+		// while reusing the same command surface for the clean/push verbs.
+		action: Args.string({
+			description: "list (default), clean, or push",
+			required: false,
+			options: ["list", "clean", "push"],
+			default: "list",
+		}),
+	};
+
+	static flags = {
+		limit: Flags.integer({ char: "n", description: "Number of recent issues to show (list)", default: 20 }),
+		tool: Flags.string({ char: "t", description: "Filter by tool name (list, clean)" }),
+		json: Flags.boolean({ char: "j", description: "Output as JSON", default: false }),
+		id: Flags.integer({ description: "Delete a single grievance by id (clean)" }),
+		all: Flags.boolean({ description: "Delete every grievance (clean)", default: false }),
+	};
+
+	static examples = [
+		"omp grievances",
+		"omp grievances list --tool find",
+		"omp grievances clean --id 209",
+		"omp grievances clean --tool find",
+		"omp grievances clean --all",
+		"omp grievances push",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Grievances);
+		if (args.action === "clean") {
+			await cleanGrievances({ id: flags.id, tool: flags.tool, all: flags.all, json: flags.json });
+			return;
+		}
+		if (args.action === "push") {
+			await pushGrievances({ json: flags.json });
+			return;
+		}
+		await listGrievances({ limit: flags.limit, tool: flags.tool, json: flags.json });
+	}
+}

package/src/commands/install.ts

@@ -0,0 +1,107 @@
+/**
+ * `omp install <target>` — top-level convenience over `omp plugin install` /
+ * `omp plugin link`.
+ *
+ * The docs (omp.sh/docs/extension-authoring) advertise
+ *
+ *   omp install ./my-extension
+ *
+ * as a third loading mechanism that "symlinks the directory into the plugin
+ * set and watches it for changes". Before this command existed, `install` was
+ * not a registered subcommand, so the CLI runner forwarded the argv to the
+ * default `launch` command and the model received `install ./my-extension`
+ * as an initial prompt — see #1496.
+ *
+ * Local-path targets (`./foo`, `/abs/foo`, `~/foo`, or an existing directory)
+ * route to `plugin link` so they are symlinked into the plugin set, matching
+ * the documented behavior. Everything else (`pkg`, `pkg@1.2.3`,
+ * `name@marketplace`) routes to `plugin install`.
+ */
+
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { type PluginAction, type PluginCommandArgs, runPluginCommand } from "../cli/plugin-cli";
+import { initTheme } from "../modes/theme/theme";
+
+/**
+ * Heuristic used to decide whether `omp install <target>` should `link` a
+ * local directory or `install` a remote spec. Exported for tests.
+ */
+export function looksLikeLocalPath(target: string, cwd?: string): boolean {
+	if (target.startsWith(".") || target.startsWith("/") || target.startsWith("~")) return true;
+	// Windows drive prefix (e.g. `C:\foo`).
+	if (/^[a-zA-Z]:[\\/]/.test(target)) return true;
+	// Bare names that happen to exist as a local directory (relative to `cwd`).
+	try {
+		return existsSync(cwd ? path.resolve(cwd, target) : path.resolve(target));
+	} catch {
+		return false;
+	}
+}
+
+export default class Install extends Command {
+	static description = "Install or link an extension package (alias of `plugin install`/`plugin link`)";
+
+	static args = {
+		targets: Args.string({
+			description: "Local path, npm spec, or marketplace ref (e.g. ./my-ext, my-pkg@1.2.3, name@marketplace)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		force: Flags.boolean({ description: "Force install" }),
+		"dry-run": Flags.boolean({ description: "Show actions without applying changes" }),
+		scope: Flags.string({
+			description: 'Install scope: "user" (default) or "project" (marketplace installs only)',
+			options: ["user", "project"],
+		}),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Install);
+		const targets = Array.isArray(args.targets) ? args.targets : args.targets ? [args.targets] : [];
+
+		if (targets.length === 0) {
+			process.stderr.write("Usage: omp install <path | npm-spec | name@marketplace> [...]\n");
+			process.exit(1);
+		}
+
+		await initTheme();
+
+		// Split into local-paths (→ link) and remote specs (→ install). Each batch
+		// preserves user-supplied order so progress output reads naturally.
+		const localPaths: string[] = [];
+		const remoteSpecs: string[] = [];
+		for (const target of targets) {
+			if (looksLikeLocalPath(target)) localPaths.push(target);
+			else remoteSpecs.push(target);
+		}
+
+		const baseFlags: PluginCommandArgs["flags"] = {
+			json: flags.json,
+			force: flags.force,
+			dryRun: flags["dry-run"],
+			scope: flags.scope as "user" | "project" | undefined,
+		};
+
+		for (const localPath of localPaths) {
+			await runPluginCommand({
+				action: "link" satisfies PluginAction,
+				args: [localPath],
+				flags: baseFlags,
+			});
+		}
+
+		if (remoteSpecs.length > 0) {
+			await runPluginCommand({
+				action: "install" satisfies PluginAction,
+				args: remoteSpecs,
+				flags: baseFlags,
+			});
+		}
+	}
+}

package/src/commands/join.ts

@@ -0,0 +1,39 @@
+/**
+ * Join a shared collab session from the CLI: launches the interactive TUI and
+ * immediately runs `/join <link>`.
+ */
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { Args, Command } from "@oh-my-pi/pi-utils/cli";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+
+export default class Join extends Command {
+	static description = "Join a shared collab session (same as /join)";
+
+	static args = {
+		link: Args.string({
+			description: "Collab link shared by the host (/collab)",
+			required: true,
+		}),
+	};
+
+	static examples = [`${APP_NAME} join "relay.example.sh/abc123#key"`];
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Join);
+		const link = args.link?.trim();
+		if (!link) {
+			process.stderr.write(`Usage: ${APP_NAME} join <link>\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			process.stderr.write(`${APP_NAME} join requires an interactive terminal\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const parsed = parseArgs([]);
+		parsed.join = link;
+		await runRootCommand(parsed, []);
+	}
+}