@spec explore(keyword()) :: :ok | {:error, term()}

Launches the PhoenixGenApi TUI explorer with options.

Loads all PhoenixGenApi runtime config data via PhoenixGenApiTui.Introspection, then starts an interactive terminal interface.

Options

• :transport — :local (default), :ssh, or :distributed.
• :force_refresh — bypass cache and fetch fresh data on start (default false).
• :remote_node — query PhoenixGenApi data from a remote node via RPC.
• :timeout — RPC timeout in milliseconds (default 10_000).

Local options

Any extra options are forwarded to PhoenixGenApiTui.App (e.g. test_mode: {80, 24}, name: nil).

SSH options

When transport: :ssh, these options configure the SSH daemon:

• :port — TCP port (default 4546).
• :auto_host_key — generate a host key automatically (default true).
• :auth_methods — e.g. ~c"password" (default).
• :user_passwords — e.g. [{~c"phoenix", ~c"tui"}] (default).

Any other keyword is forwarded to :ssh.daemon/2. See the ExRatatui SSH guide for the full option reference.

Distributed options

When transport: :distributed, the function starts a listener that remote nodes attach to via ExRatatui.Distributed.attach/3:

ExRatatui.Distributed.attach(:"app@hostname", PhoenixGenApiTui.App)

See the ExRatatui Distribution guide for details.

Examples

# Local (default)
PhoenixGenApiTui.explore()

# SSH with defaults (port 4546, phoenix:tui password)
PhoenixGenApiTui.explore(transport: :ssh)

# SSH with custom port and credentials
PhoenixGenApiTui.explore(
  transport: :ssh,
  port: 4000,
  user_passwords: [{~c"admin", ~c"secret"}]
)

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

# Query remote node
PhoenixGenApiTui.explore(remote_node: :"app@remote-host")

# Force fresh data load
PhoenixGenApiTui.explore(force_refresh: true)

@spec run(keyword()) :: {:ok, pid()} | {:error, term()}

Starts the PhoenixGenApi TUI explorer in a background process.

Unlike ui/1, this function returns immediately with the PID of the TUI process, keeping the calling process (IEx) responsive.

The TUI runs in a separate process and takes over the terminal. Press q in the TUI to stop it, or call stop/1 with the PID.

Options

Same as ui/1.

Examples

iex> {:ok, pid} = PhoenixGenApiTui.run()
iex> PhoenixGenApiTui.stop(pid)

@spec ssh_defaults(keyword()) :: keyword()

Applies default SSH options to the given keyword list.

Defaults (all overridable via opts):

• :port — 4546
• :auto_host_key — true
• :auth_methods — ~c"password"
• :user_passwords — [{~c"phoenix", ~c"tui"}]

@spec stop(pid()) :: :ok

Stops a running TUI process started with run/1.

Examples

iex> {:ok, pid} = PhoenixGenApiTui.run()
iex> PhoenixGenApiTui.stop(pid)
:ok

@spec ui(keyword()) :: :ok | {:error, term()}

Launches the PhoenixGenApi TUI explorer in the local terminal.

This is the primary entry point for interactive use from IEx. Reads runtime configuration from the connected PhoenixGenApi application.

Note: This function blocks the calling process (IEx) until the TUI exits. The TUI takes over the terminal. Press q to quit and return to IEx.

Options

• :remote_node — query PhoenixGenApi data from a remote node via RPC.
• :timeout — RPC timeout in milliseconds (default 10_000).

Examples

iex> PhoenixGenApiTui.ui()
iex> PhoenixGenApiTui.ui(remote_node: :"app@remote-host")
iex> PhoenixGenApiTui.ui(remote_node: :"app@remote-host", timeout: 5_000)

Non-blocking usage

To run the TUI in a background process (keeping IEx responsive), use run/1 instead:

iex> {:ok, pid} = PhoenixGenApiTui.run()
iex> # TUI is running in background, IEx is still usable
iex> # Press `q` in the TUI terminal to stop it