@ipul-labs/forge 1.15.1 → 1.16.1

package/README.md

@@ -86,6 +86,25 @@ npm install -g @ipul-labs/forge
 npx forge <command>
 ```
 
+#### Interactive mode
+
+Run `forge` with no arguments to enter an interactive terminal session:
+
+```bash
+forge
+```
+
+```
+  forge v1.15.1
+
+──────────────────────────────────────────────────
+ ❯ issues --limit 5
+──────────────────────────────────────────────────
+ group/repo  |  agent:claude  |  v1.15.1
+```
+
+Tab-completes command names. Type `use <repo>` to switch repos. Commands that error stay in the session — only `exit`, `quit`, or Ctrl+D leave.
+
 #### End-to-end: issue to production
 
 ```bash
@@ -99,6 +118,7 @@ Runs: analyze → review → validate → apply → watch CI → merge → watch
 ```bash
 forge issues                   # List open issues (--label X, --mine, --limit N)
 forge issue 42                 # Show full description
+forge create-issue --title "fix: broken widget"  # Create a new issue
 forge analyze 42               # Run two-pass analysis, cache result
 forge show                     # Re-render cached analysis
 forge refine --feedback "..."  # Iterate with feedback
@@ -109,6 +129,8 @@ forge ci-fix                   # Re-analyze with failed-pipeline logs
 forge merge                    # Merge the MR
 forge resolution-check         # Verify merged MR closes the issue
 forge close                    # Close the issue
+forge use group/other-repo     # Switch active repo
+forge update                   # Pull latest + reinstall dependencies
 ```
 
 #### Options

package/bin/cli/analyze.js

@@ -260,7 +260,7 @@ function AnalyzeView({
 /**
  * Render a cached analysis (read from session) through the same ResultBlock
  * the live analyze view uses. No streaming, no progress — just the final
- * payload. Used by `forge-agent show`.
+ * payload. Used by `forge show`.
  */
 export async function renderCachedResult(result) {
 	await runApp(
@@ -405,14 +405,14 @@ export async function cmdAnalyze(argv) {
 
 	const iid = Number(argv[1]);
 	if (!Number.isInteger(iid) || iid <= 0) {
-		console.error("Usage: forge-agent analyze <iid> [options]");
+		console.error("Usage: forge analyze <iid> [options]");
 		process.exit(1);
 	}
 
 	const { primary, secondaries } = await resolveRepoSet(argv);
 	if (!primary) {
 		console.error(
-			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge-agent init`.",
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge init`.",
 		);
 		process.exit(1);
 	}

package/bin/cli/apply.js

@@ -188,7 +188,7 @@ export async function cmdApply(argv) {
 	const analysis = await readAnalysis(target.repo, target.iid);
 	if (!analysis) {
 		console.error(
-			`No cached analysis at ${target.repo}#${target.iid}. Run: forge-agent analyze ${target.iid}`,
+			`No cached analysis at ${target.repo}#${target.iid}. Run: forge analyze ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/cifix.js

@@ -253,7 +253,7 @@ export async function cmdCiFix(argv) {
 	const state = await readState(target.repo, target.iid);
 	if (!state?.branch || !state?.mrIid) {
 		console.error(
-			`Session ${target.repo}#${target.iid} has no branch/MR yet. Run: forge-agent apply ${target.iid}`,
+			`Session ${target.repo}#${target.iid} has no branch/MR yet. Run: forge apply ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/createIssue.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import React, { useEffect, useState } from "react";
+import Spinner from "ink-spinner";
+import { h, Box, Text, useApp, runApp } from "./ink.js";
+import { getFlag, projectRoot, resolvePrimaryRepo } from "./utils.js";
+
+function CreateIssueView({ repo, title, description, onDone }) {
+	const { exit } = useApp();
+	const [phase, setPhase] = useState("creating");
+	const [issue, setIssue] = useState(null);
+	const [error, setError] = useState(null);
+
+	useEffect(() => {
+		if (phase === "done" || phase === "error") {
+			onDone({ phase, issue, error });
+			exit();
+		}
+	}, [phase]);
+
+	useEffect(() => {
+		let cancelled = false;
+		(async () => {
+			try {
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(repo);
+				const created = await provider.createIssue(title, description);
+				if (cancelled) return;
+				setIssue(created);
+				setPhase("done");
+			} catch (err) {
+				if (cancelled) return;
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	if (phase === "creating") {
+		return h`<${Box}>
+			<${Text} color="cyan"><${Spinner} type="dots"/></>
+			<${Text}> Creating issue in ${repo}…</>
+		</>`;
+	}
+
+	if (phase === "done") {
+		return h`<${Box} flexDirection="column">
+			<${Box}>
+				<${Text} color="green">✓ </>
+				<${Text}>Created </>
+				<${Text} color="yellow">#${issue.iid}</>
+				<${Text}> — ${issue.title}</>
+			</>
+			${issue.web_url
+				? h`<${Box}><${Text} dimColor>${issue.web_url}</></>`
+				: null}
+			<${Box} marginTop=${1}>
+				<${Text} dimColor>${`Next: forge ship ${issue.iid}`}</>
+			</>
+		</>`;
+	}
+
+	return h`<${Box}>
+		<${Text} color="red">${`✘ ${error?.message ?? String(error)}`}</>
+	</>`;
+}
+
+export async function cmdCreateIssue(argv) {
+	const title = getFlag(argv, "--title") ?? argv.slice(1).find((a) => !a.startsWith("-"));
+	if (!title) {
+		console.error("Usage: forge create-issue --title \"Bug: widget broken\" [--description \"...\"] [--repo <id>] [--json]");
+		process.exit(1);
+	}
+
+	const description = getFlag(argv, "--description") ?? "";
+	const repo = await resolvePrimaryRepo(argv);
+	if (!repo) {
+		console.error(
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge init`.",
+		);
+		process.exit(1);
+	}
+
+	const json = argv.includes("--json");
+	if (json) {
+		const { createProvider } = await import(
+			path.join(projectRoot, "server/forge/core/providers/index.js")
+		);
+		try {
+			const issue = await createProvider(repo).createIssue(title, description);
+			process.stdout.write(`${JSON.stringify(issue, null, 2)}\n`);
+		} catch (err) {
+			process.stdout.write(`${JSON.stringify({ error: err.message })}\n`);
+			process.exit(2);
+		}
+		return;
+	}
+
+	let outcome = { phase: null };
+	await runApp(
+		h`<${CreateIssueView}
+			repo=${repo}
+			title=${title}
+			description=${description}
+			onDone=${(o) => (outcome = o)} />`,
+	);
+	if (outcome.phase === "error") process.exit(2);
+}

package/bin/cli/doctor.js

@@ -123,7 +123,7 @@ export async function cmdDoctor() {
 		{
 			name: "FORGE_TOKEN",
 			fn: () => {
-				if (!process.env.FORGE_TOKEN) throw new Error("not set (run: forge-agent init)");
+				if (!process.env.FORGE_TOKEN) throw new Error("not set (run: forge init)");
 				return "set";
 			},
 		},

package/bin/cli/init.js

@@ -103,7 +103,7 @@ function InitWizard({ envPath, hasExisting, force, onDone }) {
 
 	if (step === "overwrite") {
 		return h`<${Box} flexDirection="column">
-			<${Text}>forge-agent init</>
+			<${Text}>forge init</>
 			<${Box} marginTop=${1}>
 				<${Text} color="yellow">! </>
 				<${Text}>${envPath} exists — overwrite?</>
@@ -121,7 +121,7 @@ function InitWizard({ envPath, hasExisting, force, onDone }) {
 
 	if (step === "token") {
 		return h`<${Box} flexDirection="column">
-			<${Text}>forge-agent init</>
+			<${Text}>forge init</>
 			<${Box} marginTop=${1}/>
 			<${Field} label="FORGE_TOKEN" hint="press Enter to use generated">
 				<${TextInput}
@@ -265,7 +265,7 @@ function InitWizard({ envPath, hasExisting, force, onDone }) {
 				<${Text} dimColor>${`Configured ${data.repos.length} repo${data.repos.length === 1 ? "" : "s"} (primary: ${data.repos[0] ?? "none"}).`}</>
 			</>
 			<${Box}>
-				<${Text} dimColor>${"Next: forge-agent doctor   |   forge-agent issues   |   forge-agent start"}</>
+				<${Text} dimColor>${"Next: forge doctor   |   forge issues   |   forge start"}</>
 			</>
 		</>`;
 	}

package/bin/cli/issue.js

@@ -32,7 +32,7 @@ function IssueDetail({ issue, repo }) {
 			<${Text}>${issue.description ?? "(no description)"}</>
 		</>
 		<${Box} marginTop=${1}>
-			<${Text} dimColor>${`Next: forge-agent ship ${issue.iid}`}</>
+			<${Text} dimColor>${`Next: forge ship ${issue.iid}`}</>
 		</>
 	</>`;
 }
@@ -83,13 +83,13 @@ function IssueView({ iid, repo, onDone }) {
 export async function cmdIssue(argv) {
 	const iid = Number(argv[1]);
 	if (!Number.isInteger(iid) || iid <= 0) {
-		console.error("Usage: forge-agent issue <iid> [--repo <id>]");
+		console.error("Usage: forge issue <iid> [--repo <id>]");
 		process.exit(1);
 	}
 	const repo = (await resolvePrimaryRepo(argv)) ?? null;
 	if (!repo) {
 		console.error(
-			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge-agent init`.",
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge init`.",
 		);
 		process.exit(1);
 	}

package/bin/cli/issues.js

@@ -101,7 +101,7 @@ function IssuesView({ primary, limit, label, mine, onError }) {
 			</>`,
 		)}
 		<${Box} marginTop=${1}>
-			<${Text} dimColor>${"Analyze: forge-agent analyze <iid>"}</>
+			<${Text} dimColor>${"Analyze: forge analyze <iid>"}</>
 		</>
 	</>`;
 }
@@ -110,7 +110,7 @@ export async function cmdIssues(argv) {
 	const primary = await resolvePrimaryRepo(argv);
 	if (!primary) {
 		console.error(
-			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge-agent init`.",
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge init`.",
 		);
 		process.exit(1);
 	}

package/bin/cli/merge.js

@@ -123,7 +123,7 @@ export async function cmdMerge(argv) {
 		const state = await readState(target.repo, target.iid);
 		if (!state?.mrIid) {
 			console.error(
-				`Session ${target.repo}#${target.iid} has no MR. Run: forge-agent apply ${target.iid}`,
+				`Session ${target.repo}#${target.iid} has no MR. Run: forge apply ${target.iid}`,
 			);
 			process.exit(1);
 		}

package/bin/cli/refine.js

@@ -171,7 +171,7 @@ function RefineView({ analysis, primary, secondaries, feedback, model, eventSink
 		})}
 		${result
 			? h`<${Box} marginTop=${1}>
-				<${Text} color="green">${`✓ Refined ${result.changes?.length ?? 0} change(s) — view with: forge-agent show`}</>
+				<${Text} color="green">${`✓ Refined ${result.changes?.length ?? 0} change(s) — view with: forge show`}</>
 			</>`
 			: null}
 	</>`;
@@ -193,7 +193,7 @@ export async function cmdRefine(argv) {
 	const analysis = await readAnalysis(target.repo, target.iid);
 	if (!analysis) {
 		console.error(
-			`No cached analysis at ${target.repo}#${target.iid}. Run: forge-agent analyze ${target.iid}`,
+			`No cached analysis at ${target.repo}#${target.iid}. Run: forge analyze ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/repl.js

@@ -0,0 +1,232 @@
+import readline from "node:readline";
+import path from "node:path";
+import { projectRoot, readPkg, resolvePrimaryRepo } from "./utils.js";
+
+const COMMANDS = [
+	"ship", "init", "start", "repos", "issues", "issue", "create-issue",
+	"analyze", "show", "refine", "validate", "apply", "watch",
+	"ci-fix", "merge", "resolution-check", "close",
+	"session", "doctor", "update", "use", "version", "help",
+	"exit", "quit", "clear",
+];
+
+class ExitInterrupt extends Error {
+	constructor(code) {
+		super();
+		this.code = code;
+	}
+}
+
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const YELLOW = "\x1b[33m";
+const GREEN = "\x1b[32m";
+const CYAN = "\x1b[36m";
+
+function cols() {
+	return process.stdout.columns || 80;
+}
+
+function bar() {
+	return DIM + "─".repeat(cols()) + RESET;
+}
+
+async function resolveContext() {
+	let repo = null;
+	let agent = "claude";
+	try {
+		repo = await resolvePrimaryRepo([]);
+	} catch {}
+	try {
+		const { get } = await import(
+			path.join(projectRoot, "server/forge/core/configStore.js")
+		);
+		const cfg = get();
+		agent = cfg?.defaults?.agent || "claude";
+	} catch {}
+	return { repo, agent };
+}
+
+async function getConfiguredRepos() {
+	try {
+		const { get } = await import(
+			path.join(projectRoot, "server/forge/core/configStore.js")
+		);
+		return (get().repos ?? []).map((r) => r.id);
+	} catch {
+		return [];
+	}
+}
+
+async function switchRepo(repoId) {
+	const { get, patch } = await import(
+		path.join(projectRoot, "server/forge/core/configStore.js")
+	);
+	const repos = get().repos ?? [];
+	const target = repos.find((r) => r.id === repoId);
+	if (!target) {
+		console.error(`Not configured: ${repoId}`);
+		console.error(`Add it first: repos add ${repoId}`);
+		return null;
+	}
+	const rest = repos.filter((r) => r.id !== repoId);
+	await patch({ repos: [target, ...rest] });
+	return repoId;
+}
+
+export async function startRepl(dispatch) {
+	const pkg = await readPkg();
+	const tty = process.stdout.isTTY;
+	const ctx = await resolveContext();
+
+	if (tty) {
+		process.stdout.write(
+			`\n  ${BOLD}forge${RESET} ${DIM}v${pkg.version}${RESET}\n\n`,
+		);
+	}
+
+	function footerText() {
+		const parts = [];
+		if (ctx.repo) parts.push(`${YELLOW}${ctx.repo}${RESET}`);
+		parts.push(`${DIM}agent:${RESET}${ctx.agent}`);
+		parts.push(`${DIM}v${pkg.version}${RESET}`);
+		return ` ${parts.join(`  ${DIM}|${RESET}  `)}`;
+	}
+
+	// Draw top bar, then let readline show its simple prompt,
+	// then draw bottom bar + footer below and move cursor back up.
+	// This keeps readline's prompt short so cursor positioning works.
+	function showPrompt() {
+		if (tty) {
+			process.stdout.write(bar() + "\n");
+		}
+		rl.prompt();
+		if (tty) {
+			process.stdout.write(
+				"\n" + bar() + "\n" + footerText() +
+				"\x1b[2A\x1b[4G",
+			);
+		}
+	}
+
+	function clearFrame() {
+		if (!tty) return;
+		process.stdout.write("\x1b[0J");
+	}
+
+	const prompt = tty ? ` ${DIM}❯${RESET} ` : "forge> ";
+
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+		prompt,
+		completer: (line) => {
+			const hits = COMMANDS.filter((c) => c.startsWith(line.trim()));
+			return [hits.length ? hits : COMMANDS, line];
+		},
+		terminal: tty,
+	});
+
+	showPrompt();
+
+	for await (const line of rl) {
+		const trimmed = line.trim();
+
+		if (!trimmed) {
+			showPrompt();
+			continue;
+		}
+
+		clearFrame();
+
+		if (trimmed === "exit" || trimmed === "quit") {
+			if (tty) process.stdout.write(`\n  ${DIM}Session ended.${RESET}\n\n`);
+			rl.close();
+			return;
+		}
+
+		if (trimmed === "clear") {
+			if (tty) process.stdout.write("\x1b[2J\x1b[H");
+			showPrompt();
+			continue;
+		}
+
+		const argv = parseInput(trimmed);
+
+		if (argv[0] === "use") {
+			process.stdout.write("\n");
+			if (!argv[1]) {
+				const repos = await getConfiguredRepos();
+				if (repos.length === 0) {
+					console.error("No repos configured. Run: repos add <group/repo>");
+				} else {
+					for (const id of repos) {
+						const marker = id === ctx.repo ? `${GREEN}*${RESET} ` : "  ";
+						process.stdout.write(`${marker}${id}\n`);
+					}
+				}
+			} else {
+				const result = await switchRepo(argv[1]);
+				if (result) {
+					ctx.repo = result;
+					process.stdout.write(`${GREEN}*${RESET} ${YELLOW}${result}${RESET}\n`);
+				}
+			}
+			process.stdout.write("\n");
+			showPrompt();
+			continue;
+		}
+
+		process.stdout.write("\n");
+
+		const originalExit = process.exit;
+		try {
+			process.exit = (code) => {
+				throw new ExitInterrupt(code ?? 0);
+			};
+			await dispatch(argv);
+		} catch (err) {
+			if (err instanceof ExitInterrupt) {
+				// swallow
+			} else {
+				console.error(err.message || String(err));
+			}
+		} finally {
+			process.exit = originalExit;
+		}
+
+		process.stdout.write("\n");
+		showPrompt();
+	}
+
+	if (tty) process.stdout.write(`\n  ${DIM}Session ended.${RESET}\n\n`);
+}
+
+function parseInput(line) {
+	const tokens = [];
+	let current = "";
+	let inQuote = null;
+
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (inQuote) {
+			if (ch === inQuote) {
+				inQuote = null;
+			} else {
+				current += ch;
+			}
+		} else if (ch === '"' || ch === "'") {
+			inQuote = ch;
+		} else if (ch === " " || ch === "\t") {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+		} else {
+			current += ch;
+		}
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}

package/bin/cli/repos.js

@@ -7,7 +7,7 @@ function ReposList({ repos }) {
 	if (repos.length === 0) {
 		return h`<${Box} flexDirection="column">
 			<${Text} dimColor>No repos configured.</>
-			<${Text}>${"Add one: forge-agent repos add <group/repo>"}</>
+			<${Text}>${"Add one: forge repos add <group/repo>"}</>
 		</>`;
 	}
 	return h`<${Box} flexDirection="column" marginTop=${1}>
@@ -44,7 +44,7 @@ export async function cmdRepos(argv) {
 
 	const repoArg = argv[2];
 	if (!repoArg) {
-		console.error(`Usage: forge-agent repos ${sub} <group/repo>`);
+		console.error(`Usage: forge repos ${sub} <group/repo>`);
 		process.exit(1);
 	}
 
@@ -76,7 +76,7 @@ export async function cmdRepos(argv) {
 	if (sub === "set-default" || sub === "default") {
 		const target = repos.find((r) => r.id === repoArg);
 		if (!target) {
-			console.error(`Not configured. Add it first: forge-agent repos add ${repoArg}`);
+			console.error(`Not configured. Add it first: forge repos add ${repoArg}`);
 			process.exit(1);
 		}
 		const rest = repos.filter((r) => r.id !== repoArg);

package/bin/cli/resolution.js

@@ -92,7 +92,7 @@ export async function cmdResolutionCheck(argv) {
 	const state = await readState(target.repo, target.iid);
 	if (!state?.mrIid) {
 		console.error(
-			`Session ${target.repo}#${target.iid} has no MR. Run: forge-agent apply ${target.iid}`,
+			`Session ${target.repo}#${target.iid} has no MR. Run: forge apply ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/session.js

@@ -30,7 +30,7 @@ function SessionsTable({ sessions, head }) {
 	if (sessions.length === 0) {
 		return h`<${Box} flexDirection="column">
 			<${Text} dimColor>No sessions yet.</>
-			<${Text}>${"Run: forge-agent analyze <iid>"}</>
+			<${Text}>${"Run: forge analyze <iid>"}</>
 		</>`;
 	}
 	const rows = sessions.map((s) => {
@@ -192,7 +192,7 @@ export async function cmdSession(argv) {
 }
 
 /**
- * Top-level `forge-agent show [<iid>]` — re-renders the cached analysis from
+ * Top-level `forge show [<iid>]` — re-renders the cached analysis from
  * the session through the same Ink view as live analyze. Resolves <iid> via
  * positional arg or HEAD pointer.
  */
@@ -214,7 +214,7 @@ export async function cmdShow(argv) {
 	if (!analysis) {
 		console.error(
 			`No cached analysis at ${sessionDir(target.repo, target.iid)}.\n` +
-				`Run: forge-agent analyze ${target.iid}`,
+				`Run: forge analyze ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/sessionStore.js

@@ -196,9 +196,9 @@ export async function cleanAll() {
  * Resolve a session target from CLI argv. Honours an explicit positional iid
  * or HEAD as fallback. Returns { repo, iid } or null.
  *
- *   forge-agent show              → HEAD
- *   forge-agent show 42           → primary repo + iid 42
- *   forge-agent show 42 --repo X  → repo X + iid 42
+ *   forge show              → HEAD
+ *   forge show 42           → primary repo + iid 42
+ *   forge show 42 --repo X  → repo X + iid 42
  */
 export async function resolveSessionTarget({ explicitIid, explicitRepo }) {
 	if (Number.isInteger(explicitIid) && explicitIid > 0) {

package/bin/cli/ship.js

@@ -1,5 +1,5 @@
 /**
- * `forge-agent ship <iid>` — the headline command.
+ * `forge ship <iid>` — the headline command.
  *
  * Walks an issue from "open ticket" all the way to "deployed in production"
  * with a yes/no Confirm gate at every state-changing step. Each phase calls
@@ -114,7 +114,7 @@ function ProposalSummary({ analysis }) {
 		${changes.map((c, i) =>
 			h`<${Text} key=${i} dimColor>${`  ${c.action.padEnd(7)} ${c.repo}:${c.file}`}</>`,
 		)}
-		<${Text} dimColor>${"  (full diff: forge-agent show " + (analysis.issue?.iid ?? "") + ")"}</>
+		<${Text} dimColor>${"  (full diff: forge show " + (analysis.issue?.iid ?? "") + ")"}</>
 	</>`;
 }
 
@@ -305,7 +305,7 @@ function ShipView({ iid, primary, secondaries, bypassYes, autoMerge, skipValidat
 				const res = await validate(analysis, () => {});
 				if (cancelled) return;
 				if (!res.allPassed) {
-					finishStep("Validating proposal", "fail", "see: forge-agent validate");
+					finishStep("Validating proposal", "fail", "see: forge validate");
 					setError(new Error("validation failed"));
 					setPhase("error");
 					return;
@@ -668,7 +668,7 @@ function ShipView({ iid, primary, secondaries, bypassYes, autoMerge, skipValidat
 	if (phase === "review") {
 		gate = h`<${Box} flexDirection="column" marginTop=${1}>
 			${analysis ? h`<${ProposalSummary} analysis=${analysis} />` : null}
-			<${Box} marginTop=${1}><${Text} dimColor>${"Use 'no' to abort, 'yes' to continue (run `forge-agent refine` separately to iterate)."}</></>
+			<${Box} marginTop=${1}><${Text} dimColor>${"Use 'no' to abort, 'yes' to continue (run `forge refine` separately to iterate)."}</></>
 			<${Confirm}
 				message="Accept this fix and continue toward production?"
 				bypassYes=${bypassYes}
@@ -703,18 +703,18 @@ function ShipView({ iid, primary, secondaries, bypassYes, autoMerge, skipValidat
 		</>`;
 	} else if (phase === "aborted") {
 		footer = h`<${Box} marginTop=${1}>
-			<${Text} dimColor>${`Aborted. Resume with: forge-agent ship ${iid}`}</>
+			<${Text} dimColor>${`Aborted. Resume with: forge ship ${iid}`}</>
 		</>`;
 	} else if (phase === "error") {
 		footer = h`<${Box} marginTop=${1}>
 			<${Text} color="red">${`✘ ${error?.message ?? String(error)}`}</>
-			<${Text} dimColor>${`  (resume with: forge-agent ship ${iid})`}</>
+			<${Text} dimColor>${`  (resume with: forge ship ${iid})`}</>
 		</>`;
 	}
 
 	return h`<${Box} flexDirection="column">
 		<${Box}>
-			<${Text} bold>forge-agent ship </>
+			<${Text} bold>forge ship </>
 			<${Text} color="yellow">#${iid}</>
 			<${Text} dimColor>${`  (${primary}${secondaries.length ? ` + ${secondaries.length} secondaries` : ""})`}</>
 		</>
@@ -728,14 +728,14 @@ function ShipView({ iid, primary, secondaries, bypassYes, autoMerge, skipValidat
 export async function cmdShip(argv) {
 	const iid = Number(argv[1]);
 	if (!Number.isInteger(iid) || iid <= 0) {
-		console.error("Usage: forge-agent ship <iid> [options]");
+		console.error("Usage: forge ship <iid> [options]");
 		process.exit(1);
 	}
 
 	const { primary, secondaries } = await resolveRepoSet(argv);
 	if (!primary) {
 		console.error(
-			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge-agent init`.",
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge init`.",
 		);
 		process.exit(1);
 	}

package/bin/cli/update.js

@@ -0,0 +1,95 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+import React, { useEffect, useState } from "react";
+import Spinner from "ink-spinner";
+import { h, Box, Text, useApp, runApp } from "./ink.js";
+import { projectRoot, readPkg } from "./utils.js";
+
+function UpdateView({ onDone }) {
+	const { exit } = useApp();
+	const [phase, setPhase] = useState("checking");
+	const [info, setInfo] = useState({});
+	const [error, setError] = useState(null);
+
+	useEffect(() => {
+		if (phase === "done" || phase === "error") {
+			onDone({ phase, info, error });
+			exit();
+		}
+	}, [phase]);
+
+	useEffect(() => {
+		(async () => {
+			try {
+				const before = (await readPkg()).version;
+				setInfo((prev) => ({ ...prev, before }));
+
+				setPhase("pulling");
+				execSync("git pull --rebase", { cwd: projectRoot, stdio: "pipe" });
+
+				setPhase("installing");
+				execSync("npm install --no-audit --no-fund", {
+					cwd: projectRoot,
+					stdio: "pipe",
+				});
+
+				const after = (await readPkg()).version;
+				setInfo({ before, after, updated: before !== after });
+				setPhase("done");
+			} catch (err) {
+				setError(err);
+				setPhase("error");
+			}
+		})();
+	}, []);
+
+	if (phase === "checking") {
+		return h`<${Box}>
+			<${Text} color="cyan"><${Spinner} type="dots"/></>
+			<${Text}> Checking for updates…</>
+		</>`;
+	}
+	if (phase === "pulling") {
+		return h`<${Box}>
+			<${Text} color="cyan"><${Spinner} type="dots"/></>
+			<${Text}> Pulling latest changes…</>
+		</>`;
+	}
+	if (phase === "installing") {
+		return h`<${Box}>
+			<${Text} color="cyan"><${Spinner} type="dots"/></>
+			<${Text}> Installing dependencies…</>
+		</>`;
+	}
+	if (phase === "done") {
+		if (info.updated) {
+			return h`<${Box} flexDirection="column">
+				<${Box}>
+					<${Text} color="green">✓ </>
+					<${Text}>Updated </>
+					<${Text} dimColor>${info.before}</>
+					<${Text}> → </>
+					<${Text} color="green">${info.after}</>
+				</>
+				<${Box}><${Text} dimColor>Restart forge to use the new version.</>
+				</>
+			</>`;
+		}
+		return h`<${Box}>
+			<${Text} color="green">✓ </>
+			<${Text}>Already up to date </>
+			<${Text} dimColor>(v${info.after})</>
+		</>`;
+	}
+	return h`<${Box}>
+		<${Text} color="red">${`✘ Update failed: ${error?.message ?? String(error)}`}</>
+	</>`;
+}
+
+export async function cmdUpdate() {
+	let outcome = { phase: null };
+	await runApp(
+		h`<${UpdateView} onDone=${(o) => (outcome = o)} />`,
+	);
+	if (outcome.phase === "error") process.exit(2);
+}

package/bin/cli/validate.js

@@ -210,7 +210,7 @@ export async function cmdValidate(argv) {
 	const analysis = await readAnalysis(target.repo, target.iid);
 	if (!analysis) {
 		console.error(
-			`No cached analysis at ${target.repo}#${target.iid}. Run: forge-agent analyze ${target.iid}`,
+			`No cached analysis at ${target.repo}#${target.iid}. Run: forge analyze ${target.iid}`,
 		);
 		process.exit(1);
 	}

package/bin/cli/watch.js

@@ -206,7 +206,7 @@ export async function cmdWatch(argv) {
 		const state = await readState(target.repo, target.iid);
 		if (!state?.mrIid) {
 			console.error(
-				`Session ${target.repo}#${target.iid} has no MR yet. Run: forge-agent apply ${target.iid}`,
+				`Session ${target.repo}#${target.iid} has no MR yet. Run: forge apply ${target.iid}`,
 			);
 			process.exit(1);
 		}

package/bin/forge-agent.js

@@ -18,13 +18,24 @@ import { cmdResolutionCheck } from "./cli/resolution.js";
 import { cmdClose } from "./cli/close.js";
 import { cmdShip } from "./cli/ship.js";
 import { cmdIssue } from "./cli/issue.js";
+import { cmdCreateIssue } from "./cli/createIssue.js";
+import { startRepl } from "./cli/repl.js";
+import { cmdUpdate } from "./cli/update.js";
+
+async function cmdUse(argv) {
+	const repoId = argv[1];
+	if (!repoId) {
+		return cmdRepos(["repos", "list"]);
+	}
+	return cmdRepos(["repos", "set-default", repoId]);
+}
 
 function usage() {
 	process.stdout.write(`
-forge-agent — AI-powered code change & deploy control panel
+forge — AI-powered code change & deploy control panel
 
 Usage
-  forge-agent <command> [options]
+  forge <command> [options]
 
 Commands
   ship <iid>           ★ End-to-end: analyze → review → validate → apply →
@@ -35,6 +46,7 @@ Commands
   repos                Manage configured repos (list | add | set-default | remove)
   issues               List open issues (--label X, --mine, --limit N)
   issue <iid>          Show full description, labels, author, web URL
+  create-issue         Create a new issue (--title "..." [--description "..."])
   analyze <iid>        Run issue analysis; caches result to ~/.forge/sessions
   show [<iid>]         Re-render the cached analysis for <iid> (or HEAD)
   refine [<iid>]       Iterate the cached analysis with feedback (--feedback "...")
@@ -45,8 +57,10 @@ Commands
   merge [<iid>]        Merge the MR (confirms by default; --auto arms auto-merge)
   resolution-check     Verify the merged MR actually closes the issue
   close [<iid>]        Close the issue (confirms by default)
+  use <repo>           Switch active repo (interactive mode)
   session              Inspect cached sessions (list | show | clean)
   doctor               Check prerequisites (node, git, claude CLI, token, config)
+  update               Pull latest changes + reinstall dependencies
   version              Print version
   help                 Show this help
 
@@ -67,14 +81,15 @@ Options
   --feedback <text>    Refine feedback (refine command)
 
 Examples
-  forge-agent init
-  forge-agent start --port 5055
-  forge-agent repos add group/other-repo
-  forge-agent repos set-default group/other-repo
-  forge-agent issues --limit 10
-  forge-agent analyze 42 --repo group/repo
-  forge-agent analyze 42 --json | jq .
-  forge-agent doctor
+  forge init
+  forge start --port 5055
+  forge repos add group/other-repo
+  forge repos set-default group/other-repo
+  forge issues --limit 10
+  forge analyze 42 --repo group/repo
+  forge analyze 42 --json | jq .
+  forge create-issue --title "fix: broken widget" --description "Details here"
+  forge doctor
 
 `);
 }
@@ -107,6 +122,14 @@ async function main() {
 
 	const argv = process.argv.slice(2);
 	const cmd = argv[0];
+
+	if (!cmd) return startRepl(dispatch);
+
+	return dispatch(argv);
+}
+
+async function dispatch(argv) {
+	const cmd = argv[0];
 	const flags = {
 		force: argv.includes("--force"),
 		port: parsePort(argv),
@@ -123,6 +146,8 @@ async function main() {
 			return cmdIssues(argv);
 		case "issue":
 			return cmdIssue(argv);
+		case "create-issue":
+			return cmdCreateIssue(argv);
 		case "analyze":
 			return cmdAnalyze(argv);
 		case "show":
@@ -151,6 +176,10 @@ async function main() {
 			return cmdSession(argv);
 		case "doctor":
 			return cmdDoctor(flags);
+		case "use":
+			return cmdUse(argv);
+		case "update":
+			return cmdUpdate();
 		case "version":
 		case "--version":
 		case "-v":
@@ -158,7 +187,6 @@ async function main() {
 		case "help":
 		case "--help":
 		case "-h":
-		case undefined:
 			usage();
 			return;
 		default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipul-labs/forge",
-  "version": "1.15.1",
+  "version": "1.16.1",
   "description": "AI-powered code change & deploy control panel — connects Claude, GitLab, and Kubernetes",
   "type": "module",
   "main": "server/forge/routes.js",

package/bin/README.md

@@ -1,210 +0,0 @@
-# `forge-agent` — CLI
-
-> Type an issue, accept the suggested fix, and watch it merge to production. One command.
-
-`forge-agent` is the headless half of [Forge](../README.md). Same orchestrator the web UI uses, no browser required.
-
----
-
-## Install
-
-```bash
-npm install -g forge-agent
-```
-
-Or run from a checkout without installing:
-
-```bash
-node bin/forge-agent.js <command>
-```
-
-You'll need:
-
-- **Node.js 20+**
-- **`claude` CLI** installed and authenticated (`claude auth login`)
-- A **GitLab / GitHub / Azure DevOps** personal access token
-
----
-
-## First-time setup
-
-```bash
-forge-agent init        # interactive wizard — writes .env + ~/.forge/config.json
-forge-agent doctor      # confirm node, git, claude CLI, token, and config are all ready
-```
-
-`init` walks you through:
-
-1. `FORGE_TOKEN` (a generated default — accept with Enter)
-2. `PORT` (only matters if you also want the web UI)
-3. SCM provider (gitlab / github / azuredevops, arrow keys)
-4. Primary repo, then **add another?** (loop to add secondaries — needed for cross-repo features)
-5. SCM token (masked input)
-
----
-
-## The headline command
-
-```bash
-forge-agent ship <iid>
-```
-
-Walks an issue from "open ticket" to "deployed in production" in one command, pausing for `y/N` at every step that changes shared state:
-
-```
-ship <iid>
-  ├─ analyze          (or load cached if you've already analysed)
-  ├─ review proposal  (per-file diff + summary + divergence warnings)
-  ├─ ?accept          → continue, refuse, or refine with feedback
-  ├─ validate         (lint / typecheck / test against the proposed contents)
-  ├─ ?apply           → branch + commit + open MR
-  ├─ watch CI
-  ├─ ?ci-fix          (only if the pipeline fails — re-analyse with logs, push to same branch)
-  ├─ ?merge           → merge to main
-  ├─ watch deploy     (post-merge pipeline)
-  └─ ?close issue
-```
-
-**Resumable.** If you abort or the process dies, re-run `forge-agent ship <iid>` and it picks up at the next gate (state lives in `~/.forge/sessions/`).
-
-**Confirm-by-default.** Cursor on every gate defaults to *no*. Pass `--yes` (or set `FORGE_YES=1`) for unattended mode.
-
-```bash
-forge-agent ship 42                     # interactive, all gates
-forge-agent ship 42 --all-repos         # cross-repo (web-app + api + …)
-forge-agent ship 42 --yes               # unattended, no prompts
-forge-agent ship 42 --auto              # arm auto-merge instead of merging now
-forge-agent ship 42 --skip-validate     # skip the auto-validate before apply
-```
-
----
-
-## Discover what to work on
-
-```bash
-forge-agent issues                      # latest open issues, sorted by recency
-forge-agent issues --label feature      # filter by label
-forge-agent issues --mine               # filter by author (FORGE_USER || USER)
-forge-agent issues --json | jq .        # pipe-friendly
-forge-agent issue 42                    # full description, labels, URL
-```
-
----
-
-## Drive each phase by hand
-
-`ship` is a thin orchestrator — every phase is also a standalone command. Useful when you want to inspect, iterate, or only do part of the flow.
-
-```bash
-forge-agent analyze 42 --all-repos      # produce + cache a fresh analysis
-forge-agent show                        # re-render the most recent analysis
-forge-agent show 42                     # ...for a specific issue
-forge-agent refine --feedback "use Resend instead of SendGrid"
-forge-agent validate                    # lint/typecheck/test the proposal
-forge-agent apply --validate            # gate apply on green validation
-forge-agent watch                       # poll the MR pipeline
-forge-agent ci-fix                      # re-analyse with failed-job logs, push to same branch
-forge-agent merge                       # confirm + merge
-forge-agent merge --auto                # arm auto-merge instead
-forge-agent resolution-check            # ask the model: did this MR actually fix the issue?
-forge-agent close                       # confirm + close the issue
-```
-
-`<iid>`-less commands resolve via the **HEAD pointer** — the most recently touched session. Like `git`'s HEAD: whatever you analysed last is what `show`/`validate`/`apply`/`watch`/`merge`/`close` operate on unless you pass an explicit `<iid>`.
-
----
-
-## Sessions (`~/.forge/sessions/`)
-
-Each issue you work on gets a directory:
-
-```
-~/.forge/sessions/<repo>/<iid>/
-  analysis.json    last cached analyzeIssue result
-  state.json       { phase, branch, mrIid, mrUrl, lastPipelineStatus, ... }
-  events.ndjson    append-only audit log
-~/.forge/sessions/HEAD                "<repo>/<iid>" — the most recently touched session
-```
-
-Inspect and clean:
-
-```bash
-forge-agent session list                # table of all sessions, HEAD marked *
-forge-agent session list --json
-forge-agent session show                # full state of HEAD
-forge-agent session show 42             # ...for a specific issue
-forge-agent session clean 42            # remove one session
-forge-agent session clean --all         # wipe everything
-```
-
-Override the location with `FORGE_SESSIONS_PATH` (handy for CI or test isolation).
-
----
-
-## Common workflows
-
-### Ship a small fix, fully unattended
-
-```bash
-forge-agent ship 42 --yes
-```
-
-Don't do this on prod the first time. Watch a couple of runs interactively first.
-
-### Drive review explicitly
-
-```bash
-forge-agent analyze 42 --all-repos      # produce
-forge-agent show                        # review on the same screen later
-forge-agent refine --feedback "..."     # iterate
-forge-agent ship 42                     # pick up where you left off
-```
-
-### Run from CI
-
-```bash
-FORGE_YES=1 forge-agent ship 42
-```
-
-`--json` is available on `analyze`, `issues`, `issue`, `repos list`, `session list/show`, `watch`, and `validate` — pipe-safe outputs that bypass Ink.
-
-### Recover from a failed step
-
-Just re-run the same command. State is on disk; it picks up where it left off.
-
-```bash
-forge-agent ship 42                     # if it died mid-flow, this resumes
-forge-agent ci-fix                      # if CI failed, fix it without re-running ship
-```
-
----
-
-## Doctor & troubleshooting
-
-```bash
-forge-agent doctor
-```
-
-Sequential checklist — `node`, `git`, `claude`, `FORGE_TOKEN`, config file, frontend build. Exits non-zero if any check fails.
-
-If `analyze` is timing out (5-minute Claude CLI cap), narrow the scope:
-
-```bash
-forge-agent analyze 42 --secondary group/api    # explicit secondary instead of --all-repos
-```
-
-If `apply` says "no repos to validate against", check `forge-agent repos list` and your session's `primary` field.
-
----
-
-## Reference
-
-- [`docs/cli.md`](../docs/cli.md) — full command reference, every flag
-- [`docs/cli-ship-workflow.md`](../docs/cli-ship-workflow.md) — design + status of the end-to-end ship workflow (per-phase delivery, decisions, risks)
-- [`../README.md`](../README.md) — the broader Forge project (web UI, server, multi-provider details)
-
----
-
-## License
-
-MIT — same as the rest of Forge.