@agent-api/cli 0.4.13 → 0.4.15

package/README.md

@@ -64,6 +64,10 @@ Set `AGENT_TUI_UPDATE_CHECK=0` to disable the startup update notice.
 ```bash
 agent-tui
 agent-api
+agent-api run
+agent-api update
+agent-api version
+agent-api help
 agent-api auth login
 agent-api profiles list
 agent-api agent chat
@@ -71,9 +75,13 @@ agent-api workdir status
 agent-api doctor
 ```
 
+No command defaults to the interactive `run` command. If you provide a bare
+first argument, it must be a command name. Local workdirs are explicit: use
+`agent-tui -w <path>`, `agent-tui run <path>`, or `agent-tui run --workdir <path>`.
+
 ## Interactive Workbench
 
-Launch the first-class TUI from your current directory:
+Launch the first-class TUI without an initial local workdir:
 
 ```bash
 agent-tui
@@ -82,12 +90,13 @@ agent-tui
 Open a specific local workdir and expose local tools to the agent:
 
 ```bash
-agent-tui .
-agent-tui ./my-workdir
-agent-tui /absolute/path/to/my-workdir
+agent-tui -w .
+agent-tui run .
+agent-tui run ./my-workdir
+agent-tui --workdir /absolute/path/to/my-workdir
 ```
 
-The workdir argument must point to an existing directory. When provided, the
+The workdir option must point to an existing directory. When provided, the
 workbench automatically turns on local workdir and shell tools in approval mode.
 CLI chat runs can also expose local `SKILL.md` directories and opt into memory:
 
@@ -125,9 +134,8 @@ Inside the workbench, configure the agent run dynamically:
 /switch <name>   switch conversation handle
 ```
 
-The current working directory is loaded as the local workdir. Local workdir
-tools are only exposed to the model when you enable local context with
-`/context` or start with `--workdir`.
+Local workdir tools are only exposed to the model when you start with `-w`,
+`--workdir`, `run [workdir]`, or enable local context with `/context`.
 
 ## Authentication
 

package/dist/index.js

@@ -4,7 +4,7 @@ import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { render } from "ink";
 import React from "react";
-import { activeProfile, configureAgentAppRuntime, conversationSummary, deleteConversation, deleteProfile, getConversation, listConversations, listProfiles, loadConfig, loadConversationConfiguration, loginWithAPIKey, loginWithBrowser, normalizeChatOptions, openWorkdir, profileSummary, redactSecret, resolveRuntimeProfile, runAgent, runtime, useProfile, } from "@agent-api/app-engine/core";
+import { activeProfile, configureAgentAppRuntime, conversationSummary, deleteConversation, deleteProfile, checkForUpdate, formatUpdateNotice, getConversation, installUpdate, listConversations, listProfiles, loadConfig, loadConversationConfiguration, loginWithAPIKey, loginWithBrowser, normalizeChatOptions, openWorkdir, profileSummary, redactSecret, resolveRuntimeProfile, runAgent, runtime, useProfile, } from "@agent-api/app-engine/core";
 import { ChatApp } from "./tui/chat.js";
 import { cliAuthor, cliName, cliVersion, legacyCliName } from "./runtime.js";
 configureAgentAppRuntime({
@@ -19,20 +19,59 @@ program
     .alias("agentsway")
     .alias("agent-tui")
     .description("First-class command line interface for Agent API")
-    .argument("[workdir]", "local workdir to open and expose to the agent")
+    .option("-w, --workdir <path>", "shortcut for run with a local workdir")
+    .option("--update", "check for and install a CLI update, then exit")
     .version(cliVersion)
     .showHelpAfterError()
-    .showSuggestionAfterError();
-program.action(async (workdir) => {
-    const launchWorkdir = workdir ? await validateLaunchWorkdir(workdir) : undefined;
-    if (!process.stdin.isTTY) {
-        program.help();
+    .showSuggestionAfterError()
+    .addHelpText("after", `
+Command contract:
+  No command defaults to "run". A bare first argument is always a command.
+  Use "run [workdir]" or "-w, --workdir <path>" to open a local workdir.
+
+Examples:
+  $ agent-tui
+  $ agent-tui -w .
+  $ agent-tui run .
+  $ agent-tui update
+  $ agent-tui agent chat "Summarize this repo" --workdir .
+`);
+program.action(async (options) => {
+    if (options.update) {
+        await runTopLevelUpdate({ checkOnly: false });
         return;
     }
-    const options = normalizeChatOptions([], launchWorkdir ? { workdir: launchWorkdir } : {});
-    const app = render(React.createElement(ChatApp, { options }));
-    await app.waitUntilExit();
-    clearTerminalAfterTUI();
+    await runWorkbench(options);
+});
+program
+    .command("run")
+    .description("Open the interactive workbench")
+    .argument("[workdir]", "local workdir to open and expose to the agent")
+    .addHelpText("after", `
+Examples:
+  $ agent-tui run
+  $ agent-tui run .
+  $ agent-tui -w .
+`)
+    .action(async function (workdir) {
+    const rootOptions = this.parent?.opts() ?? {};
+    await runWorkbench({ workdir: resolveRunWorkdir(workdir, rootOptions.workdir) });
+});
+program
+    .command("update")
+    .description("Check for and install a CLI update")
+    .addHelpText("after", `
+Checks npm for the latest ${cliName} package and installs it globally when an
+update is available. Equivalent shortcut: agent-tui --update
+`)
+    .action(async () => {
+    await runTopLevelUpdate({ checkOnly: false });
+});
+program
+    .command("version")
+    .description("Print the CLI version")
+    .action(() => {
+    console.log(cliVersion);
 });
 program
     .command("auth")
@@ -80,6 +119,7 @@ program
         platform: process.platform,
     }, null, 2));
 });
+program.addHelpCommand("help [command]", "Display help for command");
 program.exitOverride();
 program.parseAsync(process.argv).catch((error) => {
     if (error?.code === "commander.helpDisplayed" || error?.code === "commander.version")
@@ -92,6 +132,44 @@ function clearTerminalAfterTUI() {
         return;
     process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
 }
+async function runWorkbench(options) {
+    const launchWorkdir = options.workdir ? await validateLaunchWorkdir(options.workdir) : undefined;
+    if (!process.stdin.isTTY) {
+        program.help();
+        return;
+    }
+    const chatOptions = normalizeChatOptions([], launchWorkdir ? { workdir: launchWorkdir } : {});
+    const app = render(React.createElement(ChatApp, { options: chatOptions }));
+    await app.waitUntilExit();
+    clearTerminalAfterTUI();
+}
+function resolveRunWorkdir(positional, option) {
+    if (positional && option)
+        throw new Error("Use either run [workdir] or -w/--workdir, not both.");
+    return option || positional;
+}
+async function runTopLevelUpdate(options) {
+    const result = await checkForUpdate({ timeoutMs: 5_000 });
+    if (!result) {
+        console.error("Could not check for a CLI update right now.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!result.updateAvailable) {
+        console.log(`${result.packageName} is already up to date (${result.current}).`);
+        return;
+    }
+    if (options.checkOnly) {
+        console.log(formatUpdateNotice(result));
+        return;
+    }
+    console.log(formatUpdateNotice(result));
+    console.log("Installing update...");
+    const installed = await installUpdate(result);
+    console.log(`Updated ${result.packageName}: ${result.current} -> ${result.latest}.`);
+    if (installed.output)
+        console.log(installed.output);
+}
 function authLoginCommand() {
     return new Command("login")
         .description("Sign in with browser auth or save an API key profile")

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
 export declare const cliName = "agent-tui";
 export declare const cliAuthor = "AgentsWay";
-export declare const cliVersion = "0.4.13";
+export declare const cliVersion = "0.4.15";
 export declare const legacyCliName = "agent-api-cli";

package/dist/runtime.js

@@ -1,4 +1,4 @@
 export const cliName = "agent-tui";
 export const cliAuthor = "AgentsWay";
-export const cliVersion = "0.4.13";
+export const cliVersion = "0.4.15";
 export const legacyCliName = "agent-api-cli";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/cli",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "First-class command line interface for Agent API",
   "license": "MIT",
   "homepage": "https://github.com/scalebox-dev/agent-tui#readme",
@@ -35,7 +35,7 @@
     "test": "npm run sync-version && npm run build && npm run smoke -w @agent-api/app-engine && node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@agent-api/app-engine": "^0.1.13",
+    "@agent-api/app-engine": "^0.1.15",
     "commander": "^14.0.3",
     "ink": "^6.8.0",
     "react": "^19.2.7"