PhoenixGenApiTui

Terminal-based interactive explorer for PhoenixGenApi applications, built on ExRatatui.

Navigate your services, function configs, call flows, cluster topology, rate limits, and runtime health — without leaving the terminal.

Features

• Two-panel navigable interface with service/function tree
• Six detail tabs: Functions, Call Flows, Cluster, Health, Stats, Rate Limits
• Function detail overlay — press Enter for full FunConfig details
• Fuzzy search/filter — press / to filter services
• Live data refresh — press r to reload from the running application
• Status indicators showing connection health
• Scrollbar indicators when lists overflow the viewport
• Vim keybindings (j/k/h/l) and arrow key support
• Tab switching with Tab or 1-6
• Help overlay
• No database connection needed — reads runtime metadata only
• Local transport — run directly in IEx with PhoenixGenApiTui.ui()
• SSH transport — serve the explorer to remote clients over SSH
• Erlang distribution transport — attach from a remote BEAM node

UI Layout

╭─ ● 🔥 PhoenixGenApi TUI Explorer  │  UserService ─────────────────────╮
╰────────────────────────────────────────────────────────────────────────╯
╭─ Search ─────────────╮ ╭─ user_service ───────────────────────────────╮
│ / search...          │ │ Functions │ Call Flows │ Cluster │ Health │.. │
╰──────────────────────╯ ╰──────────────────────────────────────────────╯
╭─ Navigation 2s · 3f ─╮ ╭──────────────────────────────────────────────╮
│ ▶ ◆ user_service (2)  │ │ Request Type  Version  Response  Nodes       │
│     ├ get_user        │ │ get_user      1.0.0     sync      [node1]   │
│     └ create_user     │ │ create_user   1.0.0     sync      [node1]   │
│   ◆ blog_service (1)  │ │                                              │
╰──────────────────────╯ ╰──────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────╯
│ j/k navigate  ⏎ select  h/l panels  Tab tabs  / search  r refresh  q   │
╰────────────────────────────────────────────────────────────────────────╯

Installation

Add phoenix_gen_api_tui to your dependencies:

def deps do
  [
    {:phoenix_gen_api_tui, "~> 0.1.0"}
  ]
end

Tip: For runtime inspection during development, add to :dev only:

{:phoenix_gen_api_tui, "~> 0.1.0", only: :dev}

Usage

From IEx (recommended)

Start your application and open IEx:

iex -S mix

Then launch the TUI:

iex> PhoenixGenApiTui.ui()

Inspect a remote node

Query PhoenixGenApi data from a remote node via RPC:

iex> PhoenixGenApiTui.ui(remote_node: :"app@remote-host")

Programmatic usage

# Local (default)
PhoenixGenApiTui.explore()

# SSH transport
PhoenixGenApiTui.explore(transport: :ssh)

# Distributed transport
PhoenixGenApiTui.explore(transport: :distributed)

Transports

Local (default)

Run directly in your IEx session:

iex> PhoenixGenApiTui.ui()

SSH

Serve the explorer over SSH. Multiple clients can connect simultaneously, each with an isolated session:

iex> PhoenixGenApiTui.explore(transport: :ssh)

Then connect from another terminal:

ssh phoenix@localhost -p 4546
# password: tui

Custom port and credentials:

PhoenixGenApiTui.explore(
  transport: :ssh,
  port: 4000,
  user_passwords: [{~c"admin", ~c"secret"}]
)

Erlang Distribution

Start a listener on the current node, then attach from a remote BEAM node:

# Terminal 1 — start the listener
iex --sname app --cookie demo -S mix
iex> PhoenixGenApiTui.explore(transport: :distributed)

# Terminal 2 — attach from another node
iex --sname local --cookie demo -S mix
iex> ExRatatui.Distributed.attach(:"app@hostname", PhoenixGenApiTui.App)

Keybindings

Guides

• Getting Started
• Keyboard Reference
• Transports
• Tab Reference

How It Works

PhoenixGenApiTui reads runtime configuration from your running PhoenixGenApi application via ConfigDb and Diagnostics. Data is cached with a 30-second TTL to avoid excessive RPC calls. Press r to force a refresh.

License

Copyright 2026 PhoenixGenApi

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.