CLI

CLI Architecture Skill

This skill covers the CLI implementation in Invowk, including Cobra command structure, dynamic command registration, TUI component wrappers, and the execution flow.

Use this skill when working on:

• cmd/invowk/ - CLI commands and structure
• Adding new CLI commands or subcommands
• Modifying command output format
• TUI component integration
• Error handling and exit codes

Command Hierarchy Structure

The CLI is organized under root.go with these main command groups:

Hidden Internal Commands Policy

CRITICAL: All invowk internal * commands MUST remain hidden.

&cobra.Command{
    Use:    "internal",
    Hidden: true,  // ALWAYS true for internal commands
}

Rules:

• Internal commands are for inter-process communication and subprocess execution
• Do NOT document in website docs
• Only mention in .claude/ and README.md
• Used by container runtime, SSH server, TUI server internals

Dynamic Command Registration

The discovery → registration flow (cmd_discovery.go):

Discovery → Validation → Command Registration
                ↓
        DiscoveredCommandSet
         ├── Commands: all discovered
         ├── AmbiguousNames: conflicts
         └── SourceOrder: sorted sources

Transparent Namespace

Unambiguous commands are registered under their SimpleName:

# Only one source defines "build" → user can run directly
invowk cmd build

# Multiple sources define "deploy" → requires disambiguation
invowk cmd @foo deploy      # Using @source prefix
invowk cmd --from foo deploy  # Using --from flag

Hierarchical Tree Building

Multi-word commands (e.g., "deploy staging") are built into a command tree with automatically created parent commands.

TUI Component Wrapper Pattern

All TUI components follow a dual-layer delegation pattern (tui_*.go):

func runTuiInput(cmd *cobra.Command, args []string) error {
    // Layer 1: Check if running under parent TUI server
    if client := tuiserver.NewClientFromEnv(); client != nil {
        // Delegate to parent TUI server via HTTP/IPC
        result, err := client.Input(tuiserver.InputRequest{...})
        return handleResult(result)
    }

    // Layer 2: Direct TUI rendering
    result, err := tui.Input(tui.InputOptions{...})
    return handleResult(result)
}

Available TUI Commands

Benefits:

• Commands work both standalone and nested in TUI server
• Output to stdout for piping/variable assignment
• Consistent behavior across execution contexts

Discovery → Runtime → Execution Flow

The complete execution path (cmd_execute.go):

runCommandWithFlags()
    │
    ├── discovery.GetCommand(cmdName)
    │
    ├── Validate runtime selection
    │   └── Check allowed runtimes for platform
    │
    ├── Validate dependencies
    │   ├── Tools (runtime-aware)
    │   ├── Filepaths (runtime-aware)
    │   ├── Capabilities (host-only)
    │   ├── CustomChecks (runtime-aware)
    │   ├── EnvVars (host-only)
    │   └── Commands (existence check)
    │
    ├── Create ExecutionContext
    │   ├── Selected runtime
    │   ├── Implementation script
    │   ├── Positional arguments
    │   ├── Environment config
    │   ├── Working directory
    │   └── Force rebuild flag
    │
    ├── Create runtime.Registry
    │
    └── Execute via selected runtime

Disambiguation Pattern

Two methods for specifying command source:

@source Prefix (First Argument)

invowk cmd @foo deploy      # Run deploy from foo.invkmod
invowk cmd @invkfile build  # Run build from invkfile.cue

--from Flag

invowk cmd --from foo deploy

Source Name Normalization

normalizeSourceName() handles various formats:

• "foo" → "foo"
• "foo.invkmod" → "foo"
• "invkfile" → "invkfile"
• "invkfile.cue" → "invkfile"

Error Handling & Exit Codes

ExitError Type

type ExitError struct {
    Code int
    Err  error
}

Pattern:

• Command RunE returns ExitError for non-zero exit codes
• Root Execute() catches ExitError and calls os.Exit(exitErr.Code)
• Prevents cascading error messages while maintaining proper exit codes

Styled Error Rendering

cmd_render.go provides styled error messages for:

• Argument validation failures
• Dependency errors
• Runtime mismatches
• Ambiguous commands
• Host platform compatibility issues

Styling System

Unified color palette (styles.go):

Reusable Styles:

• TitleStyle, SubtitleStyle, SuccessStyle, ErrorStyle
• WarningStyle, CmdStyle, VerboseStyle

Global Flags

Root Command (Persistent)

--verbose, -v     // Enable verbose output
--config          // Custom config file path
--interactive, -i // Run in alternate screen buffer

Cmd Command

--runtime, -r     // Override runtime (must be allowed)
--from            // Specify source for disambiguation
--force-rebuild   // Force container image rebuild

Configuration Loading

Flow from root.go:

Execute()
    ↓
cobra.OnInitialize(initRootConfig)
    ├── Apply --config flag override
    ├── Load config via config.Load()
    ├── Surface errors as warnings (non-fatal)
    ├── Apply verbose/interactive from config if not set via flags
    └── Store in GetVerbose(), GetInteractive() accessors

Priority: CLI flags > config file > defaults

Module Commands

Module management (module.go):

Dependency Management

module add <module>     # Add dependency
module remove <module>  # Remove dependency
module sync             # Sync dependencies
module update           # Update dependencies
module deps             # Inspect dependency tree

Discovery Integration Points

disc := discovery.New(cfg)

// Discover and validate all commands (with ambiguity detection)
commandSet, err := disc.DiscoverAndValidateCommandSet()

// Get specific command info (for execution)
cmdInfo, err := disc.GetCommand(cmdName)

// List all discovered commands (for completion)
commands, err := disc.DiscoverCommands()

// List all discovered files (for module operations)
files, err := disc.DiscoverAll()

Design Principles

File Organization

Common Pitfalls