feat(cli): add limactl-menu TUI plugin for instance management by Soumya-codr · Pull Request #5330 · lima-vm/lima

Soumya-codr · 2026-07-25T02:34:04Z

What This PR Changes

Implements #5285 - adds a limactl menu TUI plugin for managing Lima instances through an interactive terminal UI. The plugin provides:

Instance list with color-coded status (RUNNING/STOPPED/BROKEN), sorted Running first
Actions: Shell(F1), Start(F2), Stop(S), Restart(R), Delete(D), Protect/Unprotect, Ports(P), Copy SSH Config(C), Logs(L)
Info panel with full instance details (hostname, VM type, arch, CPUs, memory, disk, SSH port, protected state, errors, message)
Log viewer with journalctl -n 50 and follow toggle (L)
Confirmation modals for destructive actions (delete, stop, restart, unprotect)
Empty state modal with "Create Instance" button when no VMs exist
Status bar with live clock, instance position, SSH port, VM type/arch
Help bar with all keyboard shortcuts

Linked Issue (Required in most cases)

Closes #5285

How I Tested This

make limactl-plugins
_output/bin/limactl menu

AkihiroSuda · 2026-07-25T09:06:34Z

Thanks, but please sign the commit for DCO
https://github.com/apps/dco

(run git commit -a -s --amend, and make sure that the Signed-off-by: NAME <EMAIL> line with your real name is included in the commit message)

If you used an AI, you also have to disclose it

AkihiroSuda · 2026-07-25T09:08:01Z

The UI looks so redundant.
Can we just begin with a single-panel UI?
When an instance on the list is chosen, a pop-up menu will be shown for choosing an action.

Soumya-codr · 2026-07-25T12:50:54Z

The UI looks so redundant. Can we just begin with a single-panel UI? When an instance on the list is chosen, a pop-up menu will be shown for choosing an action.

Okay thanks for addressing that but i need more context from this , Do u want me to only chnage the whole thing to one panel like this

The single-panel design simplifies the UI but requires an extra click (Enter → select 'Show Info') to see instance details. For users managing multiple VMs, this adds friction vs the previous split view where info was visible alongside the list.

Could we consider a middle ground @AkihiroSuda :

Single panel with inline detail — when an instance is selected, show its key details (status, SSH port, IP) below the list in the same panel, then use popups only for actions?
Or a toggle — 'v' key switches between simple list and list+details?
What's the priority: minimal code, or efficient workflow for daily users?

please let me know then i will move forward

AkihiroSuda · 2026-07-25T13:45:01Z

Single panel with inline detail — when an instance is selected, show its key details (status, SSH port, IP) below the list in the same panel, then use popups only for actions?

Could be just shown in the table?
Also, the table does not need to repeat "STOPPED" status twice

What's the priority: minimal code, or efficient workflow for daily users?

Minimal code.
Additional features can be proposed in follow-up issues and PRs.

AkihiroSuda · 2026-07-26T20:58:31Z

@Soumya-codr
Please squash the commits, and check #5330 (comment)

Soumya-codr · 2026-07-28T20:43:50Z

Hi @AkihiroSuda,

I have updated the PR according to your feedback:

Single-Panel Layout: Updated to a single-panel list with inline instance details (Status, SSH Port, Address) and an action popup on Enter.
Squashed Commits: Combined all changes into a single clean commit.
DCO Sign-off: Signed off with my real name (Soumya Sagar <soumya.sagar.codr@gmail.com>).

Usability Feedback & Proposed Hotkeys:
Sorry to say, but after testing the single-panel flow, opening the action popup modal via Enter for every routine task (like shelling into a VM or checking info) feels a bit impractical for daily CLI workflows due to the extra keypresses required each time.

To make the workflow much smoother while keeping the implementation minimal, I propose adding direct single-key hotkeys on the list along with a simple footer help bar:

s -> Instant Shell
i -> Show Info
t -> Start / x -> Stop
d -> Delete (with confirmation)
Enter -> Still opens the full Action Modal
Footer help bar: [s] Shell [i] Info [t] Start [x] Stop [Enter] Menu [q] Quit

Would you be open to including these hotkeys in this PR to improve daily usability? Looking forward to your thoughts!

AkihiroSuda · 2026-07-29T08:15:15Z

+	if in.Protected {
+		prot = " [LOCKED]"
+	}
+	return fmt.Sprintf("%s  %-18s  SSH:%-5d  %s%s", icon, name, in.SSHLocalPort, in.SSHAddress, prot)


You can print more info here as in limactl ls

Done! Updated the row layout to include status, arch, CPUs/memory, and SSH address in aligned columns matching limactl ls.

AkihiroSuda · 2026-07-29T08:15:22Z

lint is failing

Fixed! Replaced exec.Command with exec.CommandContext to resolve the noctx linter error. golangci-lint now passes cleanly with 0 issues.

AkihiroSuda · 2026-07-29T08:16:22Z

single-key hotkeys

Can we use functional keys?

e.g. https://midnight-commander.org

AkihiroSuda · 2026-07-29T08:17:54Z

Start/Stop can share a single key for toggling the state

AkihiroSuda · 2026-07-29T08:35:10Z

+		s.showTextView(" Error ", "Failed to get SSH config: "+err.Error())
+		return
+	}
+	tmp := "/tmp/lima-ssh-" + in.Name + ".config"


This path is vulnerable and can be written by other user on the host

Removed man copySSH action entirely to eliminate the /tmp file security vulnerability.

AkihiroSuda · 2026-07-29T08:35:39Z

+	s.showTextView(" Info ", b.String())
+}
+
+func (s *State) copySSH(in *limatype.Instance) {


Do we really need this?
Include ~/.lima/*/ssh.config is more convenient

Agreed! Removed copySSH action to keep the tool minimal and avoid redundant SSH config management.

AkihiroSuda · 2026-07-29T08:37:04Z

+	if p == "" || p == "[]" {
+		p = "No port forwards configured"
+	}
+	s.showTextView(" Port Forwards ", "Port Forwards for "+in.Name+"\n\n"+p)


Something weird was shown

╔ Port Forwards ═══════════════════════════════════════════════════════╗ ║ ║ ║ Port Forwards for agent ║ ║ ║ ║ [{ 0x3b47f1cd7c38 52:55:55:87:3a:b6 lima0 0x3b47f1babde8}] ║ ║ ║ ║ ║ ╚══════════════════════════════════════════════════════════════════════╝

Fixed! Updated the port format string to {{range .PortForwards}}{{.GuestIP}}:{{.GuestPort}} -> {{.HostIP}}:{{.HostPort}}{{"\n"}}{{end}} to properly render port mappings instead of raw network interfaces.

Soumya-codr · 2026-07-29T14:48:56Z

single-key hotkeys

Can we use functional keys?

e.g. https://midnight-commander.org

Updated to Midnight Commander-style Function Keys (F1 Actions, F2 Start/Stop Toggle, F3 Info, F5 Restart, F8 Delete, F10 Quit) along with a bottom help bar legend.

Soumya-codr · 2026-07-29T15:16:01Z

Start/Stop can share a single key for toggling the state

Done! F2 (and t) now acts as a single smart toggle key that starts stopped instances and stops running instances.

Soumya-codr · 2026-07-29T15:20:03Z

Hi @AkihiroSuda ,

I have updated the PR addressing all your review feedback:

Linting: Fixed noctx linter errors by switching to exec.CommandContext. All golangci-lint checks pass cleanly.
Function Keys & Single Start/Stop Toggle: Implemented Midnight Commander-style Function Keys (F1 Actions, F2 Start/Stop Toggle, F3 Info, F5 Restart, F8 Delete, F10 Quit)...
Row Formatting (limactl ls): Formatted table rows to display Status, Arch, CPUs/Memory, and SSH Address matching limactl ls.
Security: Removed copySSH action to eliminate the /tmp file security vulnerability.
Port Forwards: Fixed .PortForwards formatting to display GuestIP:GuestPort -> HostIP:HostPort.
Footer: Added a bottom help bar legend.

Please have a look when you get a chance. Thanks!

afbjorklund · 2026-07-31T16:51:25Z

Can we put this plugin in a separate repository under github.com/lima-vm ?

limactl menu TUI #5285 (comment)

require (
	github.com/gdamore/tcell/v2 v2.13.10
	github.com/rivo/tview v0.42.0
)

It is different from the built-in pkg/uiutil

resker · 2026-08-01T00:28:50Z

Realize this is WIP, but gave it a spin and thought I'd offer a couple first impressions:

Every action (Shell, Start/Stop/Restart, Delete, Protect/Unprotect) calls s.app.Stop() then os.Exit() in execCmd, so it doesn't return to the instance list afterward — it exits the whole TUI. For Shell especially this is surprising: you drop into the VM shell, and typing exit doesn't bring you back to the menu, it exits limactl-menu entirely. Might be worth at least a status-bar hint ("this will exit the menu") or, longer term, restarting the TUI after the subprocess returns for the non-destructive actions.
No inline explanation for what actions do — e.g. Protect/Unprotect isn't obvious to a first-time user (it toggles limactl protect, which blocks accidental limactl delete). Even a one-line description in a footer/status area when an item is focused would help.

AkihiroSuda · 2026-08-01T16:39:24Z

Function Keys & Single Start/Stop Toggle: Implemented Midnight Commander-style Function Keys (F1 Actions, F2 Start/Stop Toggle, F3 Info, F5 Restart, F8 Delete, F10 Quit)...

F1 is commonly used for Help, F5 is for Refresh (not Restart)

AkihiroSuda · 2026-08-01T16:41:34Z

Can we put this plugin in a separate repository under github.com/lima-vm ?

I expect limactl to automatically open the menu UI by default when the menu plugin matures, so I expect it to stay in the main repo.

Implements lima-vm#5285 - adds 'limactl menu' TUI plugin for managing Lima instances through an interactive terminal UI. Features: - Single-panel instance list showing status icon, name, status, arch, CPUs/memory, and SSH address - Midnight Commander-style function keys (F1 Help, F2 Start/Stop Toggle, F3 Info, F5 Refresh, F8 Delete, F10 Quit) - Interactive action popup menu on Enter - F5 refreshes the instance list in-place - Confirmation modals for destructive actions (Stop, Delete) - Modals for instance details and port forwards - Footer help bar with keyboard shortcut legend - Empty state with option to create a new instance when no VMs exist Developed with AI assistance. Signed-off-by: Soumya Sagar <soumya.sagar.codr@gmail.com>

AkihiroSuda · 2026-08-31T06:00:36Z

Needs rebasing

AkihiroSuda · 2026-09-14T04:04:14Z

ping @Soumya-codr

Soumya-codr mentioned this pull request Jul 25, 2026

limactl menu TUI #5285

Open

AkihiroSuda added the area/cli limactl CLI user experience label Jul 25, 2026

AkihiroSuda added the impact/changelog label Jul 25, 2026

Soumya-codr force-pushed the feat/limactl-menu branch from 007075b to 3615845 Compare July 28, 2026 20:42

AkihiroSuda reviewed Jul 29, 2026

View reviewed changes

Soumya-codr force-pushed the feat/limactl-menu branch from 3615845 to c218014 Compare July 29, 2026 14:42

AkihiroSuda added the status/needs-design-consensus label Aug 1, 2026

Soumya-codr force-pushed the feat/limactl-menu branch from c218014 to 6f55939 Compare August 10, 2026 05:14

AkihiroSuda added this to the v2.3.0 milestone Aug 24, 2026

Conversation

Soumya-codr commented Jul 25, 2026

What This PR Changes

Linked Issue (Required in most cases)

How I Tested This

Uh oh!

AkihiroSuda commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AkihiroSuda commented Jul 25, 2026

Uh oh!

Soumya-codr commented Jul 25, 2026

Uh oh!

AkihiroSuda commented Jul 25, 2026

Uh oh!

AkihiroSuda commented Jul 26, 2026

Uh oh!

Soumya-codr commented Jul 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda commented Jul 29, 2026

Uh oh!

AkihiroSuda commented Jul 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Soumya-codr commented Jul 29, 2026

Uh oh!

Soumya-codr commented Jul 29, 2026

Uh oh!

Soumya-codr commented Jul 29, 2026

Uh oh!

afbjorklund commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

resker commented Aug 1, 2026

Uh oh!

AkihiroSuda commented Aug 1, 2026

Uh oh!

AkihiroSuda commented Aug 1, 2026

Uh oh!

AkihiroSuda commented Aug 31, 2026

Uh oh!

AkihiroSuda commented Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AkihiroSuda commented Jul 25, 2026 •

edited

Loading

afbjorklund commented Jul 31, 2026 •

edited

Loading