Domotz

Domotz - Claude Code Skill

Prerequisites: Install the CLI

This skill drives the domotz-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

   bashCopy code
   bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/domotz/install.sh)
   

2. Windows (PowerShell):

   powershellCopy code
   iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/domotz/install.ps1 | iex
   

3. Verify: domotz-cli --version
4. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the domotz-cli and domotz-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

domotz-cli gives MSPs and AV integrators full command-line and agent-native access to Domotz Collectors, devices, variables, alerts, and network topology. It syncs your whole fleet into a local database so cross-site rollups - fleet health, every offline device, new-device detection, one unified inventory export - become single offline queries instead of agent-by-agent API sweeps.

When to Use This CLI

Use domotz-cli when an agent or operator needs to query a fleet of Domotz-monitored networks from the terminal: checking which sites are down, finding every offline or newly-appeared device across all clients, exporting a unified asset inventory, or reading variables, alerts, and topology with structured JSON output. It is the right choice over raw API calls whenever the question spans more than one agent.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI for non-Domotz monitoring stacks (PRTG, Zabbix, Datto RMM, NinjaOne) - it only talks to the Domotz Public API.
• Do not use it for ticketing/PSA actions (creating tickets, billing) - pair it with a PSA tool instead.
• Do not use it for ad-hoc network scans of arbitrary hosts; it reports what Domotz Collectors already monitor.
• Do not use the fleet store-backed commands as a live source without a recent 'sync --full' - they read the local mirror.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Cross-fleet rollups the API can't do in one call

• fleet health - One status board across every Domotz Collector: online/offline agents, degraded sites, and down-device counts per site.

  Pick this when an agent needs the single-glance 'is anything on fire across all my sites' answer instead of looping the agent list endpoint.

  bashCopy code
  domotz-cli fleet health --agent
  

• fleet offline - Every unreachable or offline device across all sites in one prioritized list, with site and importance.

  Use to triage outages fleet-wide without paginating per-agent device lists.

  bashCopy code
  domotz-cli fleet offline --json --select site,display_name,importance
  

• fleet new - Devices first-seen anywhere in the fleet within a time window - a rogue-device security signal.

  Reach for this on a security sweep: surface unexpected devices that appeared on any monitored network overnight.

  bashCopy code
  domotz-cli fleet new --since 24h --json
  

• fleet inventory - One asset table - vendor, model, type, OS, serial, site - for every device across every agent.

  Use for client asset reports or a fleet-wide CMDB export in one command.

  bashCopy code
  domotz-cli fleet inventory --csv > assets.csv
  

• fleet alerts - Alert profiles (alerting rules) and their device bindings, aggregated across the fleet.

  Pick this to review every site's alerting rules in one place instead of walking each agent.

  bashCopy code
  domotz-cli fleet alerts --json
  

• fleet ip-conflicts - IP address conflicts across all sites in one prioritized list.

  Use to catch addressing problems fleet-wide before they cause silent outages.

  bashCopy code
  domotz-cli fleet ip-conflicts --json
  

• fleet agents - Only the sites (Collectors) that are offline or degraded right now, with location, organization, and version, in one prioritized list.

  Pick this when the question is 'which SITES are down' - not individual devices ('fleet offline') and not the full healthy-included board ('fleet health').

  bashCopy code
  domotz-cli fleet agents --agent
  

• fleet triggers - TCP service sensors (eyes) currently DOWN across every device on every agent, in one fleet-wide list.

  Pick this for currently-down TCP service checks across the fleet; alert-profile rules and bindings live in 'fleet alerts'.

  bashCopy code
  domotz-cli fleet triggers --agent
  

• fleet events - Per-agent activity-log and network-event history merged into one chronological fleet-wide timeline.

  Pick this for the fleet-wide activity feed; for newly-appeared devices use 'fleet new', for currently-down devices use 'fleet offline'.

  bashCopy code
  domotz-cli fleet events --since 24h --agent
  

Fleet analytics

• fleet breakdown - Counts of devices by type, vendor, and OS across the fleet for capacity and security posture.

  Reach for this to answer 'how many of X do we manage' across all clients at once.

  bashCopy code
  domotz-cli fleet breakdown --by vendor --json
  

• fleet speedtest - Per-site WAN speed-test history aggregated into fleet min/avg/max and a worst-site ranking.

  Use to spot the slowest client circuits across the fleet from one command.

  bashCopy code
  domotz-cli fleet speedtest --json
  

• fleet stale - Collectors whose local snapshot has gone quiet - last-synced or last-seen older than a threshold, a silent monitoring blind spot.

  Pick this to find agents that stopped reporting (Collector offline or sync gap) before trusting any other fleet rollup.

  bashCopy code
  domotz-cli fleet stale --max-age 24h --agent
  

• fleet unmonitored - Devices Domotz can't fully monitor - failed or missing authentication and SNMP status - surfaced fleet-wide as a coverage-gap audit.

  Pick this for monitoring hygiene (creds/SNMP gaps), not for devices that are simply offline - that is 'fleet offline'.

  bashCopy code
  domotz-cli fleet unmonitored --agent
  

Per-site, offline

• topology - Cached network topology for a site, summarized (node/edge counts, gateways) and queryable offline.

  Pick this to inspect a site's topology fast and offline after a sync.

  bashCopy code
  domotz-cli topology --agent-id 12345 --json
  

• drift - Diffs two local snapshots for a site to surface configuration and inventory changes over time.

  Use after a maintenance window to see exactly what changed on a network.

  bashCopy code
  domotz-cli drift --agent-id 12345 --json
  

Command Reference

agent - Manage agent

• domotz-cli agent count - Counts the collectors.
• domotz-cli agent delete - Deletes a collector.
• domotz-cli agent get - Returns the details of a collector.
• domotz-cli agent get-list-uptime - Returns the uptime of all collectors.
• domotz-cli agent list - Returns the list of collectors accessible by the user.

alert-profile - Manage alert profile

• domotz-cli alert-profile get-agent - Returns the alert profile bindings of a collector.
• domotz-cli alert-profile get-alert-profiles2 - Returns the list of configured alert profiles. You can configure alert profiles on the Domotz Portal.
• domotz-cli alert-profile get-devices - Returns the alert profile bindings of the devices of a collector.

area - Manage area

• domotz-cli area - Returns all the areas of a Company. Note: This API is restricted to users on the Enterprise Plan.

custom-driver - Manage custom driver

• domotz-cli custom-driver get - Returns details of a Custom Driver.
• domotz-cli custom-driver list - Retrieves the list of available Custom Drivers.
• domotz-cli custom-driver list-associations - Retrieves a list of all Custom Driver associations for a collector.
• domotz-cli custom-driver re-enable-associations - Re-enable all disabled Custom Drivers for the current user.

custom-tag - Manage custom tag

• domotz-cli custom-tag create - Creates a new Tag.
• domotz-cli custom-tag delete - Deletes a Tag and removes it from Collectors and Devices.
• domotz-cli custom-tag edit - Updates one or more properties of an existing Tag.
• domotz-cli custom-tag get - Retrieves all Tags available in the account, including their metadata and usage counts.

device-profile - Manage device profile

• domotz-cli device-profile - Returns the list of the available device profiles.

inventory - Manage inventory

• domotz-cli inventory create-field - Creates a new Inventory Field - the user will be able to set key-values pairs on every device.
• domotz-cli inventory delete - Clears the inventory.
• domotz-cli inventory delete-field - Deletes the Inventory Field.
• domotz-cli inventory get - Enumerates all the Inventory fields.
• domotz-cli inventory update-field - Updates the Inventory Field.

meta - Manage meta

• domotz-cli meta - Returns information about API usage and limits.

rbac - Manage rbac

• domotz-cli rbac create-user - Create a new RBAC User.
• domotz-cli rbac create-user-group - Create a new RBAC User group.
• domotz-cli rbac delete-user - Delete an RBAC User by user ID.
• domotz-cli rbac delete-user-group - Delete an RBAC User group by user group ID.
• domotz-cli rbac edit-user - Update an RBAC User by user ID.
• domotz-cli rbac edit-user-group - Update an RBAC User group by user group ID. Note: Users and roles are replaced by those provided in the request.
• domotz-cli rbac get-role - Retrieve a Role and its Permissions. Note: When 'is_applied_to_all_entities' is true, 'entity_ids' is omitted.
• domotz-cli rbac get-roles - List all RBAC roles and associated user groups.
• domotz-cli rbac get-user - Retrieve RBAC User details by User ID.
• domotz-cli rbac get-user-group - Retrieve RBAC User group details by user group ID.
• domotz-cli rbac get-user-groups - List all RBAC User groups with their details.
• domotz-cli rbac get-users - List all RBAC Users with their details.

type - Manage type

• domotz-cli type list-device-base - Returns the device types list.
• domotz-cli type list-device-detected - Returns the detected device types list.

user - Manage user

• domotz-cli user - Returns the account information.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

bashCopy code
domotz-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query.

Recipes

Triage outages fleet-wide

bashCopy code
domotz-cli fleet offline --json --select site,display_name,importance

Lists every offline device across all sites with just the fields you need for triage.

Narrow a verbose device payload

bashCopy code
domotz-cli fleet inventory --json --select site,display_name,type,vendor,os

Device records are deeply nested; dotted --select paths pull only the columns that matter and keep agent context small.

Overnight rogue-device sweep

bashCopy code
domotz-cli fleet new --since 24h --json

Surfaces devices first-seen anywhere in the fleet in the last day for a security review.

Client asset report

bashCopy code
domotz-cli fleet inventory --csv > assets.csv

Exports a single vendor/model/type/OS/serial/site table across every managed device.

Read a site's topology offline

bashCopy code
domotz-cli topology --agent-id 12345 --cached --json

Re-reads the last cached topology graph summary without re-hitting the API (fetch live first by running without --cached).

Auth Setup

Authenticate with an API key from the Domotz Portal (Settings > API Key). Set DOMOTZ_API_KEY (DOMOTZ_PUBLIC_API_KEY is also accepted as a fallback), and set your region/cell (shown beside the key, e.g. us-east-1-cell-1) via DOMOTZ_REGION so the CLI targets api-.domotz.com.

Run domotz-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable - JSON on stdout, errors on stderr

• Filterable - --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  bashCopy code
  domotz-cli agent list --agent --select id,name,status
  

• Previewable - --dry-run shows the request without sending

• Offline-friendly - sync/search commands can use the local SQLite store when available

• Non-interactive - never prompts, every input is a flag

• Explicit retries - use --idempotent only when an already-existing create should count as success, and --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

jsonCopy code
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

Copy code
domotz-cli feedback "the --since flag is inclusive but docs say exclusive"
domotz-cli feedback --stdin < notes.txt
domotz-cli feedback list --json --limit 10

Entries are stored locally at ~/.local/share/domotz-cli/feedback.jsonl. They are never POSTed unless DOMOTZ_FEEDBACK_ENDPOINT is set AND either --send is passed or DOMOTZ_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

Copy code
domotz-cli profile save briefing --json
domotz-cli --profile briefing agent list
domotz-cli profile list --json
domotz-cli profile show briefing
domotz-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show domotz-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

1. Install the MCP binary (run the install script from the Prerequisites section, or see mcp-install.md for per-agent wire-up).
2. Register with Claude Code:

   bashCopy code
   claude mcp add domotz-mcp -- domotz-mcp
   

3. Verify: claude mcp list

Direct Use

1. Check if installed: which domotz-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   bashCopy code
   domotz-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: domotz-cli <command> --help.