jujumate 0.4.0

Terminal UI for Juju infrastructure orchestration

⬢ JujuMate

A terminal UI for Juju — monitor all your infrastructure resources in a single interactive screen with real-time updates. Inspired by K9s and KDash.

---

Features

• 🔄 Auto-refresh — status updates automatically every few seconds; logs stream live via WebSocket
• 🧭 Navigator — unified Cloud → Controller → Model navigation in a single tab with cascade filtering and a detail strip showing key fields of the current selection
• 📊 Status view — apps, units, offers, integrations, SAAS, machines and storage in one screen
• 🏥 Health view — shows only unhealthy models by default; toggle to see all with f
• 💾 Storage panel — storage volumes, pools and sizes; toggle detached storage with d; press Enter to see device info and mountpoints
• 🔍 Drill-down navigation — select a cloud → filter controllers → filter models → see full status. Enter auto-advances to the next selector
• 🔎 Inline filtering — press / in Status or Logs to search with live highlight
• 🔗 Peer relation toggle — press p to show/hide peer relations in the Integrations panel
• 🖥️ Units-per-machine toggle — press u to show units (and their subordinates) nested under each machine
• 💾 Storage view — storage instances per model with pool, size and attachment status; press d to toggle detached entries; press Enter to open a full detail modal (mountpoint, read-only, device info, lifecycle)
• 🗂️ Collapsible panels — press x to collapse/expand any Status panel individually; focused panel highlighted in theme colour
• 👑 Leader indicators — unit leaders marked with * (green) following juju status convention
• 🔗 Relation lifecycle — Integrations panel shows live relation status; relations being torn down display as removing
• 📋 Copy to clipboard — press y in Status or Relation Data to copy the full content
• 🔐 Secrets browser — list and inspect Juju secrets per model (Shift+S)
• 📦 Offers browser — browse all cross-model offers in a controller, with endpoint details and live consumer tracking across controllers (Shift+O)
• 📋 Relation databag inspector — examine raw relation data for any relation (Enter on a relation)
• ⚙️ App config viewer — inspect application configuration (Enter on an app)
• 🖥️ Machine detail modal — press Enter on any machine to see hardware specs, status timestamps and network interfaces
• 🎨 Themeable — five built-in themes; fully customisable via YAML
• ⚙️ Settings modal — change theme, refresh interval, default controller and log level at runtime (Shift+C)
• 🪟 Terminal transparency — respects your terminal background (no forced black background)
• ⌨️ K9s-style help overlay — press ? to see all keybindings at any time (full-screen)

---

Installation

Recommended — install as a tool with uv:

uv tool install jujumate

Or with pipx:

pipx install jujumate

JujuMate reads your existing Juju configuration from ~/.local/share/juju/ automatically — no extra setup needed if juju is already working.

---

Quick Start

jujumate

On first launch JujuMate connects to your current Juju controller and auto-selects your current model. Use the keyboard shortcuts below to navigate.

---

Keyboard Shortcuts

Global

Key	Action
n	Go to Navigator tab (Clouds → Controllers → Models)
s	Go to Status tab
h	Go to Health tab
r	Force refresh
Esc	Clear drill-down filter
?	Toggle help overlay
q	Quit

Navigator tab

Key	Action
↑ / ↓	Move cursor within the active selector
Enter	Select the highlighted item and advance focus to the next selector
Tab / Shift+Tab	Move focus between Cloud, Controller and Model selectors

Status tab

Key	Action
/	Filter by app name, charm, channel or message (with live highlight)
Esc	Clear filter
d	Toggle detached storage visibility in the Storage panel
p	Toggle peer relations in the Integrations panel
u	Toggle units (and subordinates) nested under each machine
d	Toggle detached entries in the Storage panel
x	Collapse/expand the current panel
y	Copy full status to clipboard (includes cloud, controller, model and Juju version)
Enter on app	Open App Config viewer
Enter on offer	Open Offer detail
Enter on relation	Open Relation Data inspector
Enter on machine	Open Machine detail modal (hardware, status, network)
Enter on storage	Open Storage detail modal (mountpoint, device, lifecycle)

Health tab

Key	Action
f	Toggle between unhealthy-only (default) and all models

Modals

Key	Action
Shift+S	Open Secrets browser for the current model
Shift+O	Open Offers browser for the current controller
Shift+L	Open live Log viewer for the current model
Shift+C	Open Settings modal (appearance, behaviour, diagnostics)
Enter	Open detail view
y	Copy value to clipboard (Relation Data / Secrets)
Esc	Close modal

---

Views

Navigator

The entry point for navigating your Juju estate. A single tab replaces the old Clouds / Controllers / Models tabs with a three-column cascade layout:

• Selector strip — three compact tables side-by-side: Clouds (Name, Type), Controllers (Controller, Models) and Models (Model, Machines, Apps). Use ↑/↓ to move the cursor, Enter to select and auto-advance, and Tab/Shift+Tab to switch focus between selectors.
• Detail strip — a horizontal panel above the selectors that shows the key fields of the currently selected cloud, controller and model. Updates as you navigate.
• Cascade filtering — selecting a cloud filters controllers to that cloud; selecting a controller filters models to that controller. Changing a cloud resets the controllers and models below it.

Status

The main view. Displays a full juju status-style breakdown of the selected model:

• Applications — name, charm, channel, revision, units, status and workload message
• Units — workload/agent status, machine or pod, address, ports; subordinates shown nested under their principal; leader units are marked with *
• Machines — id, state, address, instance, base, AZ (IaaS models only); press u to expand units and their subordinates inline; press Enter on a machine to open its detail modal
• Storage — storage instances with pool, size and mountpoint; toggle detached storage with d; press Enter on a storage entry to see device details

Press Enter on a machine to see:

• Hardware — architecture, CPU cores, memory, root disk size, virtualisation type
• Status — agent and instance status with relative timestamps (e.g. 2h ago)
• Network interfaces — name, IP address, MAC address and Juju space for each NIC
• SAAS — consumed remote offers and their status
• Offers — cross-model offers with active/total connection counts
• Integrations — regular and cross-model relations with live status column (peer relations hidden by default; press p to toggle); relations being removed show as removing
• Storage — storage instances with pool, size and attachment status; attached entries shown in green, detached in orange; press d to toggle detached entries; press Enter to open a full detail modal

Each panel can be collapsed individually with x while it has focus, and expanded again with x. The focused panel is highlighted with a distinct border colour (violet in Monokai and Ubuntu themes).

Health

Shows a summary of all models across all controllers, highlighting those with errors or blocked units. Unhealthy models are shown by default; press f to toggle between unhealthy-only and all models.

Offers browser (Shift+O)

Lists all offers across every model in the current controller. Select an offer to see:

• Model, URL, application, charm, description and access level
• Endpoint details (name, interface, role)
• Live consumer list — scans all known controllers to find which models and applications are consuming the offer

Secrets browser (Shift+S)

Lists all secrets visible in the current model. Select a secret to see its metadata (owner, revision, rotation policy, timestamps).

Log viewer (Shift+L)

Streams live log entries from the current model. Use / to filter by text.

Relation Data inspector

Press Enter on any relation in the Status tab to open a databag viewer showing the application-level and unit-level relation data for both sides of the relation. Press y to copy the full content to clipboard.

App Config viewer

Press Enter on any application in the Status tab to inspect its current configuration values.

Machine detail modal

Press Enter on any machine row in the Machines panel to open a modal showing:

• Instance ID, address, base OS, availability zone, controller and model
• Hardware — architecture, CPU cores, memory, root disk size and virtualisation type (parsed from Juju's hardware string)
• Status — agent and instance status with relative timestamps (e.g. started 2h ago)
• Network interfaces — name, IP address, MAC address and Juju space for each NIC

Section titles adapt to the active theme's accent colour. Press Esc to close.

Storage detail modal

Press Enter on any storage row in the Storage panel to open a modal showing:

• Unit, Storage ID, Type, Pool, Size and Status
• Attachment — Mountpoint inside the container or VM; Read Only flag; Device name and Device Link for IaaS block storage (e.g. /dev/sdb, /dev/disk/by-id/...)
• Lifecycle — Persistent flag and Life value (alive in green, dying in orange, dead in red)

Press Esc to close.

---

Configuration

JujuMate is configured via ~/.config/jujumate/config.yaml. All fields are optional.

# ~/.config/jujumate/config.yaml

theme: ubuntu               # Theme name (default: ubuntu)
refresh_interval: 5         # Seconds between auto-refresh (default: 5)
offers_cache_ttl: 300       # Seconds to cache the offers list (default: 300)
default_controller: prod    # Controller to use (default: current Juju controller)
log_file: ~/.local/state/jujumate/jujumate.log
log_level: INFO             # DEBUG | INFO | WARNING | ERROR | CRITICAL

Most settings can also be changed at runtime — press Shift+C to open the Settings modal, which lets you change the theme (with live preview), refresh interval, default controller and log level without editing the file manually. Changes are saved immediately.

offers_cache_ttl is a config-file-only setting (not exposed in the Settings modal). It controls how long the Offers list is cached between modal opens. Press r inside the Offers modal to force an immediate refresh.

---

Themes

JujuMate ships with five built-in themes: ubuntu (default), dark, monokai, solarized-dark and spacemacs.

Press Shift+C to open the Settings modal, then select a theme in the Appearance section to preview it live before it's applied.

To create a custom theme, add a YAML file to ~/.config/jujumate/themes/:

# ~/.config/jujumate/themes/mytheme.yaml
name: mytheme
primary: "#FF6600"
secondary: "#003366"
background: "#1a1a2e"
surface: "#16213e"
dark: true

Then set it in your config:

theme: mytheme

Available fields: primary, secondary, accent, background, surface, panel, warning, error, success, foreground, dark.

User themes override built-in themes with the same name.

---

Development

Requirements: Python 3.10+, uv

git clone https://github.com/Abuelodelanada/jujumate.git
cd jujumate
uv sync

Run from source:

uv run jujumate

Run checks (lint + typecheck + tests):

uv run nox

Individual sessions:

uv run nox -s tests       # Run tests with coverage
uv run nox -s lint        # Ruff lint + format check
uv run nox -s typecheck   # Pyright static analysis
uv run ruff format src tests  # Auto-format code

---

License

GNU General Public License v3.0