claudetools/.claude/skills/rmm-search/SKILL.md

name, description

name

description

rmm-search

Find machines/agents in the GuruRMM fleet cleanly and on the first try. Use this ANY time you need to locate an RMM agent by name, role, client, site, or OS before acting on it — instead of pulling /api/agents and grepping (which bleeds across clients and picks the wrong box). Flexible, forgiving, multi-field search with a client filter so a query like "hyperv valleywide" returns ONLY Valley Wide's hyperv host, never Dataforth's. Invoke on: "find the X machine", "which agent is", "look up <host> in RMM", "<client>'s server/DC/hyperv/file server", "search RMM for", "what's the agent id for". After finding the agent, hand its hostname/id to the `rmm` skill to run commands.

rmm-search — clean machine lookup in GuruRMM

The /rmm skill resolves agents by grepping /api/agents client-side, which is exactly where lookups go wrong: a bare term like hyperv matches every client's hyperv box, and it's easy to act on the wrong one. This skill does a forgiving, ranked, client-aware search instead. Use it as the front door for finding an agent; use /rmm for acting on it.

Usage

bash .claude/scripts/rmm-search.sh <words...> [-c|--client <name>] [--online] [--json] [-n N]
bash .claude/scripts/rmm-search.sh -c <client>          # list ALL machines for a client
bash .claude/scripts/rmm-search.sh --list-clients       # distinct client names

How matching works (built for first-try correctness)

• Normalized: case, spaces, and hyphens are ignored — valleywide, valley wide, and Valley Wide Plastering all match the same client.
• Multi-field: every query word is matched against hostname, client_name, site_name, os_type, and id.
• AND semantics: every word must hit some field, so adding words narrows. hyperv valleywide → only the box that is both a hyperv host AND Valley Wide. This is why a query can't bleed across clients without -c.
• Ranked: exact > prefix > substring > subsequence (typo tolerance on hostnames, e.g. hyprv→HYPERV). Hostname matches outrank client/site/OS. Best result first; a whole-query hostname hit gets a boost.
• -c/--client is an explicit hard scope. If the client term is ambiguous (matches >1 client and none exactly), it lists the candidates and stops rather than guessing — narrow the value and retry.
• --online keeps only agents seen in the last 5 minutes. Online state is derived from last_seen, NOT the API is_connected flag (currently null fleet-wide — don't trust it).

Output

A ranked table: HOSTNAME | CLIENT | SITE | OS | STAT | ID (best match first). --json emits {hostname,id,client,site,os,online,last_seen,score} for piping the id into a /rmm command. -n N caps the rows.

Examples

rmm-search.sh hyperv valleywide          # VWP-HYPERV1 only (not DF-HYPERV-B)
rmm-search.sh dc -c dataforth            # Dataforth's domain controllers
rmm-search.sh vwp fil                    # VWP-FILES (partial words ok)
rmm-search.sh -c "peaceful spirit"       # every Peaceful Spirit machine
rmm-search.sh files valleywide --json | jq -r '.[0].id'   # id -> feed to /rmm

Implementation

• Wrapper .claude/scripts/rmm-search.sh (arg parsing + auth via rmm-auth.sh + fetch /api/agents), engine .claude/scripts/rmm-search.py (scoring/filter).
• The agents payload is piped to the engine on stdin — it's too large to pass as a CLI argument on Windows ("Argument list too long").
• Read-only. To run a command on a found agent, pass its hostname/id to /rmm.
• Ranking heuristic mirrors the dashboard Omnibox (scoreMatch) in spirit but is deliberately looser (multi-field + subsequence) to favor first-try hits.