Interactive UI

flow provides both a powerful terminal user interface (TUI) and flexible command-line options to fit your workflow. This guide covers using the interactive browser, customizing the experience, and working with different output formats.

Looking for a native desktop experience?

Mochi is a desktop app built on Flow with a full GUI for browsing, running, and managing your workflows. Join the waitlist →

Using the TUI Browser

The flow browse command launches an interactive browser for discovering and running executables.

Basic Navigation

flow browse  # Launch the interactive browser

Keyboard shortcuts:

• ↑ / ↓ - Move up/down through the list
• ← / → - Navigate between panels (workspaces, executables)
• Enter - Select the highlighted workspace or executable
• Space - Toggle the namespace list for the selected workspace
• Tab - Toggle the executable detail viewer
• R - Run the selected executable (when applicable)
• H - Show help menu with all shortcuts
• C - Copy the selected item (see Copying)
• Q - Quit the browser

Mouse:

• Scroll wheel - Move the selection in lists and tables, or scroll detail views
• Click - Select a row; click it again to open it
• Click a breadcrumb - Go back to that page

While mouse support is on, hold Shift (Option on iTerm2) to select text with the mouse. To turn it off, see Mouse Support.

Copying

Press C in any view to copy to the clipboard:

View	Copies
Executable list or detail	The command that runs it, e.g. flow build api:binary
Workspace list or detail	The workspace name (workspace/namespace for a namespace row)
Template detail	The template file's location
Secret list or detail	The secret name, never its value
YAML or JSON views	The raw YAML or JSON
Other lists and tables	The first column of the selected row

In a secret's detail view, V copies the secret value.

Copying writes both the system clipboard and the OSC 52 terminal escape, so it works locally and over SSH. Over SSH your terminal has to support OSC 52; in tmux, add set -g set-clipboard on to your tmux.conf.

Filtering and Search

Filter executables by various criteria:

# Filter by workspace
flow browse --workspace api-service

# Filter by namespace
flow browse --namespace deployment

# Filter by a namespace and everything nested under it
flow browse --namespace 'deployment/*'

# Filter by verb
flow browse --verb deploy

# Filter by tags
flow browse --tag production --tag critical

# Search by name or description
flow browse --filter "database backup"

# Show executables from all namespaces (not just current)
flow browse --all

Combine filters for precise results:

flow browse --workspace api --verb deploy --tag production

Running Executables

From the browser:

• Select an executable and press R to run it
• Arguments and prompts will be handled interactively

Direct execution:

# View specific executable details
flow browse deploy api:production

# Run without browsing
flow deploy api:production

Output Formats

Control how flow displays information with output format options.

TUI vs Non-Interactive

# Interactive TUI (default)
flow browse
flow browse --output tui
flow workspace list
flow workspace list --output tui
flow secret list
flow secret list --output tui

# Simple list output
flow browse --output json
flow workspace list --output json
flow secret list --output yaml

Disabling the TUI

flow drops to plain output on its own when stdin or stdout isn't a terminal — in CI, in a script, or when piped into another command. To disable the TUI while attached to a terminal:

# Permanently disable TUI
flow config set tui false

# Temporarily disable with environment variable
DISABLE_FLOW_INTERACTIVE=true flow browse

Customization

Themes

Choose from several built-in themes:

# Available themes
flow config set theme default      # Everforest (default)
flow config set theme light        # Light theme
flow config set theme dark         # Dark theme
flow config set theme dracula      # Dracula
flow config set theme tokyo-night  # Tokyo Night

Custom Colors

Override theme colors by editing your config file:

# In your flow config file
colorOverride:
  primary: "#83C092"
  secondary: "#D699B6"
  background: "#2D353B"
  border: "#7FBBB3"
  # See config reference for all options

Complete reference: See the config file reference for all color options.

Notifications

Get notified when long-running executables complete:

# Enable desktop notifications
flow config set notifications true

# Enable notification sound
flow config set notifications true --sound

# Disable notifications
flow config set notifications false

Mouse Support

Mouse support is on by default. Turn it off to select text without holding Shift:

flow config set mouse false

Log Display

Control how command output is displayed:

# Set global log mode
flow config set log-mode logfmt    # Structured logs (default)
flow config set log-mode text      # Plain text output
flow config set log-mode json      # JSON format
flow config set log-mode hidden    # Hide output

Per-executable log modes:

executables:
  - name: debug-task
    exec:
      logMode: text  # Override global setting
      cmd: echo "Debug output"

Workspace Modes

Control how flow determines your current workspace:

# Dynamic mode - auto-switch based on directory
flow config set workspace-mode dynamic

# Fixed mode - always use set workspace
flow config set workspace-mode fixed

Learn more: See the Workspaces guide for detailed workspace mode explanations.

Timeouts

Set default timeout for all executables:

# Set global timeout
flow config set timeout 45m

# Examples: 30s, 5m, 2h
flow config set timeout 10m

Configuration Management

View Current Settings

# View all settings
flow config get

# View specific setting
flow config get --output json | jq '.theme'

Reset to Defaults

# Reset all configuration
flow config reset

# Warning: This overwrites all customizations

Configuration File Location

Your config is stored in:

• Linux: ~/.config/flow/config.yaml
• macOS: ~/Library/Application Support/flow/config.yaml