Skip to main content

hop3-tui

Terminal User Interface for Hop3 PaaS.

Overview

A modern, keyboard-driven terminal interface for managing Hop3 applications, built with turbodesk.

Features

  • Dashboard overview: System stats, app summary, recent activity
  • Application management: List, filter, start/stop/restart apps
  • Environment variables: View, add, edit, delete with sensitive value hiding
  • Live log polling: Filter logs, pause/resume, auto-scroll
  • Chat interface: Interactive command line with tab completion
  • System monitoring: CPU, memory, disk usage and service status
  • Addon management: Create, attach, detach PostgreSQL, Redis, MySQL
  • Backup management: Create, restore, delete app backups
  • Connection status indicator: Visual feedback for server connectivity

Installation

pip install hop3-tui

Quick Start

# Set your server URL
export HOP3_SERVER_URL="https://hop3.example.com"
export HOP3_TOKEN="your-api-token"

# Run the TUI
hop3-tui

Configuration

Configuration via environment variables or ~/.config/hop3/tui.toml:

Variable Description Default
HOP3_SERVER_URL Server URL http://localhost:5000
HOP3_TOKEN API authentication token -
HOP3_TUI_THEME Color theme (dark/light) dark

Config File

[server]
url = "https://hop3.example.com"
token = "your-api-token"

[display]
theme = "dark"
refresh_interval = 5

Keyboard Shortcuts

Global

Key Action
d Dashboard
a Apps list
s System status
o Addons
b Backups
c Chat interface
? Help
q Quit

Navigation

Key Action
j/Down Move down
k/Up Move up
Enter Select
Escape Go back
/ Filter
R Refresh

Apps

Key Action
s Start app
S Stop app
r Restart app
l View logs
e Environment variables

Architecture

hop3-tui/
├── src/hop3_tui/
│   ├── __main__.py       # Entry point
│   ├── app.py            # Main Hop3TUI class with connection state
│   ├── config.py         # Configuration loading (env vars + TOML)
│   ├── api/
│   │   ├── client.py     # JSON-RPC client with error handling
│   │   └── models.py     # Pydantic data models
│   ├── screens/          # One `render(ui, hop3, size, ...) -> View` per screen
│   │   ├── _common.py    # bind(), halves(), rows(), fill() — what CSS used to do
│   │   ├── _logview.py   # The pane behind both logs.py and system_logs.py
│   │   ├── dashboard.py  # Overview with app counts
│   │   ├── apps.py       # App list and management
│   │   ├── app_detail.py # Single app view
│   │   ├── logs.py       # Live log polling
│   │   ├── env_vars.py   # Environment variable editor
│   │   ├── system.py     # System status
│   │   ├── addons.py     # Addon management
│   │   ├── backups.py    # Backup management
│   │   ├── processes.py  # Running processes
│   │   ├── system_logs.py# System-wide logs
│   │   └── chat.py       # Command interface
│   └── widgets/
│       ├── chrome.py        # Header, footer, panel frames
│       ├── status_panel.py  # Resource meters
│       ├── status_badge.py  # Status indicators
│       └── util.py          # Bar gauges, and the "not reported" marker
└── tests/                # pytest test suite (235 tests)

Immediate mode

There is no widget tree. The app is a function (UI) -> View that turbodesk re-runs whenever a frame is marked dirty, and a screen is a function of its arguments — so there is no compose(), no reactive/watch_*, no query_one, and no stylesheet. Layout is arithmetic (halves, rows), and state lives in ui.state hooks matched between frames by call order. Each screen renders inside its own ui.scope, which is what keeps those slots from being handed to the next screen on a switch.

Rendering has no side effect on the screen, so a test calls the app function at any size and asserts on what came out — no pilot, no event loop, no async harness:

to_text(render(app(hop3), size=Size(90, 26)))

Nothing is invented

A panel shows what the server reported or says that it does not know (not reported by the server); it never shows a plausible-looking constant. The log pane's heading drops from LIVE to UNREACHABLE when a poll fails, rather than going on looking live over a dead connection. tests/test_no_fabricated_data.py holds that line.

Connection Handling

The TUI tracks connection state to the Hop3 server:

  • Connected (green indicator): Server is reachable
  • Disconnected (red indicator): Connection lost, will retry
  • Connecting (yellow indicator): Attempting to connect

Connection failures are tracked and the state updates automatically. The UI continues to show cached data while disconnected.

Development

# Run it
uv run hop3-tui

# Run tests (from the workspace root)
uv run pytest packages/hop3-tui/tests

# Lint and format
uv run ruff check src/
uv run ruff format src/

Documentation

  • hop3-server - The server that hop3-tui communicates with
  • hop3-cli - Alternative command-line interface

License

Apache-2.0 - Copyright (c) 2024-2026, Abilian SAS

Metadata

Release files for hop3-tui 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hop3-tui 0.8.1
File Size Uploaded Provenance Actions
hop3_tui-0.8.1.tar.gz 32.8 kB Without provenance Details for hop3_tui-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hop3-tui 0.8.1
File Interpreter ABI Platform Actions
hop3_tui-0.8.1-py3-none-any.whl Python 3 none any Details for hop3_tui-0.8.1-py3-none-any.whl

Total release size: 83.1 kB

Release files / hop3_tui-0.8.1.tar.gz

Download URL hop3_tui-0.8.1.tar.gz
Size 32.8 kB
Tags Source
SHA-256 checksum
How to use checksums
bd2d119e8a9c46ab5f4f24553cb461a3b63cf1ce085a177cd295006b356ba996
BLAKE2b-256 checksum
How to use checksums
26d360d7cb7cc872e7fc252f47b8be56a98b18caf05af07620a719a5161bdc0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / hop3_tui-0.8.1-py3-none-any.whl

Download URL hop3_tui-0.8.1-py3-none-any.whl
Size 50.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b40bdaa21e3898113eb7df222c07c808703e65990c234af383e25e0a8330649a
BLAKE2b-256 checksum
How to use checksums
16c7edd151cb0cc059b0290bfe5d06352165f6ed8022a66187a5b982d37e8e21
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for hop3-tui 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page