guides/getting_started.md

Select File
guides/getting_started.md

# Getting Started with PhoenixGenApiTui

PhoenixGenApiTui is a terminal-based interactive explorer for PhoenixGenApi applications. Navigate your services, function configs, call flows, cluster topology, rate limits, and runtime health — without leaving the terminal.

## Installation

Add `phoenix_gen_api_tui` to your dependencies:

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

For development-only exploration, restrict to `:dev`:

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

## Quick Start

Start your application and open IEx:

```bash
iex -S mix
```

Then launch the TUI:

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

## 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   │
╰────────────────────────────────────────────────────────────────────────╯
```

## How It Works

PhoenixGenApiTui reads runtime configuration from your running PhoenixGenApi application:

```
iex> PhoenixGenApiTui.ui()
  → PhoenixGenApiTui.Introspection.load()
  → PhoenixGenApi.ConfigDb.get_all_functions()
  → PhoenixGenApi.Diagnostics.list_call_flows()
  → PhoenixGenApi.Diagnostics.cluster_view()
  → PhoenixGenApi.Diagnostics.health_check()
  → PhoenixGenApi.Diagnostics.statistics()
  → PhoenixGenApi.RateLimiter.get_configured_limits()
  → Pre-loaded into navigable state struct
  → ExRatatui.App renders it (local, SSH, or distributed)
```

No database connection is needed. The tool reads the *shape* of your running system, not its data.

## Data Caching

The explorer caches introspection data with a 30-second TTL to avoid excessive RPC calls. Press `r` at any time to force a refresh. The header shows a status indicator:

- `●` — All subsystems loaded successfully
- `⚠` — Some subsystems unavailable (partial data)
- `○` — Connection error

## See Also

- [Keyboard Reference](keyboard_reference.md) — all keybindings
- [Transports](transports.md) — SSH and distributed mode
- [Tab Reference](tabs.md) — what each tab shows