CLI Colors (#1006)

- Add `_colors.py` module with `ColorMode` enum and `Colors` class
- Add global `--color` flag (auto/always/never) to CLI root parser
- Support `NO_COLOR` and `FORCE_COLOR` environment variables (CPython-style)
- Update `load.py` with semantic colors (info, success, error, highlight, etc.)
- Update `ls.py` and `debug_info.py` to use Colors class

Author: tony

AGENTS.md

@@ -195,3 +195,69 @@ $ uv run pytest --cov
 - **QA every edit**: Run formatting and tests before committing
 - **Minimum Python**: 3.10+ (per pyproject.toml)
 - **Minimum tmux**: 3.2+ (as per README)
+
+## CLI Color Semantics (Revision 1, 2026-01-04)
+
+The CLI uses semantic colors via the `Colors` class in `src/tmuxp/_internal/colors.py`. Colors are chosen based on **hierarchy level** and **semantic meaning**, not just data type.
+
+### Design Principles
+
+1. **Structural hierarchy**: Headers > Items > Details
+2. **Semantic meaning**: What IS this element?
+3. **Visual weight**: What should draw the eye first?
+4. **Depth separation**: Parent elements should visually contain children
+
+Inspired by patterns from **jq** (object keys vs values), **ripgrep** (path/line/match distinction), and **mise/just** (semantic method names).
+
+### Hierarchy-Based Colors
+
+| Level | Element Type | Method | Color | Examples |
+|-------|--------------|--------|-------|----------|
+| **L0** | Section headers | `heading()` | Bright cyan + bold | "Local workspaces:", "Global workspaces:" |
+| **L1** | Primary content | `highlight()` | Magenta + bold | Workspace names (braintree, .tmuxp) |
+| **L2** | Supplementary info | `info()` | Cyan | Paths (~/.tmuxp, ~/project/.tmuxp.yaml) |
+| **L3** | Metadata/labels | `muted()` | Blue | Source labels (Legacy:, XDG default:) |
+
+### Status-Based Colors (Override hierarchy when applicable)
+
+| Status | Method | Color | Examples |
+|--------|--------|-------|----------|
+| Success/Active | `success()` | Green | "active", "18 workspaces" |
+| Warning | `warning()` | Yellow | Deprecation notices |
+| Error | `error()` | Red | Error messages |
+
+### Example Output
+
+```
+Local workspaces:                              ← heading() bright_cyan+bold
+  .tmuxp  ~/work/python/tmuxp/.tmuxp.yaml      ← highlight() + info()
+
+Global workspaces (~/.tmuxp):                  ← heading() + info()
+  braintree                                    ← highlight()
+  cihai                                        ← highlight()
+
+Global workspace directories:                  ← heading()
+  Legacy: ~/.tmuxp (18 workspaces, active)     ← muted() + info() + success()
+  XDG default: ~/.config/tmuxp (not found)     ← muted() + info() + muted()
+```
+
+### Available Methods
+
+```python
+colors = Colors()
+colors.heading("Section:")      # Cyan + bold (section headers)
+colors.highlight("item")        # Magenta + bold (primary content)
+colors.info("/path/to/file")    # Cyan (paths, supplementary info)
+colors.muted("label:")          # Blue (metadata, labels)
+colors.success("ok")            # Green (success states)
+colors.warning("caution")       # Yellow (warnings)
+colors.error("failed")          # Red (errors)
+```
+
+### Key Rules
+
+**Never use the same color for adjacent hierarchy levels.** If headers and items are both blue, they blend together. Each level must be visually distinct.
+
+**Avoid dim/faint styling.** The ANSI dim attribute (`\x1b[2m`) is too dark to read on black terminal backgrounds. This includes both standard and bright color variants with dim.
+
+**Bold may not render distinctly.** Some terminal/font combinations don't differentiate bold from normal weight. Don't rely on bold alone for visual distinction - pair it with color differences.

CHANGES

@@ -31,6 +31,45 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+### Features
+
+#### CLI Colors (#1006)
+
+New semantic color output for all CLI commands:
+
+- New `--color` flag (auto/always/never) on root CLI for controlling color output
+- Respects `NO_COLOR` and `FORCE_COLOR` environment variables per [no-color.org](https://no-color.org) standard
+- Semantic color methods: `success()` (green), `warning()` (yellow), `error()` (red), `info()` (cyan), `highlight()` (magenta), `muted()` (blue)
+- All commands updated with colored output: `load`, `ls`, `freeze`, `convert`, `import`, `edit`, `shell`, `debug-info`
+- Interactive prompts enhanced with color support
+- `PrivatePath` utility masks home directory as `~` for privacy protection in output
+- Beautiful `--help` output with usage examples
+
+#### Search Command (#1006)
+
+New `tmuxp search` command for finding workspace files:
+
+- Field-scoped search with prefixes: `name:`, `session:`, `path:`, `window:`, `pane:`
+- Matching options: `-i` (ignore-case), `-S` (smart-case), `-F` (fixed-strings), `-w` (word)
+- Logic operators: `--any` for OR, `-v` for invert match
+- Output formats: human (with match highlighting), `--json`, `--ndjson` for automation and piping to `jq`
+- Searches local (cwd and parents) and global (~/.tmuxp/) workspaces
+
+#### Enhanced ls Command (#1006)
+
+New output options for `tmuxp ls`:
+
+- `--tree`: Display workspaces grouped by directory
+- `--full`: Include complete parsed config content
+- `--json` / `--ndjson`: Machine-readable output for automation and piping to `jq`
+- Local workspace discovery from current directory and parents
+- Source field distinguishes "local" vs "global" workspaces
+- "Global workspace directories" section shows XDG vs legacy paths with status
+
+#### JSON Output for debug-info (#1006)
+
+- `tmuxp debug-info --json`: Structured JSON output for automation, issue reporting, and piping to `jq`
+
 ### Development
 
 #### Makefile -> Justfile (#1005)

conftest.py

@@ -98,18 +98,31 @@ def socket_name(request: pytest.FixtureRequest) -> str:
     return f"tmuxp_test{next(namer)}"
 
 
+# Modules that actually need tmux fixtures in their doctests
+DOCTEST_NEEDS_TMUX = {
+    "tmuxp.workspace.builder",
+}
+
+
 @pytest.fixture(autouse=True)
 def add_doctest_fixtures(
     request: pytest.FixtureRequest,
     doctest_namespace: dict[str, t.Any],
     tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Harness pytest fixtures to doctests namespace."""
-    if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
-        doctest_namespace["server"] = request.getfixturevalue("server")
-        session: Session = request.getfixturevalue("session")
-        doctest_namespace["session"] = session
-        doctest_namespace["window"] = session.active_window
-        doctest_namespace["pane"] = session.active_pane
+    if isinstance(request._pyfuncitem, DoctestItem):
+        # Always provide lightweight fixtures
         doctest_namespace["test_utils"] = test_utils
         doctest_namespace["tmp_path"] = tmp_path
+        doctest_namespace["monkeypatch"] = monkeypatch
+
+        # Only load expensive tmux fixtures for modules that need them
+        module_name = request._pyfuncitem.dtest.globs.get("__name__", "")
+        if module_name in DOCTEST_NEEDS_TMUX and shutil.which("tmux"):
+            doctest_namespace["server"] = request.getfixturevalue("server")
+            session: Session = request.getfixturevalue("session")
+            doctest_namespace["session"] = session
+            doctest_namespace["window"] = session.active_window
+            doctest_namespace["pane"] = session.active_pane

docs/api/cli/index.md

@@ -16,6 +16,7 @@ freeze
 import_config
 load
 ls
+search
 shell
 utils
 ```

docs/api/cli/search.md

@@ -0,0 +1,8 @@
+# tmuxp search - `tmuxp.cli.search`
+
+```{eval-rst}
+.. automodule:: tmuxp.cli.search
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/internals/colors.md

@@ -0,0 +1,14 @@
+# Colors - `tmuxp._internal.colors`
+
+:::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues).
+:::
+
+```{eval-rst}
+.. automodule:: tmuxp._internal.colors
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/api/internals/index.md

@@ -9,6 +9,8 @@ If you need an internal API stabilized please [file an issue](https://github.com
 :::
 
 ```{toctree}
+colors
 config_reader
+private_path
 types
 ```

docs/api/internals/private_path.md

@@ -0,0 +1,14 @@
+# Private path - `tmuxp._internal.private_path`
+
+:::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/tmuxp/issues).
+:::
+
+```{eval-rst}
+.. automodule:: tmuxp._internal.private_path
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/cli/convert.md

@@ -2,8 +2,6 @@
 
 # tmuxp convert
 
-Convert between YAML and JSON
-
 ```{eval-rst}
 .. argparse::
     :module: tmuxp.cli

docs/cli/debug-info.md

@@ -4,9 +4,6 @@
 
 # tmuxp debug-info
 
-Use to collect all relevant information for submitting an issue to
-the project.
-
 ```{eval-rst}
 .. argparse::
     :module: tmuxp.cli