perchai-cli 2.4.0 → 2.4.1

package/README.md

@@ -6,6 +6,7 @@ Run Perch from a terminal without installing the Desktop app.
 npm install -g perchai-cli
 perch login --app-url https://app.perchai.app
 perch status
+perch --cwd ~/Desktop/Project --permission take_the_wheel
 perch run "Summarize this folder" --cwd .
 perch ap packet ./01-ap
 ```
@@ -13,3 +14,22 @@ perch ap packet ./01-ap
 `perch login` opens your browser, completes OAuth through Perch, and saves the CLI session in the macOS Keychain or `~/.perch/cli-auth-session.json` on other platforms.
 
 The CLI uses the hosted Perch model proxy by default when `--app-url` or `PERCH_CLI_APP_URL` points at a Perch app.
+
+## Interactive Commands
+
+Run `perch`, then use these commands inside the terminal chat:
+
+- `/help` — show commands.
+- `/status` — show cwd, auth, mode, persona, permission, and thread.
+- `/cwd [dir]` — show or change the working directory.
+- `/permission [default|auto_review|take_the_wheel|plan]` — show or change permission mode.
+- `/permissions [default|auto_review|take_the_wheel|plan]` — alias for `/permission`.
+- `/mode [ask|agents|plan]` — show or change chat mode.
+- `/persona [saffron|quill]` — show or change persona.
+- `/app-url [url]` — show or change the Perch app/model proxy URL.
+- `/local-tools [on|off]` — show or toggle local shell/file tools.
+- `/thread [new|id]` — show, reset, or set the current thread id.
+- `/clear` — clear local conversation memory for this terminal session.
+- `/login` — sign in through browser OAuth.
+- `/logout` — clear saved CLI auth.
+- `/exit` — leave Perch CLI.

package/dist/perch.cjs

@@ -221201,7 +221201,7 @@ var DEFAULT_CLI_LOGIN_APP_URL = "https://app.perchai.app";
 var HELP_TEXT = `Perch CLI
 
 Usage:
-  perch [--app-url <url>]
+  perch [--cwd <dir>] [--permission default|auto_review|take_the_wheel|plan] [--mode ask|agents|plan] [--persona saffron|quill] [--app-url <url>]
   perch login [--app-url <url>]
   perch status
   perch logout
@@ -221224,6 +221224,22 @@ Model connection:
   --app-url     Send model calls through a running Perch app, e.g. http://localhost:3000.
                 You can also set PERCH_CLI_APP_URL.
 `;
+var INTERACTIVE_HELP_TEXT = `Interactive commands:
+  /help                         Show this list.
+  /status                       Show cwd, auth, mode, persona, permission, and thread.
+  /cwd [dir]                    Show or change the working directory.
+  /permission [mode]            Show or set default, auto_review, take_the_wheel, or plan.
+  /permissions [mode]           Alias for /permission.
+  /mode [ask|agents|plan]       Show or set chat mode.
+  /persona [saffron|quill]      Show or set persona.
+  /app-url [url]                Show or change the Perch app/model proxy URL.
+  /local-tools [on|off]         Show or toggle local shell/file tools.
+  /thread [new|id]              Show, reset, or set the current thread id.
+  /clear                        Clear local conversation memory for this terminal session.
+  /login                        Sign in through browser OAuth.
+  /logout                       Clear saved CLI auth.
+  /exit                         Leave Perch CLI.
+`;
 async function runPerchCli(argv, writer = defaultWriter(), deps = {}) {
   const parsed = parsePerchCli(argv);
   if (!parsed.ok) {
@@ -221237,7 +221253,7 @@ ${HELP_TEXT}`);
     return 0;
   }
   if ("interactive" in parsed) {
-    return runInteractivePerchCli(writer, deps, parsed.appUrl);
+    return runInteractivePerchCli(writer, deps, parsed);
   }
   try {
     if (parsed.domain === "auth") {
@@ -221306,6 +221322,7 @@ function parsePerchCli(argv) {
   if (args.length === 0) {
     return global2.appUrl ? { ok: true, interactive: true, appUrl: global2.appUrl } : { ok: true, interactive: true };
   }
+  if (args[0]?.startsWith("--")) return parseInteractiveCommand(args, global2.appUrl);
   const [domain, action, folderPath, ...rest2] = args;
   if (domain === "run") return parseRunCommand(args.slice(1), global2.appUrl);
   if (domain === "login") return { ok: true, domain: "auth", action: "login", ...global2.appUrl ? { appUrl: global2.appUrl } : {} };
@@ -221434,7 +221451,84 @@ function parseRunCommand(rest2, inheritedAppUrl) {
     ...appUrl ? { appUrl } : {}
   };
 }
-async function runInteractivePerchCli(writer, deps, appUrl) {
+function parseInteractiveCommand(rest2, inheritedAppUrl) {
+  let cwd;
+  let chatMode;
+  let personaId;
+  let permissionMode;
+  let threadId;
+  let desktopConnected;
+  let cliLocalTools;
+  let appUrl = inheritedAppUrl;
+  for (let index = 0; index < rest2.length; index++) {
+    const value = rest2[index];
+    if (value === "--desktop-tools") {
+      desktopConnected = true;
+      continue;
+    }
+    if (value === "--no-local-tools") {
+      cliLocalTools = false;
+      continue;
+    }
+    if (value === "--local-tools") {
+      cliLocalTools = true;
+      continue;
+    }
+    if (value === "--app-url") {
+      appUrl = rest2[index + 1];
+      index += 1;
+      if (!appUrl) return { ok: false, error: "--app-url requires a URL" };
+      continue;
+    }
+    if (value === "--cwd") {
+      cwd = rest2[index + 1];
+      index += 1;
+      if (!cwd) return { ok: false, error: "--cwd requires a directory path" };
+      continue;
+    }
+    if (value === "--mode") {
+      const next = rest2[index + 1];
+      index += 1;
+      if (!isChatMode(next)) return { ok: false, error: `Unknown chat mode: ${next ?? "(missing)"}` };
+      chatMode = next;
+      continue;
+    }
+    if (value === "--persona") {
+      const next = rest2[index + 1];
+      index += 1;
+      if (!isPersonaId(next)) return { ok: false, error: `Unknown persona: ${next ?? "(missing)"}` };
+      personaId = next;
+      continue;
+    }
+    if (value === "--permission") {
+      const next = rest2[index + 1];
+      index += 1;
+      if (!isPermissionMode(next)) return { ok: false, error: `Unknown permission mode: ${next ?? "(missing)"}` };
+      permissionMode = next;
+      continue;
+    }
+    if (value === "--thread") {
+      threadId = rest2[index + 1];
+      index += 1;
+      if (!threadId) return { ok: false, error: "--thread requires an id" };
+      continue;
+    }
+    return { ok: false, error: `Unknown interactive flag: ${value}` };
+  }
+  return {
+    ok: true,
+    interactive: true,
+    ...appUrl ? { appUrl } : {},
+    ...cwd ? { cwd } : {},
+    ...chatMode ? { chatMode } : {},
+    ...personaId ? { personaId } : {},
+    ...permissionMode ? { permissionMode } : {},
+    ...threadId ? { threadId } : {},
+    ...desktopConnected !== void 0 ? { desktopConnected } : {},
+    ...cliLocalTools !== void 0 ? { cliLocalTools } : {}
+  };
+}
+async function runInteractivePerchCli(writer, deps, options) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     writer.stdout(HELP_TEXT);
     return 0;
@@ -221444,33 +221538,65 @@ async function runInteractivePerchCli(writer, deps, appUrl) {
     output: process.stdout,
     terminal: true
   });
-  const threadId = `cli-${Date.now()}`;
-  const recentMessages = [];
-  const connection = await connectCliModelProxy({ appUrl });
-  writer.stdout("Perch CLI chat. Type /exit to quit.\n");
+  const state = {
+    cwd: resolveExistingDirectory(options.cwd ?? process.cwd()),
+    chatMode: options.chatMode ?? "agents",
+    personaId: options.personaId ?? "saffron",
+    permissionMode: options.permissionMode ?? "default",
+    threadId: options.threadId?.trim() || `cli-${Date.now()}`,
+    desktopConnected: options.desktopConnected ?? false,
+    cliLocalTools: options.cliLocalTools ?? true,
+    appUrl: resolveCliAppUrl(options.appUrl ?? null, null),
+    recentMessages: []
+  };
+  let connection = await connectCliModelProxy({ appUrl: state.appUrl });
+  if (!state.appUrl && connection.appUrl) state.appUrl = connection.appUrl;
+  const reconnect = async () => {
+    connection.restore();
+    connection = await connectCliModelProxy({ appUrl: state.appUrl });
+    if (!state.appUrl && connection.appUrl) state.appUrl = connection.appUrl;
+  };
+  writer.stdout("Perch CLI chat. Type /help for commands, /exit to quit.\n");
+  writer.stdout(renderInteractiveStatus(state, connection));
   try {
     while (true) {
       const prompt = (await rl.question("perch> ")).trim();
       if (!prompt) continue;
       if (prompt === "/exit" || prompt === "exit" || prompt === "quit") break;
+      if (prompt.startsWith("/")) {
+        try {
+          const commandResult = await runInteractiveSlashCommand({
+            input: prompt,
+            state,
+            writer,
+            reconnect
+          });
+          if (commandResult === "exit") break;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          writer.stderr(`${message}
+`);
+        }
+        continue;
+      }
       const result2 = await (deps.runCliTurn ?? runPerchCliTurn)({
         prompt,
-        cwd: process.cwd(),
-        chatMode: "agents",
-        personaId: "saffron",
-        permissionMode: "default",
-        threadId,
-        recentMessages,
+        cwd: state.cwd,
+        chatMode: state.chatMode,
+        personaId: state.personaId,
+        permissionMode: state.permissionMode,
+        threadId: state.threadId,
+        recentMessages: state.recentMessages,
         founderModelSelection: connection.founderModelSelection,
-        desktopConnected: false,
-        cliLocalTools: true
+        desktopConnected: state.desktopConnected,
+        cliLocalTools: state.cliLocalTools
       });
       writeCliTurnResult(result2, false, writer);
-      appendRecentMessage(recentMessages, "user", prompt);
+      appendRecentMessage(state.recentMessages, "user", prompt);
       if (result2.assistantText.trim()) {
-        appendRecentMessage(recentMessages, "assistant", result2.assistantText.trim());
+        appendRecentMessage(state.recentMessages, "assistant", result2.assistantText.trim());
       }
-      if (recentMessages.length > 30) recentMessages.splice(0, recentMessages.length - 30);
+      if (state.recentMessages.length > 30) state.recentMessages.splice(0, state.recentMessages.length - 30);
     }
     return 0;
   } catch (error) {
@@ -221482,6 +221608,179 @@ async function runInteractivePerchCli(writer, deps, appUrl) {
     rl.close();
   }
 }
+async function runInteractiveSlashCommand(input) {
+  const parsed = parseInteractiveSlashCommand(input.input);
+  if (!parsed.ok) {
+    input.writer.stderr(`${parsed.error}
+`);
+    return "continue";
+  }
+  switch (parsed.kind) {
+    case "help":
+      input.writer.stdout(INTERACTIVE_HELP_TEXT);
+      return "continue";
+    case "status": {
+      const session = await readStoredCliAuthSession();
+      input.writer.stdout(renderInteractiveStatus(input.state, null, session));
+      return "continue";
+    }
+    case "cwd":
+      if (!parsed.value) {
+        input.writer.stdout(`cwd: ${input.state.cwd}
+`);
+        return "continue";
+      }
+      input.state.cwd = resolveExistingDirectory(parsed.value);
+      input.writer.stdout(`cwd: ${input.state.cwd}
+`);
+      return "continue";
+    case "permission":
+      if (!parsed.value) {
+        input.writer.stdout(`permission: ${input.state.permissionMode}
+`);
+        return "continue";
+      }
+      input.state.permissionMode = parsed.value;
+      input.writer.stdout(`permission: ${input.state.permissionMode}
+`);
+      return "continue";
+    case "mode":
+      if (!parsed.value) {
+        input.writer.stdout(`mode: ${input.state.chatMode}
+`);
+        return "continue";
+      }
+      input.state.chatMode = parsed.value;
+      input.writer.stdout(`mode: ${input.state.chatMode}
+`);
+      return "continue";
+    case "persona":
+      if (!parsed.value) {
+        input.writer.stdout(`persona: ${input.state.personaId}
+`);
+        return "continue";
+      }
+      input.state.personaId = parsed.value;
+      input.writer.stdout(`persona: ${input.state.personaId}
+`);
+      return "continue";
+    case "appUrl":
+      if (!parsed.value) {
+        input.writer.stdout(`app-url: ${input.state.appUrl ?? "(none)"}
+`);
+        return "continue";
+      }
+      input.state.appUrl = requireCliAppUrl(parsed.value);
+      await input.reconnect();
+      input.writer.stdout(`app-url: ${input.state.appUrl}
+`);
+      return "continue";
+    case "localTools":
+      if (parsed.value === void 0) {
+        input.writer.stdout(`local-tools: ${input.state.cliLocalTools ? "on" : "off"}
+`);
+        return "continue";
+      }
+      input.state.cliLocalTools = parsed.value;
+      input.writer.stdout(`local-tools: ${input.state.cliLocalTools ? "on" : "off"}
+`);
+      return "continue";
+    case "thread":
+      if (!parsed.value) {
+        input.writer.stdout(`thread: ${input.state.threadId}
+`);
+        return "continue";
+      }
+      input.state.threadId = parsed.value === "new" ? `cli-${Date.now()}` : parsed.value;
+      input.state.recentMessages = [];
+      input.writer.stdout(`thread: ${input.state.threadId}
+`);
+      return "continue";
+    case "clear":
+      input.state.recentMessages = [];
+      input.writer.stdout("Conversation memory cleared for this terminal session.\n");
+      return "continue";
+    case "login":
+      await runAuthCommand({
+        ok: true,
+        domain: "auth",
+        action: "login",
+        ...input.state.appUrl ? { appUrl: input.state.appUrl } : {}
+      }, input.writer);
+      await input.reconnect();
+      return "continue";
+    case "logout":
+      await clearStoredCliAuthSession();
+      await input.reconnect();
+      input.writer.stdout("Perch CLI session cleared.\n");
+      return "continue";
+    case "exit":
+      return "exit";
+  }
+}
+function parseInteractiveSlashCommand(input) {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("/")) return { ok: false, error: "Slash commands must start with /." };
+  const [rawCommand, ...parts] = trimmed.slice(1).split(/\s+/).filter(Boolean);
+  const command = rawCommand?.toLowerCase();
+  const value = parts.join(" ").trim() || void 0;
+  switch (command) {
+    case "help":
+    case "?":
+      return { ok: true, kind: "help" };
+    case "status":
+      return { ok: true, kind: "status" };
+    case "cwd":
+      return { ok: true, kind: "cwd", ...value ? { value } : {} };
+    case "permission":
+    case "permissions":
+      if (!value) return { ok: true, kind: "permission" };
+      if (!isPermissionMode(value)) return { ok: false, error: `Unknown permission mode: ${value}` };
+      return { ok: true, kind: "permission", value };
+    case "mode":
+      if (!value) return { ok: true, kind: "mode" };
+      if (!isChatMode(value)) return { ok: false, error: `Unknown chat mode: ${value}` };
+      return { ok: true, kind: "mode", value };
+    case "persona":
+      if (!value) return { ok: true, kind: "persona" };
+      if (!isPersonaId(value)) return { ok: false, error: `Unknown persona: ${value}` };
+      return { ok: true, kind: "persona", value };
+    case "app-url":
+    case "app":
+      return { ok: true, kind: "appUrl", ...value ? { value } : {} };
+    case "local-tools":
+    case "tools":
+      if (!value) return { ok: true, kind: "localTools" };
+      if (value !== "on" && value !== "off") return { ok: false, error: "/local-tools expects on or off." };
+      return { ok: true, kind: "localTools", value: value === "on" };
+    case "thread":
+      return { ok: true, kind: "thread", ...value ? { value: value === "new" ? "new" : value } : {} };
+    case "clear":
+      return { ok: true, kind: "clear" };
+    case "login":
+      return { ok: true, kind: "login" };
+    case "logout":
+      return { ok: true, kind: "logout" };
+    case "exit":
+    case "quit":
+      return { ok: true, kind: "exit" };
+    default:
+      return { ok: false, error: `Unknown command: /${rawCommand ?? ""}. Type /help for commands.` };
+  }
+}
+function renderInteractiveStatus(state, connection, session) {
+  const auth = session === void 0 ? connection?.authenticated ? `signed in${connection.email ? ` as ${connection.email}` : ""}` : "public/anonymous" : isStoredCliAuthSessionUsable(session) ? `signed in${session.email ? ` as ${session.email}` : ""}` : "not signed in";
+  return [
+    `cwd: ${state.cwd}`,
+    `permission: ${state.permissionMode}`,
+    `mode: ${state.chatMode}`,
+    `persona: ${state.personaId}`,
+    `thread: ${state.threadId}`,
+    `local-tools: ${state.cliLocalTools ? "on" : "off"}`,
+    `app-url: ${state.appUrl ?? connection?.appUrl ?? "(none)"}`,
+    `auth: ${auth}`
+  ].join(" \xB7 ") + "\n";
+}
 function parseGlobalFlags(argv) {
   const args = [];
   let appUrl;
@@ -221676,11 +221975,31 @@ function resolveFolderPath(input) {
   if (!stat?.isDirectory()) throw new Error(`Folder does not exist: ${resolved}`);
   return resolved;
 }
+function resolveExistingDirectory(input) {
+  const resolved = resolvePath(input);
+  const stat = import_node_fs10.default.existsSync(resolved) ? import_node_fs10.default.statSync(resolved) : null;
+  if (!stat?.isDirectory()) throw new Error(`Directory does not exist: ${resolved}`);
+  return resolved;
+}
 function resolvePath(input) {
   if (input === "~") return process.env.HOME ?? input;
   if (input.startsWith("~/")) return import_node_path15.default.join(process.env.HOME ?? "", input.slice(2));
   return import_node_path15.default.resolve(input);
 }
+function requireCliAppUrl(input) {
+  const resolved = resolveCliAppUrl(input, null);
+  if (!resolved) throw new Error(`Invalid app URL: ${input}`);
+  return resolved;
+}
+function isChatMode(value) {
+  return value === "ask" || value === "agents" || value === "plan";
+}
+function isPersonaId(value) {
+  return value === "saffron" || value === "quill";
+}
+function isPermissionMode(value) {
+  return value === "default" || value === "auto_review" || value === "take_the_wheel" || value === "plan";
+}
 function formatMoney2(value) {
   return `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perchai-cli",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Perch AI command-line interface",
   "bin": {
     "perch": "bin/perch"