Skip to main content

README.md 

# 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:

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

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

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

## Usage

### From IEx (recommended)

Start your application and open IEx:

```bash
iex -S mix
```

Then launch the TUI:

```elixir
iex> PhoenixGenApiTui.ui()
```

### Inspect a remote node

Query PhoenixGenApi data from a remote node via RPC:

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

### Programmatic usage

```elixir
# 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:

```elixir
iex> PhoenixGenApiTui.ui()
```

### SSH

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

```elixir
iex> PhoenixGenApiTui.explore(transport: :ssh)
```

Then connect from another terminal:

```bash
ssh phoenix@localhost -p 4546
# password: tui
```

Custom port and credentials:

```elixir
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:

```bash
# 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

| Key | Action |
| --- | --- |
| `j` / `↓` | Move selection down |
| `k` / `↑` | Move selection up |
| `h` / `←` | Focus navigation panel |
| `l` / `→` | Focus detail panel |
| `Enter` | Select / drill into item |
| `Esc` | Go back / close overlay |
| `Tab` | Cycle through tabs |
| `1`-`6` | Select tab directly |
| `/` | Start search (fuzzy matching) |
| `r` | Refresh data |
| `?` | Toggle help |
| `q` | Quit |

## Guides

- [Getting Started](guides/getting_started.md)
- [Keyboard Reference](guides/keyboard_reference.md)
- [Transports](guides/transports.md)
- [Tab Reference](guides/tabs.md)

## 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.