Skip to main content
Version: 0.3.0

Interactive Mode

Interactive mode (-i / --ivk-interactive) runs commands in an alternate screen buffer with full PTY (pseudo-terminal) support, enabling rich terminal interactions.

Overview​

When you run a command with -i, Invowk:

  1. Creates a pseudo-terminal (PTY) for the command
  2. Displays output in an alternate screen buffer (terminal stays clean)
  3. Forwards all keyboard input to the running command
  4. Allows scrolling and reviewing output after completion
  5. Supports embedded TUI components as modal overlays

Basic Usage​

# Run a command in interactive mode
invowk cmd build --ivk-interactive

When to Use Interactive Mode​

Interactive mode is especially useful for:

# Commands with password prompts
invowk cmd deploy --ivk-interactive

# Commands with sudo
invowk cmd system-update --ivk-interactive

# SSH sessions
invowk cmd remote-shell --ivk-interactive

# Any command with interactive input
invowk cmd database-cli --ivk-interactive

Why These Commands Need It​

Without interactive mode, stdin is not connected to a TTY, which breaks:

  • Password prompts (they can't read your input securely)
  • sudo (requires a TTY for password entry)
  • SSH sessions (need full terminal control)
  • Any program using readline or similar libraries

Enabling by Default​

You can enable interactive mode by default in your configuration:

// In config file: ~/.config/invowk/config.cue
ui: {
    interactive: true  // Enable by default
}

This is equivalent to always passing --ivk-interactive on the command line.

note

Interactive mode works with all runtimes: native, virtual, and container.

Key Bindings​

During Command Execution​

During command execution:
  All keys      → Forwarded to running command
  Ctrl+        → Emergency quit (force exit)

All keyboard input is forwarded directly to the running command, allowing full interaction with password prompts, editors, and other interactive programs.

After Command Completion​

Once the command finishes, you can review the output:

After command completion:
  ↑/k           → Scroll up one line
  ↓/j           → Scroll down one line
  PgUp/b        → Scroll up half page
  PgDown/f/Space→ Scroll down half page
  Home/g        → Go to top
  End/G         → Go to bottom
  q/Esc/Enter   → Exit and return to terminal

The status bar shows:

  • Command exit code
  • Execution duration
  • Scroll position indicator

Embedded TUI Components​

When running in interactive mode, TUI components called from your scripts are rendered as modal overlays on top of the command output, rather than in a separate screen:

{
    name: "interactive-setup"
    description: "Setup with embedded TUI prompts"
    implementations: [{
        script: """
            # When run with --ivk-interactive, TUI components appear as overlays
            NAME=$(invowk tui input --title "Project name:")
            TYPE=$(invowk tui choose --title "Type:" api cli library)
            
            if invowk tui confirm "Create $TYPE project '$NAME'?"; then
                mkdir -p "$NAME"
                echo "Created $NAME"
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

This creates a seamless experience where:

  1. Your script runs in the alternate screen
  2. When a TUI component is needed, it appears as an overlay
  3. After the user completes the interaction, the overlay closes
  4. Script execution continues with the captured value

How It Works​

When a command runs with -i:

  1. Invowk starts a local TUI server
  2. Child processes detect the INVOWK_TUI_ADDR environment variable
  3. Instead of rendering directly, TUI components send requests to the parent
  4. The parent renders them as modal overlays
  5. Results are sent back to the child process

This happens automatically - no changes needed to your scripts.

Alternate Screen Buffer​

The alternate screen buffer is a terminal feature that:

  • Provides a separate "screen" for the command
  • Preserves your terminal history
  • Automatically restores when the command exits

This means after exiting interactive mode:

  • Your terminal looks exactly as it did before
  • No output pollution in your scrollback
  • Clean separation between invowk output and normal terminal use

Limitations​

  • Single command: Can't run multiple commands in parallel in interactive mode
  • PTY required: The terminal must support PTY operations
  • Debian-based containers only: Alpine and Windows container images are not supported

Container Runtime Support​

Interactive mode works seamlessly with the container runtime. Container runs already use the auto-provisioned image layer (enabled by default) so invowk is available inside the container; interactive mode adds the TUI plumbing. See Container Runtime for details. When you run a container command with -i:

  1. Provisioned image layer: Invowk ensures its binary is available (same as non-interactive runs)
  2. TUI server: A local server handles TUI requests from the container
  3. Modal overlays: TUI components render on your terminal, not inside the container
# Run a container command interactively
invowk cmd myproject build -i -r container

Inside your container scripts, you can use all TUI components:

{
    name: "deploy"
    implementations: [{
        script: """
            # TUI components work inside containers!
            ENV=$(invowk tui choose "Select environment" "dev" "staging" "prod")

            if invowk tui confirm "Deploy to $ENV?"; then
                ./deploy.sh "$ENV"
            fi
            """
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "container"
            image: "debian:stable-slim"
        }]
    }]
}
Linux Containers Only

Alpine-based images are not supported — musl-based environments have subtle behavioral differences that reduce runtime reliability. Use Debian-based images (e.g., debian:stable-slim) or language-specific images (e.g., python:3-slim).

Best Practices​

  1. Use for commands that need input: Deploy scripts with confirmations, database migrations, etc.

  2. Don't use for simple commands: Quick commands without interaction don't benefit from interactive mode

  3. Combine with TUI components: Create rich interactive workflows with embedded prompts

  4. Consider config default: If most of your commands need interaction, enable it in config

Examples​

Deployment Script​

{
    name: "deploy"
    description: "Deploy with confirmations"
    implementations: [{
        script: """
            echo "Deploying to production..."

            # This sudo prompt works because we're in interactive mode
            sudo systemctl restart myapp

            echo "Deployment complete!"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Run with: invowk cmd myproject deploy -i

Database Migration​

{
    name: "db migrate"
    description: "Run database migrations"
    implementations: [{
        script: """
            echo "=== Database Migration ==="

            # Interactive confirmation
            if invowk tui confirm "Apply migrations to production?"; then
                # Password prompt works in interactive mode
                psql -h prod-db -U admin -W -f migrations.sql
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Next Steps​