---
title: Interactive TUI Guide
description: >-
  Master the ivybloom terminal user interface for conversational drug discovery
  workflows.
tags:
  - tui
  - terminal-ui
  - dashboard
  - interactive
  - keyboard-shortcuts
---

The TUI is the CLI's interactive face — a terminal dashboard that combines AI chat, real-time job monitoring, and result visualization for drug discovery workflows. Reach for it when you want a conversational, keyboard-driven session rather than one-off scripted commands, all without leaving your terminal. It runs against the same backend and job history as the rest of the CLI and the web platform, so your sessions and jobs stay in sync. For the full command set, see the [CLI overview](/docs/cli).

  beginner

## Interactive TUI Guide

The ivybloom TUI provides a conversational interface for drug discovery workflows, combining AI chat with real-time job monitoring and result visualization.

---

## Launching the TUI

```bash
ivybloom
```

You'll see a splash screen with a command prompt. Type a message or use `/` commands to navigate.

---

## Interface Layout

The TUI has four main areas:

```
+------------------+------------------------+------------------+
| Session Sidebar  |    Conversation        |  Context Panel   |
| (Ctrl+S toggle)  |                        |  (Tab toggle)    |
|                  |                        |                  |
| - Sessions list  |  [Assistant response]  |  Files           |
| - Archive/fork   |  [Your message]        |  Jobs            |
|                  |  [Tool progress]       |  Artifacts       |
|                  |                        |  Tool Calls      |
+------------------+------------------------+------------------+
| Input Area                                                   |
| > Type your message here...                    [Model: ...]  |
+--------------------------------------------------------------+
| Status: Connected | Synced | Streaming...                    |
+--------------------------------------------------------------+
```

---

## Keyboard Shortcuts

### Input and Navigation

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Shift+Enter` | New line in message |
| `Up Arrow` (empty input) | Previous message / focus context panel |
| `Down Arrow` | Scroll conversation down |
| `PgUp` / `PgDn` | Scroll conversation |
| `Home` / `End` | Jump to start/end of conversation |
| `Ctrl+U` | Clear input |

### Panels and Overlays

| Key | Action |
|-----|--------|
| `Tab` | Toggle context panel (right sidebar) |
| `Ctrl+S` | Toggle session sidebar (left) |
| `Ctrl+P` | Open command palette |
| `Ctrl+L` | Clear conversation |
| `?` | Show help overlay |
| `Esc` | Close overlay / stop streaming / back |
| `Ctrl+C` | Force quit |

### Triggers

| Key | Action |
|-----|--------|
| `/` | Show command suggestions (inline) |
| `@` | Open file picker |
| `!` | Show actions modal (available tools) |

---

## Command Palette

Press `Ctrl+P` or type `/` to access the built-in commands organized by category. Additional tool-specific and context-aware commands appear dynamically based on your session state.

### Session Commands

| Command | Description |
|---------|-------------|
| `/new` | Start a new chat session |
| `/clear` | Clear current conversation |
| `/sessions` | Open sessions manager |
| `/rename` | Rename current session |
| `/fork` | Create a branch of current session |
| `/archive` | Archive current session |
| `/export` | Export conversation to file |

### Navigation Commands

| Command | Description |
|---------|-------------|
| `/home` | Go to home screen |
| `/dashboard` | Open dashboard overview |
| `/jobs` | Open jobs hub |
| `/tools` | Browse available tools |
| `/artifacts` | View generated artifacts |
| `/settings` | Open settings |

### Job Commands

| Command | Description |
|---------|-------------|
| `/jobs` | View all jobs |
| `/jobhistory` | View job history |
| `/batch` | Manage batch jobs |
| `/jobdetails <id>` | View specific job details |

### Data Commands

| Command | Description |
|---------|-------------|
| `/data` | Manage data files |
| `/exports` | View exports |
| `/reports` | View generated reports |

### Settings Commands

| Command | Description |
|---------|-------------|
| `/appearance` | Customize theme and display |
| `/account` | View account info |
| `/apikeys` | Manage API keys |
| `/byok` | Configure bring-your-own-key |
| `/models` | Select AI model |

---

## Triggers and Mentions

### File Attachment (@)

Type `@` to open the file picker and attach files to your message:

```
> Analyze this protein structure @protein.pdb
```

The file picker shows:
- Project files
- Recent files
- Inbox (auto-discovered files)

Navigate with arrow keys, `Enter` to select, `Esc` to cancel.

### Actions (!)

Type `!` to see available tools and curated actions:

```
> !esmfold
```

The actions modal shows:
- Available computational tools
- Suggested actions based on context
- `.bloom` file suggestions

### Inline Commands (/)

Type `/` for inline command suggestions:

```
> /jobs
```

As you type, suggestions filter to match. Use arrow keys to navigate, `Enter` to execute, `Tab` to complete.

---

## Context Panel

Toggle with `Tab`. Shows real-time information about your session:

### Files Section
- Currently attached files
- Click to preview or remove

### Jobs Section
- Active jobs with live status
- Progress bars and phase indicators
- Click to view details

### Artifacts Section
- Generated outputs from completed jobs
- Click to view or download

### Tool Calls Section
- Currently executing tools
- Progress and status for each

---

## Tool Approval

Approval gates are not enabled. The TUI runs every tool call as soon as the orchestrator selects it, expensive operations and long-running jobs included, and no approval dialog appears.

---

## Real-Time Streaming

When the AI responds, you'll see:
- **Streaming text** with animated cursor
- **Tool progress cards** showing each tool's status
- **Live job updates** in the context panel

Press `Esc` to stop streaming.

### Connection Status

The status bar shows:
- **Connected** (green) - SSE connection active
- **Reconnecting** (yellow) - Attempting to reconnect
- **Offline** (red) - No connection

The TUI automatically reconnects with exponential backoff.

---

## Pages (Full-Screen Views)

Some commands open full-screen pages with tabbed interfaces:

### Jobs Hub (/jobs)

Tabs:
- **All Jobs** - Every job, with status filters, search and sorting
- **Sessions** - Recent chat sessions to resume
- **Batch** - Batch job queues and their progress
- **Tools** - Browse the tool catalog by category
- **Actions** - Tool actions from the current conversation

Navigation:
- `Tab` / `Shift+Tab` - Switch tabs
- `1`-`5` - Jump to a tab
- `j` / `k` or arrows - Navigate list
- `Enter` - Select / view details
- `Esc` - Return to chat

### Settings Hub (/settings)

Tabs:
- **Account** - Profile information
- **Display** - Theme and animations
- **Execution** - Execution settings
- **General** - Core preferences
- **LLM Keys** - Bring-your-own-key setup
- **Service Keys** - Manage API keys
- **Sessions** - Signed-in sessions

### Data Hub (/data)

Tabs:
- **Files** - Uploaded data files
- **Exports** - Generated exports
- **Reports** - Analysis reports
- **Artifacts** - Conversation artifacts such as code and images
- **Storage** - Workspace storage, when available

---

## Session Management

### Session Sidebar

Press `Ctrl+S` to toggle the session sidebar showing:
- All chat sessions
- Session names and timestamps
- Archive status

Click a session to switch to it.

### Session Actions

| Command | Action |
|---------|--------|
| `/new` | Create new session |
| `/rename` | Rename current session |
| `/fork` | Branch current session |
| `/archive` | Archive (hide) session |
| `/sync` | Sync with server |

---

## Conversation Flow

### Example: Protein Structure Prediction

```
You: Predict the structure for this sequence: MKLVFFAEDVGSNKGAIIGLMVGGVVIA

[Tool call: esmfold_predict]
  Status: Running...
  Progress: 45%

[Job completed]
  Artifact: structure.pdb (ready)

Assistant: Your protein structure prediction is complete\! The structure has been saved
as structure.pdb. I found a high-confidence fold with pLDDT score of 89.2.

Would you like me to analyze the structure or run molecular docking?
```

### Example: Multi-Step Workflow

```
You: I have a new drug candidate. Run ADMET prediction and check for toxicity.

[Tool call: admet_predict]
  Status: Complete
  Results: Good oral bioavailability, low toxicity risk

[Tool call: protox3_predict]
  Status: Running...
  Progress: 78%

Assistant: ADMET results look promising\! The compound shows:
- High intestinal absorption (94%)
- Low CYP inhibition risk
- Favorable LogP (2.3)

ProTox-3 analysis is still running for detailed toxicity profiling.
```

---

## Theming and Appearance

Customize the TUI appearance via `/appearance` or config file:

### Available Themes
- **default** - The standard theme
- **dark** - Dark background with light text
- **earth** - Earth-tone palette
- **acid** - High-contrast palette

### Settings File

Display settings live in `~/.config/ivybloom/ui_settings.json`:

```json
{
  "theme": "dark",
  "animation_style": "spinner",
  "spinner_style": "dots",
  "progress_style": "default",
  "status_icons": "default",
  "enable_animations": true,
  "enable_sounds": false,
  "refresh_rate": 250
}
```

Individual colors are not configurable; pick a theme instead.

---

## Visualization Features

The TUI includes rich visualizations for scientific data directly in your terminal.

### Biological Sequence Display

Color-coded amino acid and nucleotide sequences:
- **Hydrophobic** (green): A, V, L, I, M, F, W, P
- **Polar** (cyan): S, T, N, Q, C, G
- **Acidic** (red): D, E
- **Basic** (blue): K, R, H
- **Aromatic** (magenta): Y

BLAST results show conservation indicators (`*` conserved, `:` similar) with E-value and identity metrics.

### Molecule Property Cards

SMILES structures display with property grids:
```
+-- Molecule Properties ----------------------+
| SMILES: CCO                                 |
| MW: 46.07  |  LogP: -0.31  |  HBD: 1       |
| HBA: 1     |  RotB: 0      |  TPSA: 20.23  |
| Drug-like: Yes (Lipinski compliant)         |
+---------------------------------------------+
```

### Protein Structure Preview

PDB files render as ASCII structure diagrams with atom counts and chain information.

### Workflow Pipeline View

Multi-step workflows display as node graphs:
```
[ESMFold] ───▶ [DiffDock] ───▶ [ADMET]
    ●              ○              ○
 Complete      Running        Pending
```

### Dashboard Charts

The Jobs Hub (`/jobs`) shows:
- **Pie chart** - Job distribution by status
- **Sparklines** - Quick metric visualization using: `▁▂▃▄▅▆▇█`
- **Score bars** - Gradient color bars (red to green) for ratings

### Animation Types

Built-in animations for loading states include:
- **Spinner**: `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`
- **Pulse**: `█▉▊▋▌▍▎▏`
- **Wave**: `⠋⠙⠚⠞⠖⠦⠴⠲⠳⠓`
- **Progress**: `▁▃▄▅▆▇█`

### Artifact Viewer

View results directly in the terminal:
- **JSON** - Pretty-printed with syntax highlighting
- **CSV** - Tabular display with headers
- **FASTA** - Colored sequence blocks
- **PDB** - Structure summary with chain info

Access via context panel or `/artifacts` command.

---

## Agent Integration

The TUI integrates with the AI orchestration system to provide a conversational interface for tool execution.

### Tool Approval

When the orchestrator selects a tool, it runs without asking: approval gates are not enabled (see [Tool Approval](#tool-approval)).

### Streaming Responses

During orchestration, the TUI displays:
- **Streaming text** with animated cursor as the AI generates its response
- **Tool progress cards** showing each tool call's status, phase, and progress percentage
- **Live job updates** in the context panel via SSE (Server-Sent Events)

Press `Esc` at any time to stop streaming.

### Session Persistence

TUI sessions are automatically persisted and can be resumed:

```bash
# Resume last session
ivybloom -r last

# Resume a specific session
ivybloom --resume SESSION_ID
```

Sessions sync to the cloud when authenticated. See [Sessions & Checkpoints](/docs/cli/sessions) for checkpoint and rollback capabilities.

### Headless Mode

For single messages without launching the full TUI:

```bash
ivybloom -m "fold BRCA1"
ivybloom -m "dock erlotinib against EGFR" --follow
```

See [Orchestration](/docs/cli/orchestration) for the full AI routing documentation.

---

## Tips and Best Practices

### Efficient Navigation
- Use `Tab` to quickly check job status without leaving the conversation
- `Ctrl+P` is faster than typing `/` for frequent commands
- `Esc` is your universal \"go back\" key

### Working with Files
- Drop files in your project's `.ivybloom/inbox/` folder for auto-discovery
- Use `@` trigger for quick file attachment
- The context panel shows all attached files

### Monitoring Jobs
- Jobs appear in the context panel automatically
- Use `/jobs` for detailed view with filtering
- SSE provides instant updates (no polling delay)

### Keyboard-First Workflow
- Learn the trigger keys: `/` `@` `\!`
- Use `j`/`k` in list views (vim-style)
- `Tab` and `Shift+Tab` cycle through elements

---

## Troubleshooting

### TUI Not Launching

```bash
# Check authentication
ivybloom auth status

# Verify terminal capabilities
ivybloom doctor
```

### Connection Issues

The status bar shows connection state. If disconnected:
1. Check internet connection
2. Verify API key: `ivybloom auth status`
3. The TUI auto-reconnects; wait a few seconds

### Display Problems

Set `"enable_animations": false` in `~/.config/ivybloom/ui_settings.json`, or open `/appearance` in the TUI and pick a different theme.

---

## Read next

- [Sessions & Checkpoints](/docs/cli/sessions) — Persistent conversations and time-travel
- [Orchestration](/docs/cli/orchestration) — AI routing that powers TUI chat
- [Commands Reference](/docs/cli/commands) — Full command documentation
- [Job Management](/docs/cli/jobs) — Detailed job workflows
- [Configuration](/docs/cli/configuration) — Customize behavior and themes