vcf-super-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ versions may include breaking changes.
 
 ## [Unreleased]
 
+## v0.5.0 — 2026-06-08
+
+Find VMs by attribute. Answers the everyday *"which VM has `10.20.3.41`?"* — a
+reverse lookup the REST `vm list` filter can't do, because guest networking lives
+only on the pyVmomi `guest.*` properties.
+
+### Added
+
+- **`vsc vsphere inventory find`** (#54) — locate VMs by guest/runtime attribute
+  without knowing the moid: `--ip` (exact or CIDR, IPv4/IPv6, across the primary and
+  every NIC address), `--name`, `--hostname`, `--guest-os` (case-insensitive
+  substring or glob), `--mac` (exact), and `--power-state`. Flags **AND** together; a
+  repeated flag **ORs** within its field; at least one match flag is required (it
+  refuses to dump the whole inventory). `--props` (repeatable) widens each hit's
+  output only — never a match criterion. One PropertyCollector round-trip over a
+  container view (always destroyed); a pure, pyVmomi-free matcher does the filtering.
+  Reads only — no `--apply` — and emits the same JSON / error envelope / exit codes
+  as the other pyVmomi fallback commands.
+
 ## v0.4.0 — 2026-06-08
 
 Live resource-id completion. Pressing `<TAB>` on an id-typed argument can now

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vcf-super-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Modern, agent-friendly CLI for VMware Cloud Foundation 9, with a command tree generated dynamically from the vcf-sdk vAPI bindings.
 Project-URL: Homepage, https://github.com/thomaschristory/vcf-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/vcf-super-cli/
@@ -74,7 +74,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
-| Live resource-id completion | planned |
+| Live resource-id completion | ✅ v0.4 |
+| Find VMs by attribute — IP / hostname / MAC / guest OS / power (`vsc vsphere inventory find`) | ✅ v0.5 |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/README.md

@@ -42,7 +42,8 @@ $ vsc vsphere power stop vm-42 --apply        # writes are dry-run without --app
 | NSX **Policy API** read (`vsc nsx …`) | ✅ v0.1 |
 | Writes — dry-run by default + `--apply` (`vsc vsphere …` / `vsc nsx …`) | ✅ v0.2 |
 | Ergonomics — offline shell completion, per-field filter flags + paging, pyVmomi fallback (`perf`/`events`/`tasks`/`inventory`) | ✅ v0.3 |
-| Live resource-id completion | planned |
+| Live resource-id completion | ✅ v0.4 |
+| Find VMs by attribute — IP / hostname / MAC / guest OS / power (`vsc vsphere inventory find`) | ✅ v0.5 |
 | NSX Manager / Global-Manager, SDDC Manager, Operations, LCM | deferred |
 
 ## Install

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/docs/commands.md

@@ -51,6 +51,17 @@ API. Those commands live under `vsc vsphere` alongside the generated ones, are
   managed-object properties the REST list ops omit (device tree, custom attributes),
   via the PropertyCollector. `--props` is repeatable (e.g. `--props config.hardware`);
   with none, a small per-type summary set is returned.
+- `vsc vsphere inventory find [--ip …] [--name …] [--hostname …] [--mac …] [--guest-os …] [--power-state …] [--props …]`
+  — **find VMs by guest/runtime attribute without knowing the moid.** This is the
+  answer to *"which VM has `10.20.3.41`?"*: guest networking isn't in the REST
+  `vm list` filter, so this sweeps every VM's `guest.*` properties in one round-trip.
+  `--ip` accepts an exact address or a CIDR (`10.20.3.0/24`, IPv4 or IPv6) and matches
+  across the primary and every NIC address; `--name`/`--hostname`/`--guest-os` are
+  case-insensitive substring or glob; `--mac` is exact; `--power-state` is one of
+  `poweredOn`/`poweredOff`/`suspended`. Flags **AND** together, a repeated flag **ORs**
+  within its field, and at least one match flag is required. `--props` (repeatable)
+  widens each hit's output only — it never affects matching. Powered-off VMs and those
+  without VMware Tools report no guest IP and won't match `--ip`.
 
 ## `vsc nsx …` (NSX Policy)
 

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/docs/design.md

@@ -68,8 +68,11 @@ SOAP API. Those are **hand-written read-only commands** mounted under
   and exit codes (`vsc/pyvmomi/runner.py`).
 
 Commands: `perf` (PerformanceManager counters), `events` / `tasks`
-(Event/Task managers), and `inventory` (a PropertyCollector property walk). All
-are reads — no `--apply`.
+(Event/Task managers), and `inventory` — a PropertyCollector property walk
+(`inventory vm`/`host`) plus `inventory find`, which sweeps every VM's `guest.*`
+properties in one round-trip to locate a VM by IP / name / hostname / MAC / guest
+OS / power state (the fields the REST `vm list` filter can't reach). All are
+reads — no `--apply`.
 
 ## Design specs
 
@@ -78,6 +81,7 @@ The authoritative, milestone-by-milestone designs live in the repository:
 - [v0.1 — dynamic read-only CLI](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-design.md)
 - [v0.2 — writes](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.2-writes-design.md)
 - [v0.3 — ergonomics](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-05-vcf-super-cli-v0.3-ergonomics-design.md)
+- [v0.5 — find VMs by attribute](https://github.com/thomaschristory/vcf-super-cli/blob/main/docs/superpowers/specs/2026-06-08-vcf-super-cli-v0.5-find-vms-design.md)
 
 ## Contracts
 

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/docs/index.md

@@ -19,11 +19,13 @@ $ vsc vsphere perf vm vm-42 --metric cpu.usage
 
 - **Mirrors the real API** — commands come from the SDK's vAPI metadata, covering
   vCenter and NSX from one generator.
-- **Ergonomic** — offline tab-completion (enums, formats, profiles, filter
-  choices), per-field `--<field>` filter flags, and paging (`--all` /
-  `--max-items` / `--limit`).
+- **Ergonomic** — tab-completion (enums, formats, profiles, filter choices, and
+  opt-in [live resource ids](usage.md#live-resource-id-completion-opt-in)),
+  per-field `--<field>` filter flags, and paging (`--all` / `--max-items` /
+  `--limit`).
 - **pyVmomi fallback** — read-only `perf`, `events`, `tasks`, and `inventory`
-  commands for areas the REST/vAPI surface doesn't cover.
+  commands for areas the REST/vAPI surface doesn't cover, including
+  `inventory find` to locate a VM by IP / hostname / MAC / guest OS.
 - **Safe by default** — writes are dry-run unless `--apply`; a dry-run never connects.
 - **Agent-friendly** — JSON output, stable error envelope, documented exit codes,
   bundled agent Skill.

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/docs/profiles.md

@@ -56,6 +56,10 @@ VSC_PROFILE=prod vsc nsx segments list
 | `VSC_VSPHERE_INSECURE` / `VSC_NSX_INSECURE` | `1`/`true` to skip TLS verification (lab/self-signed) |
 | `VSC_CONFIG_FILE` | Override the config file location |
 | `VSC_LOG_LEVEL` | Log level on stderr (default `WARNING`) |
+| `VSC_COMPLETE_DYNAMIC` | `1`/`true` to enable [live resource-id completion](usage.md#live-resource-id-completion-opt-in) (off by default) |
+| `VSC_COMPLETE_TTL` | Live-completion cache TTL in seconds (default `60`) |
+| `VSC_COMPLETE_TIMEOUT` | Hard timeout for a live-completion fetch in seconds (default `2`) |
+| `VSC_CACHE_DIR` | Override the cache directory (where live-completion results are cached) |
 
 !!! warning "TLS"
     Verification is **on by default**. Only set `VSC_*_INSECURE` (or

vcf_super_cli-0.5.0/docs/superpowers/specs/2026-06-08-vcf-super-cli-v0.5-find-vms-design.md

@@ -0,0 +1,78 @@
+# v0.5 — find VMs by attribute
+
+**Milestone:** v0.5 — find VMs · **Issue:** #54 · **Date:** 2026-06-08
+
+## Problem
+
+You can `vsc vsphere vm list` and filter on what the vAPI `VM.FilterSpec` exposes
+(names, power states, hosts, clusters, datacenters, folders, resource pools).
+None of the **guest/runtime network fields** are filterable there, so the everyday
+question *"which VM has `10.20.3.41`?"* is unanswerable from the CLI. Guest
+networking lives only on the pyVmomi `guest.*` properties; the per-VM REST guest
+API needs the moid first, useless for a reverse lookup.
+
+## Command
+
+```
+vsc vsphere inventory find [--ip ...] [--name ...] [--hostname ...] [--mac ...]
+                           [--guest-os ...] [--power-state ...] [--props ...] [-o ...]
+```
+
+Third command under `inventory_app`, next to `vm`/`host`. VM-focused for v1.
+
+### Match semantics
+
+- Flags **AND** together; a repeated flag **ORs** within that field.
+- `--ip` matches any address across `guest.ipAddress` + every `guest.net[].ipAddress`,
+  as an **exact IP or CIDR** via stdlib `ipaddress` (IPv4 and IPv6). An exact IP is
+  just a `/32` (or `/128`) network, so one code path covers both.
+- `--name`, `--hostname`, `--guest-os` are case-insensitive **substring**, or
+  **glob** when the pattern has `*?[`. `--name` is fully client-side (one matcher).
+- `--mac` exact, case-insensitive, against `guest.net[].macAddress`.
+- `--power-state` ∈ {poweredOn, poweredOff, suspended} against `runtime.powerState`.
+- **No match flag → usage error** (exit 2); we refuse to dump the whole inventory.
+  `--props`/`-o` alone do not count.
+
+### `--props` passthrough (output only)
+
+Repeatable; mirrors `inventory vm --props`. Appends arbitrary property paths to the
+single PropertyCollector retrieve so each **matched** VM also surfaces them under a
+`properties` sub-dict — bridging search→inspect in one call. Never a match criterion.
+
+## Implementation
+
+`vsc/pyvmomi/find.py`:
+
+- **Pure matcher** (`Criteria`, `matches`, `summarize`, `validate_criteria`, plus
+  `_ip_match`/`_text_match`/`_addresses`/`_macs`) — operates only on a plain
+  props dict, no pyVmomi import in the hot path, so it unit-tests in isolation.
+- **One round-trip** (`find_matches` → `_retrieve_all_vms`): a
+  `CreateContainerView(rootFolder, [vim.VirtualMachine], recursive=True)` plus a
+  single `RetrieveContents` with a `TraversalSpec` pulling the fixed search paths
+  **plus** any `--props`. The container view is **always destroyed** in a `finally`.
+
+`vsc/pyvmomi/inventory.py` adds the thin `find` command: builds `Criteria` from the
+flags, rejects an empty criteria set and malformed `--ip`/`--power-state` as usage
+errors, and emits through the shared `run_read` runner (same JSON / error envelope /
+exit codes as the other pyVmomi reads).
+
+### Per-hit shape
+
+```json
+{ "obj": {"type": "VirtualMachine", "value": "vm-101"},
+  "name": "web-1", "power_state": "poweredOn",
+  "ip_addresses": ["10.20.3.41"], "hostname": "web-1.corp",
+  "guest_os": "Ubuntu Linux (64-bit)",
+  "properties": { "config.version": "vmx-19" } }   // only with --props
+```
+
+No matches → empty array, exit 0.
+
+## Scope / non-goals (v1)
+
+- vSphere/pyVmomi only; NSX has its own search surface.
+- VMs only (no host/network/datastore search yet).
+- Single `RetrieveContents` (no paging). Very large inventories may later want
+  `RetrievePropertiesEx` + `maxObjects` paging — a scaling follow-up.
+- VMs without VMware Tools / powered-off report no (or stale) guest IP and won't
+  match `--ip`; expected, noted in the docs.

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vcf-super-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Modern, agent-friendly CLI for VMware Cloud Foundation 9, with a command tree generated dynamically from the vcf-sdk vAPI bindings."
 readme = "README.md"
 requires-python = ">=3.12"

vcf_super_cli-0.5.0/tests/test_pyvmomi_find.py

@@ -0,0 +1,342 @@
+"""`vsc vsphere inventory find` — pure matcher + container-view retrieval + CLI."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+import typer
+from pyVmomi import vim, vmodl
+from typer.testing import CliRunner
+
+from vsc.pyvmomi.find import (
+    Criteria,
+    find_matches,
+    matches,
+    summarize,
+    validate_criteria,
+)
+from vsc.pyvmomi.inventory import inventory_app
+
+runner = CliRunner()
+
+
+# --------------------------------------------------------------------------- #
+# props-dict fixtures (the matcher only ever sees plain dicts)
+# --------------------------------------------------------------------------- #
+
+
+def _props(
+    *,
+    name: str = "web-1",
+    power: str = "poweredOn",
+    primary_ip: str | None = "10.20.3.41",
+    nics: list[dict[str, Any]] | None = None,
+    hostname: str | None = "web-1.corp",
+    guest_os: str | None = "Ubuntu Linux (64-bit)",
+) -> dict[str, Any]:
+    props: dict[str, Any] = {"name": name, "runtime.powerState": power}
+    if primary_ip is not None:
+        props["guest.ipAddress"] = primary_ip
+    if nics is not None:
+        props["guest.net"] = nics
+    if hostname is not None:
+        props["guest.hostName"] = hostname
+    if guest_os is not None:
+        props["guest.guestFullName"] = guest_os
+    return props
+
+
+# --------------------------------------------------------------------------- #
+# matcher — IP
+# --------------------------------------------------------------------------- #
+
+
+def test_match_exact_ip() -> None:
+    assert matches(_props(), Criteria(ip=("10.20.3.41",)))
+    assert not matches(_props(), Criteria(ip=("10.20.3.42",)))
+
+
+def test_match_cidr() -> None:
+    assert matches(_props(), Criteria(ip=("10.20.3.0/24",)))
+    assert not matches(_props(), Criteria(ip=("10.20.4.0/24",)))
+
+
+def test_match_ipv6() -> None:
+    props = _props(primary_ip=None, nics=[{"ipAddress": ["fe80::1", "2001:db8::5"]}])
+    assert matches(props, Criteria(ip=("2001:db8::5",)))
+    assert matches(props, Criteria(ip=("2001:db8::/32",)))
+    assert not matches(props, Criteria(ip=("2001:dead::/32",)))
+
+
+def test_match_ip_across_multiple_nics() -> None:
+    props = _props(
+        primary_ip="10.0.0.1",
+        nics=[{"ipAddress": ["10.0.0.1"]}, {"ipAddress": ["192.168.5.9"]}],
+    )
+    assert matches(props, Criteria(ip=("192.168.5.9",)))
+
+
+def test_no_tools_vm_has_no_ip() -> None:
+    bare = {"name": "db-1", "runtime.powerState": "poweredOff"}
+    assert not matches(bare, Criteria(ip=("10.20.3.41",)))
+
+
+def test_ip_or_within_field() -> None:
+    # Repeated --ip is OR: the VM only needs one of them.
+    assert matches(_props(), Criteria(ip=("10.0.0.9", "10.20.3.41")))
+
+
+def test_garbage_guest_address_does_not_crash() -> None:
+    props = _props(primary_ip="not-an-ip", nics=[{"ipAddress": ["10.20.3.41"]}])
+    assert matches(props, Criteria(ip=("10.20.3.41",)))
+
+
+def test_ip_family_mismatch_is_no_match_not_crash() -> None:
+    # An IPv6 pattern against an IPv4-only guest must simply not match — the
+    # stdlib membership test short-circuits on version, so no exception leaks.
+    assert not matches(_props(primary_ip="10.20.3.41"), Criteria(ip=("2001:db8::1",)))
+    assert not matches(_props(primary_ip="10.20.3.41"), Criteria(ip=("2001:db8::/32",)))
+
+
+# --------------------------------------------------------------------------- #
+# matcher — text / mac / power
+# --------------------------------------------------------------------------- #
+
+
+def test_name_substring_case_insensitive() -> None:
+    assert matches(_props(name="PROD-web-1"), Criteria(name=("web",)))
+
+
+def test_name_glob() -> None:
+    assert matches(_props(name="web-prod-1"), Criteria(name=("web-*-1",)))
+    assert not matches(_props(name="web-prod-2"), Criteria(name=("web-*-1",)))
+
+
+def test_hostname_and_guest_os_match() -> None:
+    assert matches(_props(), Criteria(hostname=("corp",)))
+    assert matches(_props(), Criteria(guest_os=("ubuntu",)))
+
+
+def test_mac_exact_case_insensitive() -> None:
+    props = _props(nics=[{"macAddress": "00:50:56:AA:BB:CC"}])
+    assert matches(props, Criteria(mac=("00:50:56:aa:bb:cc",)))
+    assert not matches(props, Criteria(mac=("00:50:56:aa:bb:cd",)))
+
+
+def test_power_state_match() -> None:
+    assert matches(_props(power="poweredOff"), Criteria(power_state=("poweredOff",)))
+    assert not matches(_props(power="poweredOn"), Criteria(power_state=("poweredOff",)))
+
+
+# --------------------------------------------------------------------------- #
+# matcher — AND across fields, no-match
+# --------------------------------------------------------------------------- #
+
+
+def test_and_across_fields() -> None:
+    crit = Criteria(ip=("10.20.3.41",), power_state=("poweredOn",), name=("web",))
+    assert matches(_props(), crit)
+    # One failing field fails the whole match (AND).
+    assert not matches(_props(power="poweredOff"), crit)
+
+
+def test_no_match_returns_false() -> None:
+    assert not matches(_props(), Criteria(name=("does-not-exist",)))
+
+
+# --------------------------------------------------------------------------- #
+# Criteria / validation
+# --------------------------------------------------------------------------- #
+
+
+def test_is_empty() -> None:
+    assert Criteria().is_empty
+    assert not Criteria(ip=("10.0.0.1",)).is_empty
+
+
+def test_validate_rejects_bad_ip() -> None:
+    with pytest.raises(ValueError, match="invalid --ip"):
+        validate_criteria(Criteria(ip=("999.1.1.1",)))
+
+
+def test_validate_rejects_bad_power_state() -> None:
+    with pytest.raises(ValueError, match="invalid --power-state"):
+        validate_criteria(Criteria(power_state=("on",)))
+
+
+def test_validate_accepts_cidr_and_exact() -> None:
+    validate_criteria(Criteria(ip=("10.20.3.0/24", "10.20.3.41"), power_state=("poweredOn",)))
+
+
+# --------------------------------------------------------------------------- #
+# summarize
+# --------------------------------------------------------------------------- #
+
+
+def test_summarize_shape_and_extra_props() -> None:
+    props = _props(nics=[{"ipAddress": ["10.20.3.41", "fe80::1"]}])
+    props["config.hardware.numCPU"] = 4
+    hit = summarize({"type": "VirtualMachine", "value": "vm-1"}, props, ["config.hardware.numCPU"])
+    assert hit["name"] == "web-1"
+    assert hit["power_state"] == "poweredOn"
+    assert "10.20.3.41" in hit["ip_addresses"]
+    assert hit["hostname"] == "web-1.corp"
+    assert hit["properties"] == {"config.hardware.numCPU": 4}
+
+
+def test_summarize_no_extra_props_omits_properties_key() -> None:
+    hit = summarize({"type": "VirtualMachine", "value": "vm-1"}, _props(), [])
+    assert "properties" not in hit
+
+
+# --------------------------------------------------------------------------- #
+# retrieval over a mocked PropertyCollector (single round-trip, view destroyed)
+# --------------------------------------------------------------------------- #
+
+
+def _object_content(moid: str, **props: Any) -> Any:
+    return vmodl.query.PropertyCollector.ObjectContent(
+        obj=vim.VirtualMachine(moid, None),
+        propSet=[vmodl.DynamicProperty(name=k, val=v) for k, v in props.items()],
+    )
+
+
+class _RecStub:
+    """Records managed-method invocations so we can assert the view was destroyed."""
+
+    def __init__(self) -> None:
+        self.destroyed = False
+
+    def InvokeMethod(self, *args: Any, **kwargs: Any) -> None:
+        self.destroyed = True  # ContainerView.Destroy() is the only call we make
+
+
+class _FakeView:
+    """A real ContainerView (so ObjectSpec.obj type-checks) over a recording stub."""
+
+    def __init__(self) -> None:
+        self.stub = _RecStub()
+        self.view = vim.view.ContainerView("view-1", self.stub)
+
+    @property
+    def destroyed(self) -> bool:
+        return self.stub.destroyed
+
+
+class _FakeViewManager:
+    def __init__(self, view: _FakeView) -> None:
+        self._view = view
+
+    def CreateContainerView(self, container: Any, type_: Any, recursive: Any) -> Any:
+        return self._view.view
+
+
+class _FakePC:
+    def __init__(self, contents: list[Any]) -> None:
+        self.contents = contents
+        self.calls = 0
+        self.captured: Any = None
+
+    def RetrieveContents(self, specSet: Any) -> list[Any]:
+        self.calls += 1
+        self.captured = specSet
+        return self.contents
+
+
+def _fake_si(pc: _FakePC, view: _FakeView) -> Any:
+    content = type(
+        "C",
+        (),
+        {
+            "propertyCollector": pc,
+            "viewManager": _FakeViewManager(view),
+            "rootFolder": object(),
+        },
+    )()
+    return type("SI", (), {"content": content, "_stub": object()})()
+
+
+def test_find_matches_single_round_trip_and_destroys_view() -> None:
+    contents = [
+        _object_content("vm-1", **{"name": "web-1", "guest.ipAddress": "10.20.3.41"}),
+        _object_content("vm-2", **{"name": "db-1", "guest.ipAddress": "10.20.9.9"}),
+    ]
+    pc, view = _FakePC(contents), _FakeView()
+    hits = find_matches(_fake_si(pc, view), Criteria(ip=("10.20.3.41",)), [])
+    assert pc.calls == 1  # one RetrieveContents for the whole inventory
+    assert view.destroyed  # container view torn down in finally
+    assert [h["obj"]["value"] for h in hits] == ["vm-1"]
+
+
+def test_find_matches_appends_extra_props_to_path_set() -> None:
+    pc, view = _FakePC([]), _FakeView()
+    find_matches(_fake_si(pc, view), Criteria(name=("x",)), ["config.hardware.numCPU"])
+    path_set = pc.captured[0].propSet[0].pathSet
+    assert "config.hardware.numCPU" in path_set
+    assert "guest.net" in path_set  # fixed search paths still present
+    assert path_set.count("config.hardware.numCPU") == 1  # deduped
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+
+def _app() -> typer.Typer:
+    app = typer.Typer()
+    app.add_typer(inventory_app, name="inventory")
+    return app
+
+
+def test_find_cli_by_ip(monkeypatch: pytest.MonkeyPatch) -> None:
+    contents = [_object_content("vm-1", **{"name": "web-1", "guest.ipAddress": "10.20.3.41"})]
+    pc, view = _FakePC(contents), _FakeView()
+    monkeypatch.setattr("vsc.pyvmomi.runner.connect_vmomi", lambda: _fake_si(pc, view))
+    result = runner.invoke(_app(), ["inventory", "find", "--ip", "10.20.3.41"])
+    assert result.exit_code == 0, result.stdout
+    out = json.loads(result.stdout)
+    assert out[0]["obj"]["value"] == "vm-1"
+    assert out[0]["ip_addresses"] == ["10.20.3.41"]
+
+
+def test_find_cli_with_props(monkeypatch: pytest.MonkeyPatch) -> None:
+    contents = [
+        _object_content(
+            "vm-1",
+            **{"name": "web-1", "guest.ipAddress": "10.20.3.41", "config.version": "vmx-19"},
+        )
+    ]
+    pc, view = _FakePC(contents), _FakeView()
+    monkeypatch.setattr("vsc.pyvmomi.runner.connect_vmomi", lambda: _fake_si(pc, view))
+    result = runner.invoke(
+        _app(), ["inventory", "find", "--name", "web", "--props", "config.version"]
+    )
+    assert result.exit_code == 0, result.stdout
+    out = json.loads(result.stdout)
+    assert out[0]["properties"] == {"config.version": "vmx-19"}
+
+
+def test_find_cli_no_match_flag_is_usage_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    pc, view = _FakePC([]), _FakeView()
+    monkeypatch.setattr("vsc.pyvmomi.runner.connect_vmomi", lambda: _fake_si(pc, view))
+    # --props alone does not count as a match flag.
+    result = runner.invoke(_app(), ["inventory", "find", "--props", "config.version"])
+    assert result.exit_code == 2, result.stdout
+    assert pc.calls == 0  # refused before any retrieve
+
+
+def test_find_cli_bad_ip_is_usage_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    pc, view = _FakePC([]), _FakeView()
+    monkeypatch.setattr("vsc.pyvmomi.runner.connect_vmomi", lambda: _fake_si(pc, view))
+    result = runner.invoke(_app(), ["inventory", "find", "--ip", "999.1.1.1"])
+    assert result.exit_code == 2, result.stdout
+
+
+def test_find_cli_no_matches_empty_array(monkeypatch: pytest.MonkeyPatch) -> None:
+    pc, view = _FakePC([]), _FakeView()
+    monkeypatch.setattr("vsc.pyvmomi.runner.connect_vmomi", lambda: _fake_si(pc, view))
+    result = runner.invoke(_app(), ["inventory", "find", "--ip", "10.20.3.41"])
+    assert result.exit_code == 0, result.stdout
+    assert json.loads(result.stdout) == []

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/uv.lock

@@ -1326,7 +1326,7 @@ wheels = [
 
 [[package]]
 name = "vcf-super-cli"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "keyring" },

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/vsc/_version.py

@@ -4,4 +4,4 @@
 Keep this in sync with `[project].version` in `pyproject.toml`.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

vcf_super_cli-0.5.0/vsc/pyvmomi/find.py

@@ -0,0 +1,187 @@
+"""Find VMs by guest/runtime attribute (IP, name, hostname, MAC, guest OS, power).
+
+The REST ``VM.FilterSpec`` exposes none of the guest-network fields, so "which VM
+has ``10.20.3.41``?" is unanswerable there. Those fields only live on the pyVmomi
+``guest.*`` properties, so this is a single ``PropertyCollector`` sweep over every
+VM (one round-trip via a container view) plus a **pure matcher** that decides which
+hits to keep. The matcher takes a plain props dict — no pyVmomi — so it unit-tests
+in isolation; only :func:`find_matches` touches SOAP.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import ipaddress
+from dataclasses import dataclass
+from typing import Any
+
+from pyVmomi import vim, vmodl
+
+from vsc.connect.vmomi import vmomi_jsonable
+
+# Fixed property paths the matcher inspects, retrieved for every VM. ``--props``
+# paths are appended to this set (output only) — never a match criterion.
+SEARCH_PATHS: tuple[str, ...] = (
+    "name",
+    "runtime.powerState",
+    "guest.ipAddress",
+    "guest.net",
+    "guest.hostName",
+    "guest.guestFullName",
+)
+POWER_STATES = frozenset({"poweredOn", "poweredOff", "suspended"})
+_GLOB_CHARS = frozenset("*?[")
+
+
+@dataclass(frozen=True)
+class Criteria:
+    """One value per match flag; repeated flags arrive as multiple entries.
+
+    Fields **AND** together (every non-empty field must match); values within a
+    field **OR** (any one is enough). ``--props``/``-o`` are not represented here —
+    they never participate in matching.
+    """
+
+    ip: tuple[str, ...] = ()
+    name: tuple[str, ...] = ()
+    hostname: tuple[str, ...] = ()
+    mac: tuple[str, ...] = ()
+    guest_os: tuple[str, ...] = ()
+    power_state: tuple[str, ...] = ()
+
+    @property
+    def is_empty(self) -> bool:
+        """True when no match flag was given (we refuse to dump the whole inventory)."""
+        return not (
+            self.ip or self.name or self.hostname or self.mac or self.guest_os or self.power_state
+        )
+
+
+def validate_criteria(criteria: Criteria) -> None:
+    """Raise ``ValueError`` for malformed input so it surfaces as a usage error."""
+    for value in criteria.ip:
+        try:
+            ipaddress.ip_network(value, strict=False)
+        except ValueError as exc:
+            raise ValueError(f"invalid --ip {value!r} (expected an address or CIDR)") from exc
+    bad = [state for state in criteria.power_state if state not in POWER_STATES]
+    if bad:
+        allowed = ", ".join(sorted(POWER_STATES))
+        raise ValueError(f"invalid --power-state {bad[0]!r} (one of: {allowed})")
+
+
+def _addresses(props: dict[str, Any]) -> list[str]:
+    """All guest IPs: the primary ``guest.ipAddress`` plus every NIC address, deduped."""
+    out: list[str] = []
+    primary = props.get("guest.ipAddress")
+    if isinstance(primary, str):
+        out.append(primary)
+    for nic in props.get("guest.net") or []:
+        for addr in (nic.get("ipAddress") if isinstance(nic, dict) else None) or []:
+            if isinstance(addr, str):
+                out.append(addr)
+    # Preserve order, drop duplicates (primary often repeats a NIC address).
+    return list(dict.fromkeys(out))
+
+
+def _macs(props: dict[str, Any]) -> list[str]:
+    """MAC addresses across every NIC in ``guest.net``."""
+    return [
+        nic["macAddress"]
+        for nic in props.get("guest.net") or []
+        if isinstance(nic, dict) and isinstance(nic.get("macAddress"), str)
+    ]
+
+
+def _text_match(value: Any, pattern: str) -> bool:
+    """Case-insensitive substring match, or glob when the pattern has metachars."""
+    if not isinstance(value, str):
+        return False
+    haystack, needle = value.lower(), pattern.lower()
+    if _GLOB_CHARS & set(needle):
+        return fnmatch.fnmatchcase(haystack, needle)
+    return needle in haystack
+
+
+def _ip_match(addresses: list[str], pattern: str) -> bool:
+    """True if any guest address falls within ``pattern`` (exact IP or CIDR)."""
+    try:
+        network = ipaddress.ip_network(pattern, strict=False)
+    except ValueError:
+        return False
+    for addr in addresses:
+        try:
+            if ipaddress.ip_address(addr) in network:
+                return True
+        except ValueError:
+            continue  # zone-scoped/garbage guest address — skip, don't crash
+    return False
+
+
+def _mac_match(props: dict[str, Any], wanted: tuple[str, ...]) -> bool:
+    have = {mac.lower() for mac in _macs(props)}
+    return any(p.lower() in have for p in wanted)
+
+
+def matches(props: dict[str, Any], criteria: Criteria) -> bool:
+    """Decide whether one VM's properties satisfy every criterion (AND of ORs).
+
+    Each field that was given must match at least one of its values; a field left
+    unset imposes no constraint. ``all`` over the per-field results yields the AND.
+    """
+    return all(
+        (
+            not criteria.power_state or props.get("runtime.powerState") in criteria.power_state,
+            not criteria.name or any(_text_match(props.get("name"), p) for p in criteria.name),
+            not criteria.hostname
+            or any(_text_match(props.get("guest.hostName"), p) for p in criteria.hostname),
+            not criteria.guest_os
+            or any(_text_match(props.get("guest.guestFullName"), p) for p in criteria.guest_os),
+            not criteria.mac or _mac_match(props, criteria.mac),
+            not criteria.ip or any(_ip_match(_addresses(props), p) for p in criteria.ip),
+        )
+    )
+
+
+def summarize(obj: Any, props: dict[str, Any], extra_props: list[str]) -> dict[str, Any]:
+    """Shape one matched VM into a directly-useful summary (pipes into ``vm get``)."""
+    hit: dict[str, Any] = {
+        "obj": obj,
+        "name": props.get("name"),
+        "power_state": props.get("runtime.powerState"),
+        "ip_addresses": _addresses(props),
+        "hostname": props.get("guest.hostName"),
+        "guest_os": props.get("guest.guestFullName"),
+    }
+    if extra_props:
+        hit["properties"] = {path: props.get(path) for path in extra_props}
+    return hit
+
+
+def _retrieve_all_vms(si: Any, paths: list[str]) -> list[Any]:
+    """One ``RetrieveContents`` over every VM via a container view (destroyed after)."""
+    content = si.content
+    view = content.viewManager.CreateContainerView(content.rootFolder, [vim.VirtualMachine], True)
+    try:
+        pc = vmodl.query.PropertyCollector
+        traversal = pc.TraversalSpec(
+            name="toVm", type=vim.view.ContainerView, path="view", skip=False
+        )
+        obj_spec = pc.ObjectSpec(obj=view, skip=True, selectSet=[traversal])
+        prop_spec = pc.PropertySpec(type=vim.VirtualMachine, pathSet=paths, all=False)
+        filter_spec = pc.FilterSpec(objectSet=[obj_spec], propSet=[prop_spec])
+        return content.propertyCollector.RetrieveContents(specSet=[filter_spec]) or []
+    finally:
+        view.Destroy()
+
+
+def find_matches(si: Any, criteria: Criteria, extra_props: list[str]) -> list[dict[str, Any]]:
+    """Sweep all VMs once, keep those satisfying ``criteria``, shape each hit."""
+    # Fixed search paths first, then any output-only --props (deduped, order kept).
+    paths = list(dict.fromkeys([*SEARCH_PATHS, *extra_props]))
+    out: list[dict[str, Any]] = []
+    for content in _retrieve_all_vms(si, paths):
+        props = {dp.name: vmomi_jsonable(dp.val) for dp in (content.propSet or [])}
+        if matches(props, criteria):
+            out.append(summarize(vmomi_jsonable(content.obj), props, extra_props))
+    return out

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/vsc/pyvmomi/inventory.py

@@ -15,6 +15,7 @@ from pyVmomi import vim, vmodl
 from vsc.connect.vmomi import vmomi_jsonable
 from vsc.gen.complete import output_format_completer
 from vsc.output.render import OutputFormat
+from vsc.pyvmomi.find import Criteria, find_matches, validate_criteria
 from vsc.pyvmomi.runner import run_read
 
 inventory_app = typer.Typer(no_args_is_help=True, help="Property walk (pyVmomi fallback).")
@@ -89,3 +90,62 @@ def inventory_host(
 ) -> None:
     """Retrieve properties of an ESXi host."""
     _run(host, "host", props or _DEFAULT_PROPS["host"], output.value)
+
+
+_FIND_PROPS_HELP = "Extra property to surface per hit (repeatable). Output only — never matches."
+
+
+@inventory_app.command("find")
+def inventory_find(
+    ip: list[str] = typer.Option(
+        None, "--ip", help="Guest IP, exact or CIDR (e.g. 10.20.3.41 or 10.20.3.0/24). Repeatable."
+    ),
+    name: list[str] = typer.Option(
+        None, "--name", help="VM name, substring or glob (case-insensitive). Repeatable."
+    ),
+    hostname: list[str] = typer.Option(
+        None, "--hostname", help="Guest hostname, substring or glob. Repeatable."
+    ),
+    mac: list[str] = typer.Option(
+        None, "--mac", help="NIC MAC address, exact (case-insensitive). Repeatable."
+    ),
+    guest_os: list[str] = typer.Option(
+        None, "--guest-os", help="Guest OS name, substring or glob. Repeatable."
+    ),
+    power_state: list[str] = typer.Option(
+        None, "--power-state", help="poweredOn | poweredOff | suspended. Repeatable."
+    ),
+    props: list[str] = typer.Option(None, "--props", help=_FIND_PROPS_HELP),
+    output: OutputFormat = typer.Option(
+        OutputFormat.json,
+        "--output",
+        "-o",
+        help="Output format.",
+        autocompletion=output_format_completer(),
+    ),
+) -> None:
+    """Find VMs by guest/runtime attribute, without knowing the moid.
+
+    Flags AND together; repeat a flag to OR within that field. At least one match
+    flag is required (--props/-o alone do not count). Powered-off VMs and those
+    without VMware Tools report no guest IP and won't match --ip.
+    """
+
+    def build(si: Any) -> list[dict[str, Any]]:
+        criteria = Criteria(
+            ip=tuple(ip or ()),
+            name=tuple(name or ()),
+            hostname=tuple(hostname or ()),
+            mac=tuple(mac or ()),
+            guest_os=tuple(guest_os or ()),
+            power_state=tuple(power_state or ()),
+        )
+        if criteria.is_empty:
+            raise ValueError(
+                "give at least one match flag "
+                "(--ip/--name/--hostname/--mac/--guest-os/--power-state)"
+            )
+        validate_criteria(criteria)
+        return find_matches(si, criteria, props or [])
+
+    run_read(output.value, build)

{vcf_super_cli-0.4.0 → vcf_super_cli-0.5.0}/vsc/skill/assets/SKILL.md

@@ -103,6 +103,12 @@ vsc --profile prod vsphere events list --vm vm-42 --since 1h
 vsc --profile prod vsphere tasks list --max-count 20
 vsc --profile prod vsphere inventory vm vm-42 --props config.hardware
 
+# Find a VM by IP/hostname/MAC/guest-OS/power when you don't know its moid.
+# Flags AND together; repeat a flag to OR; --ip takes an exact address or a CIDR.
+vsc --profile prod vsphere inventory find --ip 10.20.3.41          # "which VM has this IP?"
+vsc --profile prod vsphere inventory find --ip 10.20.3.0/24 --power-state poweredOn
+vsc --profile prod vsphere inventory find --name 'web-*' --props config.version
+
 # Writes — preview first (dry-run), then --apply
 vsc --profile prod vsphere power stop vm-42                    # preview
 vsc --profile prod vsphere power stop vm-42 --apply            # execute