From 4b5fa5b2b8ed377f014821e231985eea89503fe3 Mon Sep 17 00:00:00 2001
From: Nitin Krishna Mucheli <nmucheli@redhat.com>
Date: Tue, 22 Sep 2026 16:36:55 +0530
Subject: [PATCH] cmd/list, doc, test/system: Add 'ls' as an alias for 'list'

Many users are used to typing 'ls' from everyday Unix usage and expect
it to work as a shorthand for listing things. Add 'ls' as an alias for
the 'toolbox list' command, using Cobra's built-in Aliases mechanism so
that flags, shell completion and error handling all keep working
exactly as they do for 'list'.

Fixes: https://github.com/containers/toolbox/issues/1836
https://github.com/containers/toolbox/pull/1837
---
 doc/meson.build           |  5 +++++
 doc/toolbox-list.1.md     |  2 ++
 doc/toolbox-ls.1          |  1 +
 doc/toolbox.1.md          |  3 ++-
 src/cmd/list.go           |  1 +
 test/system/002-help.bats | 22 ++++++++++++++++++++++
 test/system/102-list.bats |  8 ++++++++
 7 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 doc/toolbox-ls.1

diff --git a/doc/meson.build b/doc/meson.build
index f5b3666f7..a29b48320 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -37,3 +37,8 @@ foreach section, pages: manuals
     )
   endforeach
 endforeach
+
+install_data(
+  'toolbox-ls.1',
+  install_dir: get_option('mandir') / 'man1',
+)
diff --git a/doc/toolbox-list.1.md b/doc/toolbox-list.1.md
index 4d7c7b35a..ef8f4d5f8 100644
--- a/doc/toolbox-list.1.md
+++ b/doc/toolbox-list.1.md
@@ -6,6 +6,8 @@ toolbox\-list - List existing Toolbx containers and images
 ## SYNOPSIS
 **toolbox list** [*--containers* | *-c*] [*--images* | *-i*]
 
+**toolbox ls** [*--containers* | *-c*] [*--images* | *-i*]
+
 ## DESCRIPTION
 
 Lists existing Toolbx containers and images. These are OCI containers and
diff --git a/doc/toolbox-ls.1 b/doc/toolbox-ls.1
new file mode 100644
index 000000000..3e7711c62
--- /dev/null
+++ b/doc/toolbox-ls.1
@@ -0,0 +1 @@
+.so man1/toolbox-list.1
diff --git a/doc/toolbox.1.md b/doc/toolbox.1.md
index b30efd40c..1812697e5 100644
--- a/doc/toolbox.1.md
+++ b/doc/toolbox.1.md
@@ -147,7 +147,8 @@ Initialize a running container.
 
 **toolbox-list(1)**
 
-List existing Toolbx containers and images.
+List existing Toolbx containers and images. Can also be invoked as
+`toolbox ls`.
 
 **toolbox-rm(1)**
 
diff --git a/src/cmd/list.go b/src/cmd/list.go
index b795fd4be..4a4f4560e 100644
--- a/src/cmd/list.go
+++ b/src/cmd/list.go
@@ -38,6 +38,7 @@ var (
 
 var listCmd = &cobra.Command{
 	Use:               "list",
+	Aliases:           []string{"ls"},
 	Short:             "List existing Toolbx containers and images",
 	RunE:              list,
 	ValidArgsFunction: completionEmpty,
diff --git a/test/system/002-help.bats b/test/system/002-help.bats
index 0df1af01e..3aa096ffb 100644
--- a/test/system/002-help.bats
+++ b/test/system/002-help.bats
@@ -269,6 +269,28 @@ teardown_file() {
   assert [ ${#stderr_lines[@]} -eq 2 ]
 }
 
+@test "help: Try 'list' with unknown flag (using the 'ls' alias)" {
+  run --keep-empty-lines --separate-stderr "$TOOLBX" ls --foo
+
+  assert_failure
+  assert [ ${#lines[@]} -eq 0 ]
+  lines=("${stderr_lines[@]}")
+  assert_line --index 0 "Error: unknown flag: --foo"
+  assert_line --index 1 "Run 'toolbox --help' for usage."
+  assert [ ${#stderr_lines[@]} -eq 2 ]
+}
+
+@test "help: Try 'list' with unknown flag (using the 'ls' alias, forwarded to host)" {
+  run -1 --keep-empty-lines --separate-stderr "$TOOLBX" run toolbox ls --foo
+
+  assert_failure
+  assert [ ${#lines[@]} -eq 0 ]
+  lines=("${stderr_lines[@]}")
+  assert_line --index 0 "Error: unknown flag: --foo"
+  assert_line --index 1 "Run 'toolbox --help' for usage."
+  assert [ ${#stderr_lines[@]} -eq 2 ]
+}
+
 @test "help: Try 'rm' with unknown flag" {
   run --keep-empty-lines --separate-stderr "$TOOLBX" rm --foo
 
diff --git a/test/system/102-list.bats b/test/system/102-list.bats
index cff206dd0..71f9754fe 100644
--- a/test/system/102-list.bats
+++ b/test/system/102-list.bats
@@ -40,6 +40,14 @@ teardown() {
   assert [ ${#stderr_lines[@]} -eq 0 ]
 }
 
+@test "list: Smoke test (using the 'ls' alias)" {
+  run --keep-empty-lines --separate-stderr "$TOOLBX" ls
+
+  assert_success
+  assert [ ${#lines[@]} -eq 0 ]
+  assert [ ${#stderr_lines[@]} -eq 0 ]
+}
+
 @test "list: Smoke test (using --containers)" {
   run --keep-empty-lines --separate-stderr "$TOOLBX" list --containers