ls: add --sort-by FIELDS option

src/con_duct/cli.py

@@ -454,7 +454,14 @@ def _create_ls_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--reverse",
         action="store_true",
-        help="List entries in reverse order (most recent first).",
+        help="List entries in reverse order.",
+    )
+    parser.add_argument(
+        "--sort-by",
+        nargs="+",
+        metavar="FIELD",
+        choices=LS_FIELD_CHOICES,
+        help="Sort results by one or more fields. See --fields for available choices.",
     )
     return parser
 

src/con_duct/ls.py

@@ -231,6 +231,22 @@ def ls(args: argparse.Namespace) -> int:
     )
     info_files = [path for path in args.paths if is_info_file(path)]
     run_data_raw = load_duct_runs(info_files, args.eval_filter)
+
+    if sort_by := getattr(args, "sort_by", None):
+        run_data_raw = [
+            item
+            for _, item in sorted(
+                zip(map(_flatten_dict, run_data_raw), run_data_raw),
+                key=lambda x: tuple(
+                    (
+                        x[0].get(k) is None,
+                        x[0].get(k) if x[0].get(k) is not None else "",
+                    )
+                    for k in sort_by
+                ),
+            )
+        ]
+
     output_rows = process_run_data(run_data_raw, args.fields, formatter)
 
     if args.reverse:

test/test_ls.py

@@ -223,6 +223,7 @@ def _run_ls(
                 format=fmt,
                 func=ls,
                 reverse=False,
+                sort_by=None,
             )
         buf = StringIO()
         with contextlib.redirect_stdout(buf):
@@ -255,6 +256,7 @@ def test_ls_with_filter(self) -> None:
             format="summaries",
             func=ls,
             reverse=False,
+            sort_by=None,
         )
         result = self._run_ls(paths, "summaries", args)
 
@@ -383,9 +385,91 @@ def test_ls_reverse(self) -> None:
             format="json",
             func=ls,
             reverse=True,
+            sort_by=None,
         )
         result_reversed = self._run_ls(paths, "json", args)
         parsed_reversed = json.loads(result_reversed)
         prefixes_reversed = [row["prefix"] for row in parsed_reversed]
 
         assert prefixes_reversed == list(reversed(prefixes_normal))
+
+
+@pytest.mark.parametrize("reverse", [False, True])
+def test_ls_sort_by(reverse: bool, tmp_path: Any) -> None:
+    """Test --sort-by flag sorts entries by the specified field, with optional reverse."""
+    files = {
+        "file1_info.json": {
+            "schema_version": MINIMUM_SCHEMA_VERSION,
+            "execution_summary": {},
+            "prefix": "test1",
+        },
+        "file2_info.json": {
+            "schema_version": MINIMUM_SCHEMA_VERSION,
+            "execution_summary": {},
+            "prefix": "test2",
+        },
+    }
+    for filename, content in files.items():
+        path = tmp_path / filename
+        path.write_text(json.dumps(content))
+
+    paths = [str(tmp_path / f) for f in files]
+    args = argparse.Namespace(
+        paths=paths,
+        colors=False,
+        fields=["prefix", "schema_version"],
+        eval_filter=None,
+        format="json",
+        func=ls,
+        reverse=reverse,
+        sort_by=["prefix"],
+    )
+    buf = StringIO()
+    with contextlib.redirect_stdout(buf):
+        assert ls(args) == 0
+    prefixes = [row["prefix"] for row in json.loads(buf.getvalue().strip())]
+    assert prefixes == sorted(prefixes, reverse=reverse)
+
+
+def test_ls_sort_by_non_displayed_field(tmp_path: Any) -> None:
+    """Test --sort-by works for fields not included in --fields (not displayed)."""
+    # Three runs with commands in non-alphabetical order; paths also in non-alphabetical
+    # order so glob/filesystem order cannot accidentally pass the test.
+    entries = [
+        ("run_b_info.json", "cmd_b"),
+        ("run_a_info.json", "cmd_a"),
+        ("run_c_info.json", "cmd_c"),
+    ]
+    for filename, command in entries:
+        (tmp_path / filename).write_text(
+            json.dumps(
+                {
+                    "schema_version": MINIMUM_SCHEMA_VERSION,
+                    "execution_summary": {},
+                    "command": command,
+                }
+            )
+        )
+
+    # paths deliberately in creation order (b, a, c) — not sorted by command
+    paths = [str(tmp_path / filename) for filename, _ in entries]
+    args = argparse.Namespace(
+        paths=paths,
+        colors=False,
+        fields=["prefix"],  # "command" is intentionally NOT in displayed fields
+        eval_filter=None,
+        format="json",
+        func=ls,
+        reverse=False,
+        sort_by=["command"],
+    )
+    buf = StringIO()
+    with contextlib.redirect_stdout(buf):
+        assert ls(args) == 0
+    rows = json.loads(buf.getvalue().strip())
+    # Output order should match sorted command order: cmd_a, cmd_b, cmd_c
+    # which corresponds to run_a, run_b, run_c prefixes
+    prefixes = [row["prefix"] for row in rows]
+    assert "run_a_" in prefixes[0]
+    assert "run_b_" in prefixes[1]
+    assert "run_c_" in prefixes[2]