From 5618876e096e1ac2b9eb4fe389a0e21de8383de7 Mon Sep 17 00:00:00 2001
From: NiloCK <colin@mrkennedy.ca>
Date: Thu, 28 May 2026 12:40:59 -0300
Subject: [PATCH] add filename indexing for `list` cmd

---
 main.go   | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 readme.md | 27 ++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/main.go b/main.go
index 11f0d4c..3a0731f 100644
--- a/main.go
+++ b/main.go
@@ -4,6 +4,7 @@ import (
 	"flag"
 	"fmt"
 	"os"
+	"path/filepath"
 	"runtime"
 	"strings"
 
@@ -81,7 +82,7 @@ func runList(path string, max int, inclSnoozed bool, inclDone bool) {
 
 	tui.SortItems(all)
 
-	filtered := all[:0]
+	var filtered []*tuido.Item
 	for _, item := range all {
 		s := item.Satus()
 		if !inclDone && (s == tuido.Checked || s == tuido.Obsolete) {
@@ -97,10 +98,60 @@ func runList(path string, max int, inclSnoozed bool, inclDone bool) {
 	if max > 0 && max < count {
 		count = max
 	}
+	filtered = filtered[:count]
 
-	for i := 0; i < count; i++ {
-		fmt.Printf("%s\n", filtered[i].String())
+	writeTo := expandTilde(tui.GetConfigWriteTo())
+
+	type entry struct {
+		prefix string
+		text   string
+	}
+	entries := make([]entry, count)
+	prevFile := ""
+	for i, item := range filtered {
+		loc := item.Location()
+		lastColon := strings.LastIndex(loc, ":")
+		filePath, lineStr := loc[:lastColon], loc[lastColon+1:]
+		baseName := filepath.Base(filePath)
+
+		absFile, err := filepath.Abs(filePath)
+		if err != nil {
+			absFile = filePath
+		}
+		isWriteTo := absFile == writeTo ||
+			strings.HasPrefix(absFile, writeTo+string(filepath.Separator))
+
+		switch {
+		case isWriteTo:
+			entries[i].prefix = ""
+		case baseName == prevFile:
+			entries[i].prefix = ":" + lineStr
+		default:
+			entries[i].prefix = "(" + baseName + ":" + lineStr + ")"
+			prevFile = baseName
+		}
+		entries[i].text = item.String()
+	}
+
+	maxWidth := 0
+	for _, e := range entries {
+		if len(e.prefix) > maxWidth {
+			maxWidth = len(e.prefix)
+		}
+	}
+
+	for _, e := range entries {
+		fmt.Printf("%*s %s\n", maxWidth, e.prefix, e.text)
+	}
+}
+
+func expandTilde(path string) string {
+	if strings.HasPrefix(path, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			return filepath.Join(home, path[2:])
+		}
 	}
+	return path
 }
 
 func runCreate(text string) {
diff --git a/readme.md b/readme.md
index 1d48e69..edd2634 100644
--- a/readme.md
+++ b/readme.md
@@ -25,6 +25,33 @@ From some directory containing `[x]it!` files / items, or from anywhere to recov
 tuido
 ```
 
+### CLI commands
+
+`tuido` can also be used non-interactively:
+
+```
+tuido list [--max N] [-z] [-a] [path]
+```
+
+Lists open and in-progress items from `path` (default: current directory). Snoozed and completed/cancelled items are excluded by default.
+
+- `-z`, `--zzz` — include snoozed items
+- `-a`, `--all` — include snoozed, completed, and cancelled items
+- `--max N` — limit output to N items
+
+```
+tuido create <text>
+tuido add <text>
+```
+
+Creates a new open item, written to the configured `writeto` location.
+
+```
+tuido init
+```
+
+Interactive setup wizard. Creates a local (`./.tuido`) or global (`~/.config/tuido.conf`) config file. Run this the first time you use `tuido` in a new context, or to reconfigure an existing one.
+
 ### In app controls
 
 - **?**: help