i2ptui

README

i2ptui

Embeddable TUI and freestanding CLI for monitoring and managing an I2P router via I2PControl-RPC. Built with Bubble Tea and go-i2p/go-i2pcontrol.

Features

• Dashboard — live view of router status, bandwidth, known peers, participating tunnels, and uptime
• Stats — detailed bandwidth rates, tunnel build success/reject/expire percentages, and build request times
• Peers — peer count overview with reseeding and net-status indicators
• Control — restart, graceful restart, shutdown, graceful shutdown, and update checks with confirmation prompts
• Settings — edit bandwidth limits and share percentage via I2PControl with confirmation dialog and restart-required indicator
• Live Graphs — Unicode sparklines for bandwidth, tunnels, and peer count; horizontal bar chart for build success rates; toggle with g
• Notifications — in-TUI notification bar for status changes with optional desktop notifications (notify-send / osascript)
• Theming — built-in dark and light color themes selectable via --theme flag or config file
• Mouse support — click tabs to switch; works alongside keyboard navigation
• Persistent config — defaults stored in ~/.config/i2ptui/config.json
• Embeddable — the root tea.Model is exported so other Go programs can host the TUI inside their own Bubble Tea application
• Single binary — go build ./cmd/i2ptui produces a static binary with no runtime dependencies beyond a reachable I2PControl port

Install

go install github.com/go-i2p/i2ptui/cmd/i2ptui@latest

Usage

i2ptui [flags]
i2ptui [command]

Commands

Command	Description
completion	Generate shell completion scripts (bash, zsh, fish, powershell)
version	Print the build version
help	Help about any command

Flags

Flag	Default	Description
--host	127.0.0.1	I2PControl host
--port	7657	I2PControl port
--path	jsonrpc	RPC URL path
--password	itoopie	I2PControl API password
--cert		Path to self-signed cert (enables TLS skip-verify)
--interval	5s	Polling interval
--theme	dark	Color theme (dark, light)

Shell Completions

# Bash
i2ptui completion bash > /etc/bash_completion.d/i2ptui

# Zsh
i2ptui completion zsh > "${fpath[1]}/_i2ptui"

# Fish
i2ptui completion fish > ~/.config/fish/completions/i2ptui.fish

Embedding

package main

import (
    "github.com/go-i2p/i2ptui"
    tea "github.com/charmbracelet/bubbletea"
)

func main() {
    m := i2ptui.New(
        i2ptui.WithHost("127.0.0.1"),
        i2ptui.WithPort("7657"),
        i2ptui.WithPassword("itoopie"),
    )
    p := tea.NewProgram(m, tea.WithAltScreen(), tea.WithMouseCellMotion())
    p.Run()
}

Key Bindings

Key	Action
Tab / Shift+Tab	Cycle tabs
1 2 3 4 5	Jump to Dashboard, Stats, Peers, Control, Settings
↑/k ↓/j	Navigate
Enter	Activate
Esc	Cancel / dismiss
g	Toggle graph panel
r	Force refresh
q / Ctrl+C	Quit

License

MIT

Documentation

Overview

Package i2ptui provides an embeddable Bubble Tea TUI for monitoring and managing an I2P router via the I2PControl JSON-RPC interface.

Index

• Variables
• func DefaultConfigPath() string
• func SaveConfig(path string, cfg Config) error
• type Config
  • func LoadConfig(path string) Config
• type Model
  • func New(opts ...Option) Model
  • func (m Model) Init() tea.Cmd
  • func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m Model) View() string
• type Option
  • func WithCert(c string) Option
  • func WithHost(h string) Option
  • func WithInterval(d time.Duration) Option
  • func WithPassword(p string) Option
  • func WithPath(p string) Option
  • func WithPort(p string) Option
  • func WithTheme(t Theme) Option
• type Theme

Variables

var DarkTheme = Theme{
	ActiveTab:   lipgloss.Color("205"),
	InactiveTab: lipgloss.Color("240"),
	Header:      lipgloss.Color("240"),
	Label:       lipgloss.Color("252"),
	Value:       lipgloss.Color("86"),
	Section:     lipgloss.Color("99"),
	Error:       lipgloss.Color("196"),
	Status:      lipgloss.Color("220"),
	Footer:      lipgloss.Color("240"),
	Selected:    lipgloss.Color("205"),
	ConfirmBdr:  lipgloss.Color("205"),
	Notify:      lipgloss.Color("228"),
	Restart:     lipgloss.Color("214"),
}

DarkTheme is the default dark color scheme.

var LightTheme = Theme{
	ActiveTab:   lipgloss.Color("127"),
	InactiveTab: lipgloss.Color("245"),
	Header:      lipgloss.Color("245"),
	Label:       lipgloss.Color("238"),
	Value:       lipgloss.Color("28"),
	Section:     lipgloss.Color("63"),
	Error:       lipgloss.Color("160"),
	Status:      lipgloss.Color("172"),
	Footer:      lipgloss.Color("245"),
	Selected:    lipgloss.Color("127"),
	ConfirmBdr:  lipgloss.Color("127"),
	Notify:      lipgloss.Color("136"),
	Restart:     lipgloss.Color("166"),
}

LightTheme is a lighter color scheme for light terminals.

Functions

func DefaultConfigPath

func DefaultConfigPath() string

DefaultConfigPath returns the default path for the config file.

func SaveConfig

func SaveConfig(path string, cfg Config) error

SaveConfig writes the config to disk, creating directories as needed.

Types

type Config

type Config struct {
	Host     string `json:"host,omitempty"`
	Port     string `json:"port,omitempty"`
	Path     string `json:"path,omitempty"`
	Password string `json:"password,omitempty"`
	Cert     string `json:"cert,omitempty"`
	Interval string `json:"interval,omitempty"`
	Theme    string `json:"theme,omitempty"`
}

Config represents the persistent configuration file.

func LoadConfig

func LoadConfig(path string) Config

LoadConfig reads and parses the config file. Returns zero Config on error.

type Model

type Model struct {
	// contains filtered or unexported fields
}

Model is the root Bubble Tea model for i2ptui.

func New

func New(opts ...Option) Model

New creates a new Model with the given options.

func (Model) Init

func (m Model) Init() tea.Cmd

Init implements tea.Model and starts background polling.

func (Model) Update

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update implements tea.Model and dispatches incoming messages.

func (Model) View

func (m Model) View() string

View implements tea.Model and composes the full layout.

type Option

type Option func(*Model)

Option configures a Model before it starts.

func WithCert

func WithCert(c string) Option

WithCert sets the path to a self-signed certificate.

func WithHost

func WithHost(h string) Option

WithHost sets the I2PControl host address to connect to.

func WithInterval

func WithInterval(d time.Duration) Option

WithInterval sets the polling interval between snapshot fetches.

func WithPassword

func WithPassword(p string) Option

WithPassword sets the I2PControl API password.

func WithPath

func WithPath(p string) Option

WithPath sets the RPC URL path.

func WithPort

func WithPort(p string) Option

WithPort sets the I2PControl port number to connect to.

func WithTheme

func WithTheme(t Theme) Option

WithTheme sets the color theme used for rendering.

type Theme

type Theme struct {
	ActiveTab   lipgloss.Color
	InactiveTab lipgloss.Color
	Header      lipgloss.Color
	Label       lipgloss.Color
	Value       lipgloss.Color
	Section     lipgloss.Color
	Error       lipgloss.Color
	Status      lipgloss.Color
	Footer      lipgloss.Color
	Selected    lipgloss.Color
	ConfirmBdr  lipgloss.Color
	Notify      lipgloss.Color
	Restart     lipgloss.Color
}

Theme defines the color scheme for the TUI.