@pablozaiden/terminatui 0.1.2 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,31 @@
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Always run `bun run build` before running tests, to make sure there are no build errors.
+Use `bun run test` to run all the tests.
+
+Always run `bun run test` when you think you are done making changes.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/examples/tui-app/commands/config/app/get.ts

@@ -0,0 +1,66 @@
+import { 
+    Command, 
+    type AppContext, 
+    type OptionSchema, 
+    type OptionValues,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+
+const options = {
+    key: {
+        type: "string",
+        description: "Application configuration key to get",
+        required: true,
+        label: "Key",
+        order: 1,
+        group: "Required",
+        placeholder: "e.g., port, debug, logLevel",
+    },
+} as const satisfies OptionSchema;
+
+export class AppGetCommand extends Command<typeof options> {
+    readonly name = "get";
+    override displayName = "Get App Config";
+    readonly description = "Get an application configuration value";
+    readonly options = options;
+
+    override readonly actionLabel = "Get Value";
+
+    override readonly examples = [
+        { command: "config app get --key port", description: "Get app port" },
+        { command: "config app get --key logLevel", description: "Get log level" },
+    ];
+
+    override async execute(ctx: AppContext, opts: OptionValues<typeof options>): Promise<CommandResult> {
+        // Simulated app config store
+        const appConfig: Record<string, string | number | boolean> = {
+            port: 3000,
+            debug: true,
+            logLevel: "info",
+            maxConnections: 100,
+            timeout: 30000,
+        };
+
+        const value = appConfig[opts.key];
+        
+        if (value === undefined) {
+            ctx.logger.warn(`Key "${opts.key}" not found in application configuration`);
+            return {
+                success: false,
+                message: `Key "${opts.key}" not found`,
+            };
+        }
+
+        ctx.logger.info(`Retrieved app.${opts.key} = ${value}`);
+        return {
+            success: true,
+            data: { key: opts.key, value },
+        };
+    }
+
+    override renderResult(result: CommandResult): string {
+        if (!result.success) return result.message || "Error";
+        const data = result.data as { key: string; value: string | number | boolean };
+        return `app.${data.key} = ${JSON.stringify(data.value)}`;
+    }
+}

package/examples/tui-app/commands/config/app/index.ts

@@ -0,0 +1,27 @@
+import { 
+    Command, 
+    type AppContext,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+import { AppGetCommand } from "./get.ts";
+import { AppSetCommand } from "./set.ts";
+
+export class AppConfigCommand extends Command {
+    readonly name = "app";
+    override displayName = "App Settings";
+    readonly description = "Manage application configuration";
+    readonly options = {};
+
+    override readonly subCommands = [
+        new AppGetCommand(),
+        new AppSetCommand(),
+    ];
+
+    override execute(_ctx: AppContext): CommandResult {
+        console.log("Use 'config app <command>' for application configuration.");
+        console.log("Available: get, set");
+        return { success: true };
+    }
+}
+
+export { AppGetCommand, AppSetCommand };

package/examples/tui-app/commands/config/app/set.ts

@@ -0,0 +1,86 @@
+import { 
+    Command, 
+    type AppContext, 
+    type OptionSchema, 
+    type OptionValues,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+
+const options = {
+    key: {
+        type: "string",
+        description: "Application configuration key to set",
+        required: true,
+        label: "Key",
+        order: 1,
+        group: "Required",
+        placeholder: "e.g., port, debug, logLevel",
+    },
+    value: {
+        type: "string",
+        description: "Value to set",
+        required: true,
+        label: "Value",
+        order: 2,
+        group: "Required",
+        placeholder: "Enter value...",
+    },
+    type: {
+        type: "string",
+        description: "Value type for parsing",
+        enum: ["string", "number", "boolean"] as const,
+        default: "string",
+        label: "Value Type",
+        order: 3,
+        group: "Options",
+    },
+} as const satisfies OptionSchema;
+
+export class AppSetCommand extends Command<typeof options> {
+    readonly name = "set";
+    override displayName = "Set App Config";
+    readonly description = "Set an application configuration value";
+    readonly options = options;
+
+    override readonly actionLabel = "Set Value";
+
+    override readonly examples = [
+        { command: "config app set --key port --value 8080 --type number", description: "Set app port" },
+        { command: "config app set --key debug --value false --type boolean", description: "Disable debug" },
+    ];
+
+    override async execute(ctx: AppContext, opts: OptionValues<typeof options>): Promise<CommandResult> {
+        let parsedValue: string | number | boolean = opts.value;
+        
+        // Parse value based on type
+        if (opts.type === "number") {
+            parsedValue = Number(opts.value);
+            if (isNaN(parsedValue)) {
+                ctx.logger.error(`Invalid number value: "${opts.value}"`);
+                return {
+                    success: false,
+                    message: `Invalid number: "${opts.value}"`,
+                };
+            }
+        } else if (opts.type === "boolean") {
+            parsedValue = opts.value.toLowerCase() === "true";
+        }
+
+        ctx.logger.info(`Setting app.${opts.key} = ${JSON.stringify(parsedValue)}`);
+        
+        // Simulate setting the value
+        await new Promise(resolve => setTimeout(resolve, 300));
+        
+        ctx.logger.info(`Successfully updated application configuration`);
+        return {
+            success: true,
+            data: { key: opts.key, value: parsedValue, type: opts.type },
+        };
+    }
+
+    override renderResult(result: CommandResult): string {
+        if (!result.success) return result.message || "Error";
+        const data = result.data as { key: string; value: string | number | boolean; type: string };
+        return `✓ Set app.${data.key} = ${JSON.stringify(data.value)} (${data.type})`;
+    }
+}

package/examples/tui-app/commands/config/index.ts

@@ -0,0 +1,32 @@
+import { 
+    Command, 
+    type AppContext,
+    type CommandResult 
+} from "../../../../src/index.ts";
+import { UserConfigCommand } from "./user/index.ts";
+import { AppConfigCommand } from "./app/index.ts";
+
+export class ConfigCommand extends Command {
+    readonly name = "config";
+    override displayName = "Config";
+    readonly description = "Manage configuration (user and app settings)";
+    readonly options = {};
+
+    override readonly subCommands = [
+        new UserConfigCommand(),
+        new AppConfigCommand(),
+    ];
+
+    override readonly examples = [
+        { command: "config user get --key name", description: "Get user name" },
+        { command: "config user set --key theme --value dark", description: "Set user theme" },
+        { command: "config app get --key port", description: "Get app port" },
+        { command: "config app set --key debug --value true --type boolean", description: "Enable debug mode" },
+    ];
+
+    override execute(_ctx: AppContext): CommandResult {
+        console.log("Use 'config <category> <command>' to manage settings.");
+        console.log("Categories: user, app");
+        return { success: true };
+    }
+}

package/examples/tui-app/commands/config/user/get.ts

@@ -0,0 +1,65 @@
+import { 
+    Command, 
+    type AppContext, 
+    type OptionSchema, 
+    type OptionValues,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+
+const options = {
+    key: {
+        type: "string",
+        description: "Configuration key to get",
+        required: true,
+        label: "Key",
+        order: 1,
+        group: "Required",
+        placeholder: "e.g., name, email, theme",
+    },
+} as const satisfies OptionSchema;
+
+export class UserGetCommand extends Command<typeof options> {
+    readonly name = "get";
+    override displayName = "Get User Config";
+    readonly description = "Get a user configuration value";
+    readonly options = options;
+
+    override readonly actionLabel = "Get Value";
+
+    override readonly examples = [
+        { command: "config user get --key name", description: "Get user name" },
+        { command: "config user get --key email", description: "Get user email" },
+    ];
+
+    override async execute(ctx: AppContext, opts: OptionValues<typeof options>): Promise<CommandResult> {
+        // Simulated user config store
+        const userConfig: Record<string, string> = {
+            name: "John Doe",
+            email: "john@example.com",
+            theme: "dark",
+            language: "en",
+        };
+
+        const value = userConfig[opts.key];
+        
+        if (value === undefined) {
+            ctx.logger.warn(`Key "${opts.key}" not found in user configuration`);
+            return {
+                success: false,
+                message: `Key "${opts.key}" not found`,
+            };
+        }
+
+        ctx.logger.info(`Retrieved user.${opts.key} = ${value}`);
+        return {
+            success: true,
+            data: { key: opts.key, value },
+        };
+    }
+
+    override renderResult(result: CommandResult): string {
+        if (!result.success) return result.message || "Error";
+        const data = result.data as { key: string; value: string };
+        return `user.${data.key} = "${data.value}"`;
+    }
+}

package/examples/tui-app/commands/config/user/index.ts

@@ -0,0 +1,27 @@
+import { 
+    Command, 
+    type AppContext,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+import { UserGetCommand } from "./get.ts";
+import { UserSetCommand } from "./set.ts";
+
+export class UserConfigCommand extends Command {
+    readonly name = "user";
+    override displayName = "User Settings";
+    readonly description = "Manage user configuration";
+    readonly options = {};
+
+    override readonly subCommands = [
+        new UserGetCommand(),
+        new UserSetCommand(),
+    ];
+
+    override execute(_ctx: AppContext): CommandResult {
+        console.log("Use 'config user <command>' for user configuration.");
+        console.log("Available: get, set");
+        return { success: true };
+    }
+}
+
+export { UserGetCommand, UserSetCommand };

package/examples/tui-app/commands/config/user/set.ts

@@ -0,0 +1,61 @@
+import { 
+    Command, 
+    type AppContext, 
+    type OptionSchema, 
+    type OptionValues,
+    type CommandResult 
+} from "../../../../../src/index.ts";
+
+const options = {
+    key: {
+        type: "string",
+        description: "Configuration key to set",
+        required: true,
+        label: "Key",
+        order: 1,
+        group: "Required",
+        placeholder: "e.g., name, email, theme",
+    },
+    value: {
+        type: "string",
+        description: "Value to set",
+        required: true,
+        label: "Value",
+        order: 2,
+        group: "Required",
+        placeholder: "Enter value...",
+    },
+} as const satisfies OptionSchema;
+
+export class UserSetCommand extends Command<typeof options> {
+    readonly name = "set";
+    override displayName = "Set User Config";
+    readonly description = "Set a user configuration value";
+    readonly options = options;
+
+    override readonly actionLabel = "Set Value";
+
+    override readonly examples = [
+        { command: "config user set --key name --value 'Jane Doe'", description: "Set user name" },
+        { command: "config user set --key theme --value light", description: "Set theme" },
+    ];
+
+    override async execute(ctx: AppContext, opts: OptionValues<typeof options>): Promise<CommandResult> {
+        ctx.logger.info(`Setting user.${opts.key} = "${opts.value}"`);
+        
+        // Simulate setting the value
+        await new Promise(resolve => setTimeout(resolve, 300));
+        
+        ctx.logger.info(`Successfully updated user configuration`);
+        return {
+            success: true,
+            data: { key: opts.key, value: opts.value },
+        };
+    }
+
+    override renderResult(result: CommandResult): string {
+        if (!result.success) return result.message || "Error";
+        const data = result.data as { key: string; value: string };
+        return `✓ Set user.${data.key} = "${data.value}"`;
+    }
+}

package/examples/tui-app/commands/greet.ts

@@ -37,6 +37,7 @@ const greetOptions = {
 
 export class GreetCommand extends Command<typeof greetOptions> {
     readonly name = "greet";
+    override displayName = "Greet";
     readonly description = "Greet someone with a friendly message";
     readonly options = greetOptions;
 

package/examples/tui-app/commands/index.ts

@@ -1,3 +1,4 @@
 export { GreetCommand } from "./greet.ts";
 export { MathCommand } from "./math.ts";
 export { StatusCommand } from "./status.ts";
+export { ConfigCommand } from "./config/index.ts";

package/examples/tui-app/commands/math.ts

@@ -44,6 +44,7 @@ const mathOptions = {
 
 export class MathCommand extends Command<typeof mathOptions> {
     readonly name = "math";
+    override displayName = "Math Operations";
     readonly description = "Perform basic math operations";
     readonly options = mathOptions;
 

package/examples/tui-app/commands/status.ts

@@ -12,12 +12,14 @@ const statusOptions = {
         description: "Show detailed status",
         default: false,
         label: "Detailed",
+        alias: "d",
         order: 1,
     },
 } as const satisfies OptionSchema;
 
 export class StatusCommand extends Command<typeof statusOptions> {
     readonly name = "status";
+    override displayName = "Status";
     readonly description = "Show application status";
     readonly options = statusOptions;
 
@@ -39,7 +41,7 @@ export class StatusCommand extends Command<typeof statusOptions> {
             `  Uptime:   ${data.uptime}`,
             `  Memory:   ${data.memory}`,
             `  Platform: ${data.platform}`,
-            `  Node:     ${data.version}`,
+            `  Bun:      ${data.version}`,
         ].join("\n");
     }
 

package/examples/tui-app/index.ts

@@ -13,7 +13,7 @@
  */
 
 import { TuiApplication } from "../../src/index.ts";
-import { GreetCommand, MathCommand, StatusCommand } from "./commands/index.ts";
+import { GreetCommand, MathCommand, StatusCommand, ConfigCommand } from "./commands/index.ts";
 
 class ExampleApp extends TuiApplication {
     constructor() {
@@ -24,6 +24,7 @@ class ExampleApp extends TuiApplication {
                 new GreetCommand(),
                 new MathCommand(),
                 new StatusCommand(),
+                new ConfigCommand(),
             ],
             enableTui: true,
         });

package/guides/07-async-cancellation.md

@@ -246,58 +246,7 @@ export class DownloadCommand extends Command<typeof options, DownloadConfig> {
 }
 ```
 
-## Step 4: Add Result Rendering
-
-```typescript
-import React from "react";
-import { Text, Box } from "ink";
-
-export class DownloadCommand extends Command<typeof options, DownloadConfig> {
-  // ... previous code ...
-
-  /**
-   * Custom TUI result display
-   */
-  override renderResult(result: CommandResult): React.ReactNode {
-    if (!result.success && result.data?.cancelled) {
-      return (
-        <Box flexDirection="column">
-          <Text color="yellow">⚠ Download Cancelled</Text>
-          {result.data?.downloadedBytes > 0 && (
-            <Text dimColor>
-              Partial: {(result.data.downloadedBytes / 1024 / 1024).toFixed(2)} MB
-            </Text>
-          )}
-        </Box>
-      );
-    }
-
-    if (!result.success) {
-      return <Text color="red">✗ {result.message}</Text>;
-    }
-
-    return (
-      <Box flexDirection="column">
-        <Text color="green">✓ Download Complete</Text>
-        <Text>File: {result.data?.file}</Text>
-        <Text>Size: {(result.data?.size / 1024 / 1024).toFixed(2)} MB</Text>
-      </Box>
-    );
-  }
-
-  /**
-   * Copy file path to clipboard
-   */
-  override getClipboardContent(result: CommandResult): string | undefined {
-    if (result.success && result.data?.file) {
-      return result.data.file;
-    }
-    return undefined;
-  }
-}
-```
-
-## Step 5: Create the Application
+## Step 4: Create the Application
 
 Create `src/index.ts`:
 
@@ -381,7 +330,6 @@ try {
 - Pass signal to `fetch` and other async APIs
 - Clean up resources on cancellation
 - Return meaningful results for cancelled operations
-- Render different UI for cancelled vs success vs error
 
 ## Next Steps
 

package/guides/08-complete-application.md

@@ -149,8 +149,6 @@ export class NotificationService {
 Create `src/commands/add.ts`:
 
 ```typescript
-import React from "react";
-import { Text, Box } from "ink";
 import {
   Command,
   ConfigValidationError,
@@ -231,49 +229,12 @@ export class AddCommand extends Command<typeof options, AddConfig> {
       message: `Created task: ${task.title} (${task.id})`,
     };
   }
-
-  override renderResult(result: CommandResult): React.ReactNode {
-    if (!result.success) {
-      return <Text color="red">✗ {result.message}</Text>;
-    }
-
-    const task = result.data as Task;
-    const priorityColor = {
-      high: "red",
-      medium: "yellow",
-      low: "green",
-    }[task.priority] as "red" | "yellow" | "green";
-
-    return (
-      <Box flexDirection="column" gap={1}>
-        <Text color="green">✓ Task Created</Text>
-        <Box>
-          <Text dimColor>ID: </Text>
-          <Text>{task.id}</Text>
-        </Box>
-        <Box>
-          <Text dimColor>Title: </Text>
-          <Text>{task.title}</Text>
-        </Box>
-        <Box>
-          <Text dimColor>Priority: </Text>
-          <Text color={priorityColor}>{task.priority}</Text>
-        </Box>
-      </Box>
-    );
-  }
-
-  override getClipboardContent(result: CommandResult): string | undefined {
-    return result.data?.id;
-  }
 }
 ```
 
 Create `src/commands/list.ts`:
 
 ```typescript
-import React from "react";
-import { Text, Box } from "ink";
 import {
   Command,
   type AppContext,
@@ -344,45 +305,12 @@ export class ListCommand extends Command<typeof options, ListConfig> {
       message: `Found ${tasks.length} tasks`,
     };
   }
-
-  override renderResult(result: CommandResult): React.ReactNode {
-    const tasks = (result.data as Task[]) ?? [];
-
-    if (tasks.length === 0) {
-      return <Text dimColor>No tasks found</Text>;
-    }
-
-    const priorityColor = (p: string) =>
-      ({ high: "red", medium: "yellow", low: "green" })[p] as "red" | "yellow" | "green";
-
-    return (
-      <Box flexDirection="column" gap={1}>
-        <Text bold>Tasks ({tasks.length})</Text>
-        {tasks.map((task) => (
-          <Box key={task.id} gap={2}>
-            <Text dimColor>[{task.id}]</Text>
-            <Text color={task.status === "completed" ? "gray" : undefined}>
-              {task.status === "completed" ? "✓" : "○"} {task.title}
-            </Text>
-            <Text color={priorityColor(task.priority)}>{task.priority}</Text>
-          </Box>
-        ))}
-      </Box>
-    );
-  }
-
-  override getClipboardContent(result: CommandResult): string | undefined {
-    const tasks = result.data as Task[];
-    return tasks?.map((t) => `${t.id}: ${t.title}`).join("\n");
-  }
 }
 ```
 
 Create `src/commands/complete.ts`:
 
 ```typescript
-import React from "react";
-import { Text, Box } from "ink";
 import {
   Command,
   ConfigValidationError,
@@ -451,31 +379,12 @@ export class CompleteCommand extends Command<typeof options, CompleteConfig> {
       message: `Completed: ${task.title}`,
     };
   }
-
-  override renderResult(result: CommandResult): React.ReactNode {
-    if (!result.success) {
-      return <Text color="red">✗ {result.message}</Text>;
-    }
-
-    const task = result.data as Task;
-    return (
-      <Box flexDirection="column">
-        <Text color="green">✓ Task Completed</Text>
-        <Text>{task.title}</Text>
-        <Text dimColor>
-          Completed at: {task.completedAt?.toLocaleString()}
-        </Text>
-      </Box>
-    );
-  }
 }
 ```
 
 Create `src/commands/stats.ts`:
 
 ```typescript
-import React from "react";
-import { Text, Box } from "ink";
 import {
   Command,
   type AppContext,
@@ -510,50 +419,6 @@ export class StatsCommand extends Command<typeof options> {
       message: `Total: ${stats.total}, Pending: ${stats.pending}, Completed: ${stats.completed}`,
     };
   }
-
-  override renderResult(result: CommandResult): React.ReactNode {
-    const stats = result.data as TaskStats;
-
-    const completionRate = stats.total > 0
-      ? Math.round((stats.completed / stats.total) * 100)
-      : 0;
-
-    return (
-      <Box flexDirection="column" gap={1}>
-        <Text bold>📊 Task Statistics</Text>
-        
-        <Box flexDirection="column">
-          <Box gap={2}>
-            <Text dimColor>Total:</Text>
-            <Text>{stats.total}</Text>
-          </Box>
-          <Box gap={2}>
-            <Text dimColor>Pending:</Text>
-            <Text color="yellow">{stats.pending}</Text>
-          </Box>
-          <Box gap={2}>
-            <Text dimColor>Completed:</Text>
-            <Text color="green">{stats.completed}</Text>
-          </Box>
-          <Box gap={2}>
-            <Text dimColor>Completion Rate:</Text>
-            <Text color={completionRate >= 50 ? "green" : "yellow"}>
-              {completionRate}%
-            </Text>
-          </Box>
-        </Box>
-
-        <Box flexDirection="column" marginTop={1}>
-          <Text bold>By Priority:</Text>
-          <Box gap={2}>
-            <Text color="red">High: {stats.byPriority.high}</Text>
-            <Text color="yellow">Medium: {stats.byPriority.medium}</Text>
-            <Text color="green">Low: {stats.byPriority.low}</Text>
-          </Box>
-        </Box>
-      </Box>
-    );
-  }
 }
 ```
 
@@ -647,7 +512,6 @@ bun start --verbose add "Debug task" --priority low
 | Display Names | `displayName = "Add Task"` |
 | Action Labels | `actionLabel = "Create Task"` |
 | Immediate Execution | `immediateExecution = true` |
-| Custom Results | `renderResult()` |
 | Clipboard Support | `getClipboardContent()` |
 
 ## What You Learned
@@ -655,7 +519,7 @@ bun start --verbose add "Debug task" --priority low
 - **Project Structure**: Organize code into commands, services, types
 - **Shared Services**: Database and notification services
 - **Command Groups**: Organize commands in TUI sidebar
-- **Full TUI Integration**: Custom rendering, clipboard, immediate execution
+- **Full TUI Integration**: Clipboard, immediate execution
 - **Lifecycle Hooks**: `onBeforeRun` and `onAfterRun`
 - **Production Patterns**: Error handling, validation, logging
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/terminatui",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Terminal UI and Command Line Application Framework",
   "repository": {
     "url": "https://github.com/PabloZaiden/terminatui"

package/src/builtins/help.ts

@@ -33,6 +33,13 @@ export class HelpCommand extends Command<OptionSchema> {
     this.appVersion = config.appVersion;
   }
 
+  /**
+   * Help command is CLI-only (auto-injected for CLI use, not shown in TUI).
+   */
+  override supportsTui(): boolean {
+    return false;
+  }
+
   override async execute(_ctx: AppContext): Promise<void> {
     let helpText: string;
 

package/src/tui/TuiApp.tsx

@@ -91,6 +91,7 @@ function TuiAppContent({
     const [selectedCommand, setSelectedCommand] = useState<AnyCommand | null>(null);
     const [commandPath, setCommandPath] = useState<string[]>([]);
     const [commandSelectorIndex, setCommandSelectorIndex] = useState(0);
+    const [selectorIndexStack, setSelectorIndexStack] = useState<number[]>([]);
     const [selectedFieldIndex, setSelectedFieldIndex] = useState(0);
     const [editingField, setEditingField] = useState<string | null>(null);
     const [focusedSection, setFocusedSection] = useState<FocusedSection>(FocusedSection.Config);
@@ -133,9 +134,27 @@ function TuiAppContent({
         return buildCliCommand(name, commandPath, selectedCommand.options, configValues as OptionValues<OptionSchema>);
     }, [name, commandPath, selectedCommand, configValues]);
 
+    // Build breadcrumb with display names by traversing the command path
     const breadcrumb = useMemo(() => {
-        return commandPath.length > 0 ? commandPath : undefined;
-    }, [commandPath]);
+        if (commandPath.length === 0) return undefined;
+        
+        const displayNames: string[] = [];
+        let current: AnyCommand[] = commands;
+        
+        for (const pathPart of commandPath) {
+            const found = current.find((c) => c.name === pathPart);
+            if (found) {
+                displayNames.push(found.displayName ?? found.name);
+                if (found.subCommands) {
+                    current = found.subCommands;
+                }
+            } else {
+                displayNames.push(pathPart);
+            }
+        }
+        
+        return displayNames;
+    }, [commandPath, commands]);
 
     // Initialize config values when command changes
     const initializeConfigValues = useCallback((cmd: AnyCommand) => {
@@ -178,10 +197,22 @@ function TuiAppContent({
         setConfigValues(merged);
     }, [customFields, name]);
 
+    /**
+     * Check if a command has navigable subcommands (excluding commands that don't support TUI).
+     */
+    const hasNavigableSubCommands = useCallback((cmd: AnyCommand): boolean => {
+        if (!cmd.subCommands || cmd.subCommands.length === 0) return false;
+        // Filter out commands that don't support TUI
+        const navigable = cmd.subCommands.filter((sub) => sub.supportsTui());
+        return navigable.length > 0;
+    }, []);
+
     // Handlers
     const handleCommandSelect = useCallback((cmd: AnyCommand) => {
-        // Check if command has subcommands to navigate into
-        if (cmd.subCommands && cmd.subCommands.length > 0 && !cmd.supportsTui() && !cmd.supportsCli()) {
+        // Check if command has navigable subcommands (container commands)
+        if (hasNavigableSubCommands(cmd)) {
+            // Push current selection index to stack before navigating
+            setSelectorIndexStack((prev) => [...prev, commandSelectorIndex]);
             // Navigate into subcommands
             setCommandPath((prev) => [...prev, cmd.name]);
             setCommandSelectorIndex(0);
@@ -201,7 +232,7 @@ function TuiAppContent({
         } else {
             setMode(Mode.Config);
         }
-    }, [initializeConfigValues]);
+    }, [initializeConfigValues, hasNavigableSubCommands, commandSelectorIndex]);
 
     const handleBack = useCallback(() => {
         if (mode === Mode.Running) {
@@ -242,12 +273,15 @@ function TuiAppContent({
             }
             resetExecutor();
         } else if (mode === Mode.CommandSelect && commandPath.length > 0) {
+            // Pop from selector index stack to restore previous selection
+            const previousIndex = selectorIndexStack[selectorIndexStack.length - 1] ?? 0;
+            setSelectorIndexStack((prev) => prev.slice(0, -1));
+            setCommandSelectorIndex(previousIndex);
             setCommandPath((prev) => prev.slice(0, -1));
-            setCommandSelectorIndex(0);
         } else {
             onExit();
         }
-    }, [mode, commandPath, selectedCommand, cancel, onExit, resetExecutor]);
+    }, [mode, commandPath, selectedCommand, selectorIndexStack, cancel, onExit, resetExecutor]);
 
     const handleRunCommand = useCallback(async (cmd?: AnyCommand) => {
         const cmdToRun = cmd ?? selectedCommand;
@@ -413,18 +447,21 @@ function TuiAppContent({
         { enabled: !editingField && !cliModalVisible }
     );
 
-    // Get current commands for selector
+    // Get current commands for selector (excluding commands that don't support TUI)
     const currentCommands = useMemo(() => {
         if (commandPath.length === 0) {
-            return commands;
+            return commands.filter((cmd) => cmd.supportsTui());
         }
 
-        // Navigate to current path
+        // Navigate through the full path to find current level's subcommands
         let current: AnyCommand[] = commands;
-        for (const pathPart of commandPath.slice(0, -1)) {
+        for (const pathPart of commandPath) {
             const found = current.find((c) => c.name === pathPart);
             if (found?.subCommands) {
-                current = found.subCommands;
+                // Filter out commands that don't support TUI
+                current = found.subCommands.filter((sub) => sub.supportsTui());
+            } else {
+                break; // Path invalid or command has no subcommands
             }
         }
         return current;
@@ -477,7 +514,7 @@ function TuiAppContent({
                         onSelectionChange={setCommandSelectorIndex}
                         onSelect={handleCommandSelect}
                         onExit={handleBack}
-                        breadcrumb={commandPath.length > 0 ? commandPath : undefined}
+                        breadcrumb={breadcrumb}
                     />
                 );
 
@@ -486,7 +523,7 @@ function TuiAppContent({
                 return (
                     <box flexDirection="column" flexGrow={1}>
                         <ConfigForm
-                            title={`Configure: ${selectedCommand.name}`}
+                            title={`Configure: ${selectedCommand.displayName ?? selectedCommand.name}`}
                             fieldConfigs={fieldConfigs}
                             values={configValues}
                             selectedIndex={selectedFieldIndex}

package/src/tui/components/CommandSelector.tsx

@@ -146,9 +146,16 @@ export function CommandSelector({
 }
 
 /**
- * Get mode indicator for a command (e.g., "[cli]", "[tui]", "[cli/tui]").
+ * Get mode indicator for a command (e.g., "[cli]", "[tui]", "→" for subcommands).
  */
 function getModeIndicator(command: Command): string {
+    // Show navigation indicator for container commands with navigable subcommands
+    // (excluding commands that don't support TUI)
+    const navigableSubCommands = command.subCommands?.filter((sub) => sub.supportsTui()) ?? [];
+    if (navigableSubCommands.length > 0) {
+        return "→";
+    }
+    
     const cli = command.supportsCli();
     const tui = command.supportsTui();