netbox-super-cli 1.3.1__tar.gz → 1.4.0__tar.gz

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to netbox-super-cli are tracked here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely. From v1.0.0 onward, releases follow [Semantic Versioning](https://semver.org/) and the version in `pyproject.toml` matches the git tag. Pre-1.0 milestones (Phase 1-5) were pinned by tag while `pyproject.toml` stayed at `0.0.1`.
 
+## v1.4.0 — 2026-06-26
+
+Minor release. Three user-facing features for the interactive TUI and table
+output: individually selectable custom-field columns, local saved searches, and
+NetBox-native object colors.
+
+### Added
+
+- **Individually selectable custom fields** ([#121], closes [#118]). The TUI
+  column chooser (`f` — Fields) now expands `custom_fields` into one toggleable
+  column per custom field (`custom_fields.<name>`) instead of a single opaque
+  object. On the CLI, `--columns custom_fields.<name>` selects an individual
+  custom field (now documented).
+- **Saved searches** ([#123], closes [#119]). Named filter sets persist per
+  resource. In the TUI filter builder, `Ctrl+W` saves the current filters under
+  a name and `Ctrl+O` opens a picker to apply one (`d` deletes an entry). On the
+  CLI, `--saved <name>` re-applies a saved filter set on `list`; explicit
+  `--filter` and typed options take precedence over saved values. Names
+  containing `.` (or whitespace) are rejected to keep the config file well-formed.
+- **NetBox object colors** ([#122], closes [#120]). Role, tag, and other
+  color-bearing fields render in their NetBox-defined colors in table output. A
+  new `object_colors` setting (`auto`/`on`/`off`) and the
+  `--object-colors/--no-object-colors` flag toggle this independently of
+  `--color`; `off`, `NO_COLOR`, and non-TTY output are always respected.
+
+[#118]: https://github.com/thomaschristory/netbox-super-cli/issues/118
+[#119]: https://github.com/thomaschristory/netbox-super-cli/issues/119
+[#120]: https://github.com/thomaschristory/netbox-super-cli/issues/120
+[#121]: https://github.com/thomaschristory/netbox-super-cli/pull/121
+[#122]: https://github.com/thomaschristory/netbox-super-cli/pull/122
+[#123]: https://github.com/thomaschristory/netbox-super-cli/pull/123
+
 ## v1.3.1 — 2026-06-25
 
 Patch release. CI maintenance only — no runtime or user-facing changes.

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-super-cli
-Version: 1.3.1
+Version: 1.4.0
 Summary: Dynamic NetBox CLI generated from the live OpenAPI schema.
 Project-URL: Homepage, https://github.com/thomaschristory/netbox-super-cli
 Project-URL: Issues, https://github.com/thomaschristory/netbox-super-cli/issues
@@ -27,9 +27,29 @@ Requires-Dist: textual>=0.50
 Requires-Dist: typer<0.27,>=0.26
 Description-Content-Type: text/markdown
 
-# netbox-super-cli (`nsc`)
+<div align="center">
 
-A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dynamically from your install's live OpenAPI schema. The same binary works against any NetBox version and exposes plugin-provided endpoints automatically — the schema, not hand-written code, defines the surface.
+# netbox-super-cli&nbsp;·&nbsp;`nsc`
+
+**A Python CLI for [NetBox](https://netbox.dev/) that builds its entire command tree from your install's live OpenAPI schema.**
+
+One binary, any NetBox version, every plugin endpoint — the schema, not hand-written code, defines the surface.
+
+<br/>
+
+[![PyPI version](https://img.shields.io/pypi/v/netbox-super-cli?style=flat-square&logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/netbox-super-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/netbox-super-cli?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/netbox-super-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/netbox-super-cli?style=flat-square&label=downloads)](https://pypi.org/project/netbox-super-cli/)
+[![License](https://img.shields.io/badge/license-Apache_2.0-green?style=flat-square)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/thomaschristory/netbox-super-cli/test.yml?branch=main&style=flat-square&label=tests)](https://github.com/thomaschristory/netbox-super-cli/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-online-blue?style=flat-square)](https://thomaschristory.github.io/netbox-super-cli/)
+[![Stars](https://img.shields.io/github/stars/thomaschristory/netbox-super-cli?style=flat-square)](https://github.com/thomaschristory/netbox-super-cli/stargazers)
+
+[**📚 Documentation**](https://thomaschristory.github.io/netbox-super-cli/) &nbsp;·&nbsp; [**🚀 Install**](#install) &nbsp;·&nbsp; [**🖥️ Interactive TUI**](#interactive-tui) &nbsp;·&nbsp; [**🤖 AI Skill**](#bundled-skill-for-ai-agents)
+
+</div>
+
+---
 
 > **Docs:** [thomaschristory.github.io/netbox-super-cli](https://thomaschristory.github.io/netbox-super-cli/) — the full guide, including install, first-run, guides, and the auto-generated CLI/config/exit-code reference.
 
@@ -74,7 +94,9 @@ nsc tui devices    # jump straight into the devices list
 Highlights: a collapsible resource picker, a web-UI-style filter builder (`/`),
 inline record editing with a confirm-diff save, schema-derived relationship
 drill-down, bulk edit with a per-record preview, a persisted column chooser
-(`f`), and global search (`Ctrl`+`F`). Full walkthrough in the
+(`f`) that lists each custom field individually, and global search (`Ctrl`+`F`).
+The same dotted paths work on the CLI: `nsc ls devices --columns id,name,custom_fields.rack_role`.
+Full walkthrough in the
 [Interactive TUI guide](https://thomaschristory.github.io/netbox-super-cli/guides/interactive-tui/).
 
 ## Reading
@@ -90,6 +112,37 @@ uv run nsc circuits providers list --output csv
 uv run nsc ipam prefixes list --filter created__gte=2026-01-01 --output yaml
 ```
 
+### Saved searches
+
+Filter sets you save from the TUI (Ctrl+W in the filter builder) are stored
+locally under `saved_searches` in `~/.nsc/config.yaml`, keyed by tag/resource.
+Re-apply one on the CLI with `--saved`:
+
+```sh
+uv run nsc dcim devices list --saved active-switches
+# explicit --filter / typed options override the saved values:
+uv run nsc dcim devices list --saved active-switches --status offline
+```
+
+This is a local, per-config convenience and is unrelated to NetBox's
+server-side saved filters (`extras saved-filters`), which store web-UI query
+strings.
+
+### Object colors
+
+NetBox assigns colors to roles, tags, and similar fields. In table output `nsc`
+renders those values in their NetBox-defined colors:
+
+```sh
+uv run nsc dcim devices list                      # colored when stdout is a TTY
+uv run nsc dcim devices list --no-object-colors   # plain text
+```
+
+Toggle it independently of `--color` with the `object_colors` setting
+(`auto`/`on`/`off`) or the `--object-colors/--no-object-colors` flag. `off`,
+`NO_COLOR`, and non-TTY output are always respected, so piped or redirected
+output stays uncolored.
+
 ## Writing
 
 ```sh

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/README.md

@@ -1,6 +1,26 @@
-# netbox-super-cli (`nsc`)
+<div align="center">
 
-A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dynamically from your install's live OpenAPI schema. The same binary works against any NetBox version and exposes plugin-provided endpoints automatically — the schema, not hand-written code, defines the surface.
+# netbox-super-cli&nbsp;·&nbsp;`nsc`
+
+**A Python CLI for [NetBox](https://netbox.dev/) that builds its entire command tree from your install's live OpenAPI schema.**
+
+One binary, any NetBox version, every plugin endpoint — the schema, not hand-written code, defines the surface.
+
+<br/>
+
+[![PyPI version](https://img.shields.io/pypi/v/netbox-super-cli?style=flat-square&logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/netbox-super-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/netbox-super-cli?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/netbox-super-cli/)
+[![Downloads](https://img.shields.io/pypi/dm/netbox-super-cli?style=flat-square&label=downloads)](https://pypi.org/project/netbox-super-cli/)
+[![License](https://img.shields.io/badge/license-Apache_2.0-green?style=flat-square)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/thomaschristory/netbox-super-cli/test.yml?branch=main&style=flat-square&label=tests)](https://github.com/thomaschristory/netbox-super-cli/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-online-blue?style=flat-square)](https://thomaschristory.github.io/netbox-super-cli/)
+[![Stars](https://img.shields.io/github/stars/thomaschristory/netbox-super-cli?style=flat-square)](https://github.com/thomaschristory/netbox-super-cli/stargazers)
+
+[**📚 Documentation**](https://thomaschristory.github.io/netbox-super-cli/) &nbsp;·&nbsp; [**🚀 Install**](#install) &nbsp;·&nbsp; [**🖥️ Interactive TUI**](#interactive-tui) &nbsp;·&nbsp; [**🤖 AI Skill**](#bundled-skill-for-ai-agents)
+
+</div>
+
+---
 
 > **Docs:** [thomaschristory.github.io/netbox-super-cli](https://thomaschristory.github.io/netbox-super-cli/) — the full guide, including install, first-run, guides, and the auto-generated CLI/config/exit-code reference.
 
@@ -45,7 +65,9 @@ nsc tui devices    # jump straight into the devices list
 Highlights: a collapsible resource picker, a web-UI-style filter builder (`/`),
 inline record editing with a confirm-diff save, schema-derived relationship
 drill-down, bulk edit with a per-record preview, a persisted column chooser
-(`f`), and global search (`Ctrl`+`F`). Full walkthrough in the
+(`f`) that lists each custom field individually, and global search (`Ctrl`+`F`).
+The same dotted paths work on the CLI: `nsc ls devices --columns id,name,custom_fields.rack_role`.
+Full walkthrough in the
 [Interactive TUI guide](https://thomaschristory.github.io/netbox-super-cli/guides/interactive-tui/).
 
 ## Reading
@@ -61,6 +83,37 @@ uv run nsc circuits providers list --output csv
 uv run nsc ipam prefixes list --filter created__gte=2026-01-01 --output yaml
 ```
 
+### Saved searches
+
+Filter sets you save from the TUI (Ctrl+W in the filter builder) are stored
+locally under `saved_searches` in `~/.nsc/config.yaml`, keyed by tag/resource.
+Re-apply one on the CLI with `--saved`:
+
+```sh
+uv run nsc dcim devices list --saved active-switches
+# explicit --filter / typed options override the saved values:
+uv run nsc dcim devices list --saved active-switches --status offline
+```
+
+This is a local, per-config convenience and is unrelated to NetBox's
+server-side saved filters (`extras saved-filters`), which store web-UI query
+strings.
+
+### Object colors
+
+NetBox assigns colors to roles, tags, and similar fields. In table output `nsc`
+renders those values in their NetBox-defined colors:
+
+```sh
+uv run nsc dcim devices list                      # colored when stdout is a TTY
+uv run nsc dcim devices list --no-object-colors   # plain text
+```
+
+Toggle it independently of `--color` with the `object_colors` setting
+(`auto`/`on`/`off`) or the `--object-colors/--no-object-colors` flag. `off`,
+`NO_COLOR`, and non-TTY output are always respected, so piped or redirected
+output stays uncolored.
+
 ## Writing
 
 ```sh

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/docs/reference/config.md

@@ -11,8 +11,9 @@ All fields below describe `~/.nsc/config.yaml`.
 |---|---|---|
 | `default_profile` | `str | None` | `None` |
 | `profiles` | `dict[str, Profile]` | `{}` |
-| `defaults` | `<class 'Defaults'>` | `Defaults(output=<OutputFormat.TABLE: 'table'>, page_size=50, timeout=30.0, schema_refresh=<SchemaRefresh.DAILY: 'daily'>, color_mode=<ColorMode.AUTO: 'auto'>, audit_redaction=<AuditRedaction.SAFE: 'safe'>)` |
+| `defaults` | `<class 'Defaults'>` | `Defaults(output=<OutputFormat.TABLE: 'table'>, page_size=50, timeout=30.0, schema_refresh=<SchemaRefresh.DAILY: 'daily'>, color_mode=<ColorMode.AUTO: 'auto'>, object_colors=<ObjectColorMode.AUTO: 'auto'>, audit_redaction=<AuditRedaction.SAFE: 'safe'>)` |
 | `columns` | `dict[str, dict[str, list[str]]]` | `{}` |
+| `saved_searches` | `dict[str, dict[str, dict[str, dict[str, str]]]]` | `{}` |
 
 ## `Profile`
 
@@ -34,4 +35,5 @@ All fields below describe `~/.nsc/config.yaml`.
 | `timeout` | `<class 'float'>` | `30.0` |
 | `schema_refresh` | `<enum 'SchemaRefresh'>` | `<SchemaRefresh.DAILY: 'daily'>` |
 | `color_mode` | `<enum 'ColorMode'>` | `<ColorMode.AUTO: 'auto'>` |
+| `object_colors` | `<enum 'ObjectColorMode'>` | `<ObjectColorMode.AUTO: 'auto'>` |
 | `audit_redaction` | `<enum 'AuditRedaction'>` | `<AuditRedaction.SAFE: 'safe'>` |

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/app.py

@@ -94,6 +94,14 @@ def _extract_global_overrides(args: list[str]) -> CLIOverrides:
             kwargs["refresh_schema"] = True
             i += 1
             continue
+        if a == "--object-colors":
+            kwargs["object_colors"] = True
+            i += 1
+            continue
+        if a == "--no-object-colors":
+            kwargs["object_colors"] = False
+            i += 1
+            continue
         i += 1
     return CLIOverrides(**kwargs)  # type: ignore[arg-type]
 
@@ -310,6 +318,13 @@ def _root(
         ),
     ] = False,
     output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+    object_colors: Annotated[
+        bool | None,
+        typer.Option(
+            "--object-colors/--no-object-colors",
+            help="Render NetBox-native object colors (role/tag/…) in table output.",
+        ),
+    ] = None,
     debug: Annotated[bool, typer.Option("--debug")] = False,
 ) -> None:
     """Root callback — global options live here."""
@@ -321,6 +336,7 @@ def _root(
         schema_override=schema,
         refresh_schema=refresh_schema,
         output=output,
+        object_colors=object_colors,
     )
     try:
         config = load_config(default_paths().config_file)

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/globals.py

@@ -10,10 +10,11 @@ from nsc.cli.runtime import (
     CLIOverrides,
     RuntimeContext,
     resolve_color,
+    resolve_object_colors,
     resolve_profile,
 )
 from nsc.config import default_paths
-from nsc.config.models import Config
+from nsc.config.models import Config, ObjectColorMode
 from nsc.http.client import NetBoxClient
 from nsc.output.render import select_format
 from nsc.schema.source import resolve_command_model
@@ -48,6 +49,8 @@ def build_runtime_context(state: GlobalState) -> RuntimeContext:
         redaction=state.config.defaults.audit_redaction,
         profile_name=profile.name,
     )
+    color = resolve_color(state.config.defaults.color_mode, is_tty=sys.stdout.isatty())
+    object_color_mode = _resolve_object_color_mode(state)
     return RuntimeContext(
         resolved_profile=profile,
         config=state.config,
@@ -56,11 +59,19 @@ def build_runtime_context(state: GlobalState) -> RuntimeContext:
         output_format=output,
         debug=state.debug,
         page_size=state.config.defaults.page_size,
-        color=resolve_color(state.config.defaults.color_mode, is_tty=sys.stdout.isatty()),
+        color=color,
         color_stderr=resolve_color(state.config.defaults.color_mode, is_tty=sys.stderr.isatty()),
+        object_colors=resolve_object_colors(object_color_mode, color=color),
     )
 
 
+def _resolve_object_color_mode(state: GlobalState) -> ObjectColorMode:
+    override = state.overrides.object_colors
+    if override is None:
+        return state.config.defaults.object_colors
+    return ObjectColorMode.ON if override else ObjectColorMode.OFF
+
+
 __all__ = [
     "GlobalState",
     "build_runtime_context",

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/handlers.py

@@ -104,6 +104,7 @@ def handle_list(
             stream=_out(stream),
             compact=ctx.compact,
             color=ctx.color,
+            object_colors=ctx.object_colors,
         )
     except (NetBoxAPIError, NetBoxClientError) as exc:
         env = map_error(exc, operation_id=operation.operation_id)
@@ -130,6 +131,7 @@ def handle_get(
             stream=_out(stream),
             compact=ctx.compact,
             color=ctx.color,
+            object_colors=ctx.object_colors,
         )
     except (NetBoxAPIError, NetBoxClientError) as exc:
         env = map_error(exc, operation_id=operation.operation_id)
@@ -616,6 +618,7 @@ def _render_response(
         stream=stream,
         compact=ctx.compact,
         color=ctx.color,
+        object_colors=ctx.object_colors,
     )
 
 

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/registration.py

@@ -120,10 +120,39 @@ def _register_write(
 
 
 _GLOBAL_FLAG_NAMES: frozenset[str] = frozenset(
-    {"output", "compact", "columns", "limit", "all_", "filter_"}
+    {"output", "compact", "columns", "limit", "all_", "filter_", "saved"}
 )
 
 
+def _resolve_saved_filters(
+    ctx: RuntimeContext,
+    tag_name: str,
+    resource_name: str,
+    saved_name: str | None,
+    explicit_filters: list[tuple[str, str]],
+    typed_kwargs: dict[str, Any],
+) -> list[tuple[str, str]]:
+    """Layer a `--saved` filter set under explicit `--filter` and typed options.
+
+    Saved params are the base; explicit `--filter` pairs and any non-None typed
+    query option (already in ``typed_kwargs``) win. Order matters: ``handle_list``
+    overlays ``ctx.filters`` onto the typed-option params, so saved keys that the
+    user also set via a typed flag must be dropped here to let the flag win.
+    """
+    if saved_name is None:
+        return explicit_filters
+    from nsc.config.saved_searches import get_saved_search  # noqa: PLC0415
+
+    saved = get_saved_search(ctx.config, tag_name, resource_name, saved_name)
+    if saved is None:
+        raise typer.BadParameter(
+            f"no saved search named {saved_name!r} for {tag_name}/{resource_name}"
+        )
+    typed_keys = {k for k, v in typed_kwargs.items() if v is not None}
+    base = [(k, v) for k, v in saved.items() if k not in typed_keys]
+    return base + explicit_filters
+
+
 def _build_read_closure(
     operation: Operation,
     tag_name: str,
@@ -151,17 +180,19 @@ def _build_read_closure(
         limit = kwargs.pop("limit", None)
         fetch_all = kwargs.pop("all_", False)
         filters_raw: list[str] = kwargs.pop("filter_", None) or []
+        saved_name: str | None = kwargs.pop("saved", None)
         ctx = get_ctx()
+        explicit_filters = [
+            (item.split("=", 1)[0], item.split("=", 1)[1]) for item in filters_raw if "=" in item
+        ]
         update: dict[str, Any] = {
             "compact": compact,
             "columns_override": columns_csv.split(",") if columns_csv else None,
             "limit": limit,
             "fetch_all": fetch_all,
-            "filters": [
-                (item.split("=", 1)[0], item.split("=", 1)[1])
-                for item in filters_raw
-                if "=" in item
-            ],
+            "filters": _resolve_saved_filters(
+                ctx, tag_name, resource_name, saved_name, explicit_filters, kwargs
+            ),
         }
         if output:
             update["output_format"] = OutputFormat(output)
@@ -311,6 +342,20 @@ def _build_global_flag_params() -> tuple[inspect.Parameter, ...]:
             annotation=list[str] | None,
             default=typer.Option(None, "--filter"),
         ),
+        inspect.Parameter(
+            name="saved",
+            kind=inspect.Parameter.KEYWORD_ONLY,
+            annotation=str | None,
+            default=typer.Option(
+                None,
+                "--saved",
+                help=(
+                    "Apply a LOCAL named filter set saved from the TUI (config "
+                    "`saved_searches`). Explicit --filter/typed options override it. "
+                    "Unrelated to NetBox server-side saved filters."
+                ),
+            ),
+        ),
     )
 
 

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/runtime.py

@@ -15,7 +15,7 @@ from typing import Any, Literal
 from pydantic import BaseModel, ConfigDict, HttpUrl, SkipValidation
 
 from nsc.cache.store import ADHOC_PROFILE
-from nsc.config.models import ColorMode, Config, OutputFormat, Profile
+from nsc.config.models import ColorMode, Config, ObjectColorMode, OutputFormat, Profile
 from nsc.config.settings import default_paths
 from nsc.http.client import NetBoxClient
 from nsc.http.errors import NetBoxAPIError, NetBoxClientError
@@ -52,6 +52,7 @@ class CLIOverrides(_Frozen):
     schema_override: str | None = None
     refresh_schema: bool = False
     output: str | None = None
+    object_colors: bool | None = None
 
 
 class ResolvedProfile(_Frozen):
@@ -186,6 +187,22 @@ def resolve_color(mode: ColorMode, *, is_tty: bool) -> bool:
     return is_tty
 
 
+def resolve_object_colors(mode: ObjectColorMode, *, color: bool) -> bool:
+    """Resolve whether NetBox-native object colors render.
+
+    Always gated by the global `color` resolution (no ANSI when color is off),
+    but can be disabled independently: OFF turns object colors off while status
+    coloring stays on; ON/AUTO follow `color`.
+
+    Contract: ON is deliberately *not* a force — it stays identical to AUTO so
+    that `--object-colors` (and `NSC_OBJECT_COLORS=on`) can never override the
+    no-color decision (`--no-color`, `NO_COLOR`, non-tty). Only OFF diverges.
+    """
+    if mode is ObjectColorMode.OFF:
+        return False
+    return color
+
+
 class RuntimeContext(BaseModel):
     """Per-invocation runtime state.
 
@@ -208,6 +225,7 @@ class RuntimeContext(BaseModel):
     compact: bool = False
     color: bool = False
     color_stderr: bool = False
+    object_colors: bool = False
     apply: bool = False
     explain: bool = False
     strict: bool = False

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/cli/tui_commands.py

@@ -41,6 +41,46 @@ def _save_columns(tag: str, resource: str, columns: list[str]) -> None:
         atomic_write(path, dump_round_trip(doc))
 
 
+def _save_search(tag: str, resource: str, name: str, params: dict[str, str]) -> None:
+    """Persist a filter set to ``saved_searches.<tag>.<resource>.<name>``."""
+    from nsc.config.saved_searches import validate_saved_search_name  # noqa: PLC0415
+    from nsc.config.settings import default_paths  # noqa: PLC0415
+    from nsc.config.writer import (  # noqa: PLC0415
+        acquire_lock,
+        atomic_write,
+        dump_round_trip,
+        load_round_trip,
+        set_path,
+    )
+
+    # Defensive: a dotted name would split into a nested map under set_path and
+    # corrupt the file. Validate before touching disk so the file is untouched.
+    validate_saved_search_name(name)
+    path = default_paths().config_file
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        set_path(doc, f"saved_searches.{tag}.{resource}.{name}", dict(params))
+        atomic_write(path, dump_round_trip(doc))
+
+
+def _delete_search(tag: str, resource: str, name: str) -> None:
+    """Remove ``saved_searches.<tag>.<resource>.<name>`` and prune empty parents."""
+    from nsc.config.settings import default_paths  # noqa: PLC0415
+    from nsc.config.writer import (  # noqa: PLC0415
+        acquire_lock,
+        atomic_write,
+        dump_round_trip,
+        load_round_trip,
+        unset_path,
+    )
+
+    path = default_paths().config_file
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        unset_path(doc, f"saved_searches.{tag}.{resource}.{name}")
+        atomic_write(path, dump_round_trip(doc))
+
+
 def register(app: typer.Typer) -> None:
     def tui(
         ctx: typer.Context,
@@ -54,12 +94,23 @@ def register(app: typer.Typer) -> None:
         from nsc.tui import run_tui  # noqa: PLC0415  # deferred: keeps Textual lazy.
 
         column_prefs = {tag: dict(resources) for tag, resources in runtime.config.columns.items()}
+        saved_searches = {
+            tag: {
+                res: {name: dict(params) for name, params in sets.items()}
+                for res, sets in resources.items()
+            }
+            for tag, resources in runtime.config.saved_searches.items()
+        }
         run_tui(
             runtime.command_model,
             runtime.client,
             initial_resource=resource,
             save_columns=_save_columns,
             column_prefs=column_prefs,
+            object_colors=runtime.object_colors,
+            saved_searches=saved_searches,
+            save_search=_save_search,
+            delete_search=_delete_search,
         )
 
     # `tui` is canonical; `interactive` and `i` are hidden aliases for the same

{netbox_super_cli-1.3.1 → netbox_super_cli-1.4.0}/nsc/config/models.py

@@ -37,6 +37,15 @@ class ColorMode(StrEnum):
     OFF = "off"
 
 
+class ObjectColorMode(StrEnum):
+    # Render NetBox-native hex colors (role/tag/…) independently of status
+    # coloring. Still gated by the global color resolution, so OFF never yields
+    # ANSI but ON/AUTO only color when color is otherwise enabled.
+    AUTO = "auto"
+    ON = "on"
+    OFF = "off"
+
+
 class AuditRedaction(StrEnum):
     # SAFE redacts only known secrets (passwords/tokens) in bodies; FULL omits
     # every body, leaving routing metadata only — stricter compliance, harder
@@ -51,6 +60,7 @@ class Defaults(_Frozen):
     timeout: float = 30.0
     schema_refresh: SchemaRefresh = SchemaRefresh.DAILY
     color_mode: ColorMode = ColorMode.AUTO
+    object_colors: ObjectColorMode = ObjectColorMode.AUTO
     audit_redaction: AuditRedaction = AuditRedaction.SAFE
 
 
@@ -68,3 +78,7 @@ class Config(_Frozen):
     profiles: dict[str, Profile] = Field(default_factory=dict)
     defaults: Defaults = Field(default_factory=Defaults)
     columns: dict[str, dict[str, list[str]]] = Field(default_factory=dict)
+    # Local, named filter sets keyed `<tag>.<resource>.<name> = {filter_key: value}`.
+    # The leaf dict is exactly a `FilterState.as_params()` payload so a saved search
+    # round-trips through the TUI filter screen and the CLI `--saved` flag alike.
+    saved_searches: dict[str, dict[str, dict[str, dict[str, str]]]] = Field(default_factory=dict)

netbox_super_cli-1.4.0/nsc/config/saved_searches.py

@@ -0,0 +1,54 @@
+"""Framework-free lookups over the `saved_searches` config mapping.
+
+Keeps saved-search resolution out of `cli/` and `tui/` so both surfaces share
+one implementation and the logic stays unit-testable without any I/O.
+"""
+
+from __future__ import annotations
+
+from nsc.config.models import Config
+
+_MIN_PRINTABLE = 0x20
+
+
+class InvalidSavedSearchName(ValueError):
+    """Raised when a saved-search name is unsafe to persist."""
+
+
+def validate_saved_search_name(name: str) -> None:
+    """Reject names that would corrupt config.yaml or surprise the user.
+
+    Saved searches are persisted at the dotted config path
+    ``saved_searches.<tag>.<resource>.<name>`` and the writer splits on ``.``,
+    so a name containing ``.`` would be written as a *nested map* rather than a
+    leaf — making the whole file fail ``Config.model_validate`` on the next run.
+    Control characters and surrounding whitespace are rejected for the same
+    "don't persist a name that won't round-trip cleanly" reason.
+    """
+    if not name or name != name.strip():
+        raise InvalidSavedSearchName(
+            "saved-search name must be non-empty and not start or end with whitespace"
+        )
+    if "." in name:
+        raise InvalidSavedSearchName(
+            f"saved-search name {name!r} may not contain '.' "
+            "(it is used as a config-path separator)"
+        )
+    if any((ch.isspace() and ch != " ") or ord(ch) < _MIN_PRINTABLE for ch in name):
+        raise InvalidSavedSearchName(
+            f"saved-search name {name!r} may not contain tabs, newlines, "
+            "or other control characters"
+        )
+
+
+def get_saved_search(config: Config, tag: str, resource: str, name: str) -> dict[str, str] | None:
+    """The stored filter params for `<tag>.<resource>.<name>`, or None if absent."""
+    params = config.saved_searches.get(tag, {}).get(resource, {}).get(name)
+    if params is None:
+        return None
+    return dict(params)
+
+
+def list_saved_searches(config: Config, tag: str, resource: str) -> list[str]:
+    """Sorted names of saved searches for `<tag>.<resource>` (empty if none)."""
+    return sorted(config.saved_searches.get(tag, {}).get(resource, {}))

netbox_super_cli-1.4.0/nsc/output/colors.py

@@ -0,0 +1,36 @@
+"""Framework-free value object + helper for NetBox-native hex colors.
+
+NetBox FK/choice objects (roles, tags, …) carry a sibling ``color`` field — a
+6-hex string (no leading ``#``) the web UI uses to tint the badge. The table and
+TUI formatters preserve it by emitting a :class:`ColoredValue` instead of a bare
+display string. This module imports nothing from cli/http/rich so it stays usable
+by any formatter.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_HEX = re.compile(r"\A[0-9a-fA-F]{6}\Z")
+
+
+@dataclass(frozen=True)
+class ColoredValue:
+    text: str
+    color: str | None
+
+
+def normalize_hex(raw: object) -> str | None:
+    """Return a lowercased 6-hex color (no leading ``#``) or ``None``.
+
+    Accepts an optional leading ``#``. Anything that is not a string of exactly
+    six hex digits (after stripping one leading ``#``) — including ``None``,
+    non-strings, empty strings, and wrong lengths — yields ``None``.
+    """
+    if not isinstance(raw, str):
+        return None
+    candidate = raw[1:] if raw.startswith("#") else raw
+    if _HEX.match(candidate):
+        return candidate.lower()
+    return None