Discovery CLI commands

Release version: Yokohama

Updated January 30, 2025

11 minutes to read

Summarize

Summarized using AI

Summary of Discovery CLI commands

The Discovery Command Line Interface (CLI) in the Pattern Designer Enhancements application provides a set of commands for managing and troubleshooting ServiceNow Discovery configurations, credentials, MID Servers, patterns, and discovery jobs. These CLI commands require thediscoveryadminrole and enable ServiceNow customers to efficiently retrieve information, perform actions, and validate discovery components directly from the command line.

Show full answer Show less

Key Commands and Their Practical Uses

discovery-insights: Retrieves details about discovery configurations including customized patterns, instance build details, and related plugins, providing a comprehensive snapshot of your discovery setup.
get-discovery-credentials: Lists discovery credentials, with an option to filter only those credentials that are testable, helping you manage and verify credential readiness.
get-discovery-logs: Retrieves discovery logs with flexible filtering options such as status ID, device inclusion, ECC queue logs, pattern execution logs, log severity levels, and output formats, facilitating detailed troubleshooting.
get-midservers: Provides detailed information about MID Servers including their status, validation state, and optionally, issue logs, enabling monitoring and maintenance of MID Servers.
get-pattern-commands: Fetches all commands associated with a specified discovery pattern by name or sysid, useful for understanding the exact operations a pattern performs.
get-patterns: Lists all active discovery patterns with their CI types and pattern types, allowing quick reference of available patterns in your instance.
midserver-action: Executes management actions on MID Servers such as stop, resume, restart, validate, upgrade, or grab logs, providing direct control over MID Server operations.
quick-discovery: Initiates a quick discovery against a specified CI or IP address, useful for on-demand discovery and rapid verification of CI data.
run-command: Runs specific commands on remote devices using provided credentials and MID Servers, supporting advanced queries like WMI and shell commands for detailed device interrogation.
test-discovery-credential: Validates discovery credentials against a target system using a specified MID Server without altering configurations, ensuring credentials are operational before discovery runs.

Why These Commands Matter

These CLI commands empower ServiceNow customers to efficiently manage Discovery components through automation and scripting, reduce manual efforts in troubleshooting, and gain detailed insights into discovery operations. They provide robust tools for administrators to verify credentials, monitor MID Servers, inspect patterns and commands, and retrieve logs with precision, all critical for maintaining an accurate and healthy CMDB.

What to Expect

JSON-formatted output by default, facilitating integration into scripts or external tools.
Role-based access control requiring discoveryadmin privileges to execute commands securely.
Flexible argument options for fine-tuned command execution, such as filtering logs by severity or including issue logs for MID Servers.
Clear success and error messages with detailed information to guide troubleshooting and validation efforts.
Support for executing complex queries and discovery jobs directly from the CLI, enabling streamlined operations and automation.

Next Steps for ServiceNow Customers

Ensure appropriate roles are assigned to users who will operate Discovery CLI commands.
Incorporate these commands into your discovery automation workflows and troubleshooting procedures.
Use commands like test-discovery-credential and get-discovery-logs to validate and troubleshoot discovery setups proactively.
Leverage midserver-action to manage MID Server lifecycle events directly from the CLI.
Consult ServiceNow documentation or the Now Support Knowledge Base article KB1553142 for further details and examples on Discovery CLI usage.

A list of commands that are available to the Discovery Command Line Interface (CLI) in the Pattern Designer Enhancements application.

Request apps on the Store

Visit the ServiceNow Store website to view all the available apps and for information about submitting requests to the store. For cumulative release notes information for all released apps, see the ServiceNow Store version history release notes.

discovery-insights

Retrieves details about your discovery configurations and patterns. The details include custom pattern information, instance details, and plugin details.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery discovery-insights

Example

Retrieve details about your discovery configurations and patterns by executing the following command:

snc discovery discovery-insights

The command returns a JSON object (default format) containing the information in the following table.

Table 1. JSON objects returned from command discovery-insights
Object	Details
`customizedPatterns`	`patternName`: Name of the customized pattern `source`: Location where the customized changes are contained (for example, Default)
`instanceDetails`	`buildDate`: Date of the instance build (format: MM-DD-YYYY_HHMM) `buildName`: Name of the instance build
`pluginDetails`	Plugins related to discovery configuration or that are necessary to run CLI.

Return value

✔ Discovery diagnostics successfully completed.
{
   "customizedPattern": [
      {
         "patternName": "A10",
         "source": "Default"
      },
      {
         "patternName": ".NET Application",
         "source": "Default"
      }
   ],
   "instanceDetails": {
      "buildDate": "09-16-2023_2010",
      "buildName": "utah-p0"
   },
   "pluginDetails": {
      "CMDB CI Class Models": "1.48",
      "Discovery and Service Mapping Patterns": "1.8.0",
      "Pattern Designer Enhancements": "3.1.0",
      "Visibility Content": "6.13.0"
   }
}

get-discovery-credentials

Retrieves the list of discovery credentials.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery get-discovery-credentials [arguments]

Argument:

--testableonly: Includes only credentials that can be tested. Possible values: true or false.

Examples

Retrieve a list of the discovery credentials by executing the following command:

snc discovery get-discovery-credentials

List only testable discovery credentials by executing the command with the following argument:

snc discovery get-discovery-credentials --testableonly="true"

Return value

✔ Get only testable credentials [ssh, snmpv3, snmp, ssh_private_key, windows, vmware, jdbc, jms]: true
✔ Discovery credentials details retrieved
{
   "credentials": [
      {
         "active": true,
         "name": "shCred",
         "type": "ssh",
         "updated": "2023-10-16 10:57:27"
      },
      {
         "active": true,
         "name": "WindowsCred",
         "type": "windows",
         "updated": "2023-10-10 12:18:17"
      },
      {
         "active": true,
         "name": "Azure",
         "type": "azure",
         "updated": "2022-10-19 05:57:21"
      },
      {
         "active": true,
         "name": "public",
         "type": "snmp",
         "updated": "2023-09-28 07:40:35"
      },
      {
         "active": true,
         "name": "Windows MID Server Service Account",
         "type": "windows",
         "updated": "2023-10-16 10:57:23"
      },
      …
   ]
}

get-discovery-logs

Retrieves discovery logs with flexible options, including:

Status filtering
Device inclusion
External Communication Channel (ECC) queue logs
Pattern logs
Output format choices

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery get-discovery-logs [arguments]

Arguments

Table 2. Arguments for command get-discovery-logs
Argument	Description
`--status-id`	Discovery status number by which to filter logs.
`--devices`	Includes device-specific logs. Possible values: true or false.
`--ecc-queue-logs`	Includes associated ECC queue logs. Possible values: true or false.
`--pattern-logs`	Includes pattern execution logs. Possible values: true or false.
`--pattern-log-level`	Maximum severity level by which to filter pattern logs. The available options are: DEBUG: Includes only DEBUG log messages (default) ERROR: Includes ERROR and DEBUG messages WARN: Includes WARN, ERROR, and DEBUG messages INFO: Includes all messages
`--log-limit`	Maximum number of log records to return between 1-100 (default: 100). Applies to ECC queue and pattern logs only.
`--output-format`	Output format for the logs. Supported formats are JSON (default format) or table.

Examples

Retrieve discovery logs by executing the following command:

snc discovery get-discovery-logs [options]

Customize the log retrieval by including the arguments either one at a time or as a single command.

To execute the command one argument at a time:

snc discovery get-discovery-logs
Discovery status number: DIS0010013
Include Devices: true
Include ECC Queue logs: true
Include pattern execution logs: true
Pattern max log level (INFO, WARN, ERROR, DEBUG): DEBUG
Maximum number of log records to return: 100
Output format [supported: json(default), table]: json

To execute the command as a single command:

snc discovery get-discovery-logs --status-id="DIS0010013" --ecc-queue-logs="true" --devices="true" --pattern-logs="true" --output-format="json"

If the maximum number of log records to return is high, consider using a table output format.

Return value

✔ Discovery Status details retrieved
{
   "Devices": [
      {
         "CMDBCI": "",
         "ClassificationProbe": "Windows - Classify",
         "Completed": "4",
         "CompletedActivity": "Updated CI",
         "Created": "2023-10-17 09:25:33",
         "CurrentActivity": null,
         "Issues": "0",
         "ScanStatus": "Completed 4",
         "Started": "4",
         "Status": "DIS0010136"
      }
   ],
   "DiscoveryLogs": [
      {
         "CI": "",
         "Created": "2023-10-17 09:25:24",
         "Device": "",
         "ECCQueueInput": "",
         "Level": "0",
         "Message": "Discovery started",
         "Source": "Discovery",
         "Status": "DIS0010136"
      },
      {
         "CI": "",
         "Created": "2023-10-17 09:26:49",
         "Device": "192.168.1.100",
         "ECCQueueInput": "HorizontalDiscoveryProbe",
         "Level": "0",
         "Message": "Exploring CI Pattern, Pattern name: Windows OS - Servers",
         "Source": "DiscoverySensor",
         "Status": "DIS0010136"
      },
      {
         "CI": "",
         "Created": "2023-10-17 09:27:01",
         "Device": "192.168.1.100",
         "ECCQueueInput": "",
         "Level": "0",
         "Message": "Discovery completed",
         "Source": "Discovery",
         "Status": "DIS0010136"
      }
   ],
   "DiscoveryStatus": [
      {
         "Completed": "5",
         "Created": "2023-10-17 09:25:24",
         "Description": "Discover Now",
         "Discover": "CIs",
         "Duration": "1970-01-01 00:01:37",
         "Number": "DIS0010136",
         "Schedule": "WinServer",
         "Started": "5",
         "State": "Completed",
         "Updated": "2023-10-17 09:27:08"
      }
   ],
…
}

get-midservers

Retrieves detailed information about MID Servers, including status and validation details. Optionally, you can include MID Servers issue logs in the output.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery get-midservers [arguments]

Argument

--include-issues: Includes issue logs with each MID Server. Possible values: True or false (default: true).

Example

Retrieve details about the MID Servers by executing the following command:

snc discovery get-midservers

Retrieve a list of MID Servers and their issue logs by executing the command with the following argument:

snc discovery get-midservers --include-issues=true

Return value

✔ MID Server details were fetched successfully.
{
   "mid_servers": [
      {
         "home_directory": "C:\\Users\\admin\\Desktop\\midInstallationFolder\\agent",
         "host_name": "LocalLab",
         "host_os_version": "10.0.xxxx",
         "ip_address": "192.168.0.1",
         "issues": [],
         "last_refreshed": "2023-10-01 00:00:00",
         "name": "WindowsMidServer",
         "started": "2023-10-01 00:01:01",
         "status": "Up",
         "sys_id": "cb8d1625c3fdb110c72691477d01312e",
         "unresolved_issues": "0",
         "validated": "true",
         "validated_at": "2023-10-01 00:01:01"
      }
   ]
}

get-pattern-commands

Retrieves a comprehensive list of commands associated with a specified discovery pattern, identified by either its name or its sys_id.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery get-pattern-commands [arguments]

Argument

--pattern: Pattern name or sys_id

Examples

Retrieve a list of commands associated with the specified pattern by executing the command with either the pattern name or the sys_id.

Execute the command by entering the pattern name Windows OS - Servers:
```
snc discovery get-pattern-commands --pattern="Windows OS - Servers"
```
Execute the command by entering the pattern sys_id 670e55a4db702200c06776231f961942:
```
snc discovery get-pattern-commands --pattern="670e55a4db702200c06776231f961942"
```

Return value

✔ Commands fetched successfully. 
[
   {
      "Command": "\"\\root\\CIMV2\" \"SELECT Caption,IPAddress,MACAddress,DHCPEnabled,Index,InterfaceIndex,IPEnabled FROM Win32_NetworkAdapterConfiguration\"",
      "Command Type": "wmi",
      "sys_id": "2e677c4ec3adb1106618b10ad0013185"
   },
   {
      "Command": "\"\\root\\CIMV2\" \"SELECT Index,InterfaceIndex,Name,Manufacturer,NetConnectionID FROM Win32_NetworkAdapter\"",
      "Command Type": "wmi",
      "sys_id": "6a677c4ec3adb1106618b10ad0013185"
   },
   {
      "Command": "powershell -command \\Get-NetRoute -AddressFamily IPv6\\",
      "Command Type": "shell",
      "sys_id": "a6677c4ec3adb1106618b10ad0013185"
   },
   {
      "Command": "\"\\root\\CIMV2\" \"SELECT Destination,Mask,NextHop, InterfaceIndex FROM Win32_IP4RouteTable\"",
      "Command Type": "wmi",
      "sys_id": "e2677c4ec3adb1106618b10ad0013185"
   },
   {
      "Command": "\"\\root\\CIMV2\" \"SELECT DefaultIPGateway FROM Win32_NetworkAdapterConfiguration\"",
      "Command Type": "wmi",
      "sys_id": "e6677c4ec3adb1106618b10ad00131ab"
   },
…
]

get-patterns

Retrieves a comprehensive list of available discovery patterns.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery get-patterns

Example

Retrieve a list of available discovery patterns by executing the following command:

snc discovery get-patterns

Return value

✔ Details of Discovery Patterns successfully retrieved.
[
   {
      "active": true,
      "ci_type": "cmdb_ci_appl_dot_net",
      "name": ".NET Application",
      "pattern_type": "1 - Application"
   },
   {
      "active": true,
      "ci_type": "cmdb_ci_lb_service",
      "name": "A10",
      "pattern_type": "1 - Application"
   },
   {
      "active": true,
      "ci_type": "cmdb_ci_lb_a10",
      "name": "A10 Load Balancer",
      "pattern_type": "3 - Infrastructure"
   },
   {
      "active": true,
      "ci_type": "cmdb_ci_lb_a10",
      "name": "A10 Load Balancer SSH",
      "pattern_type": "3 - Infrastructure"
   },
   {
      "active": true,
      "ci_type": "cmdb_ci_appl_generic",
      "name": "A10 SSH Hosting Formatting",
      "pattern_type": "2 - Shared library"
   },
   …
]

midserver-action

Executes various actions on MID Servers, for example: stop, resume, or restart.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery midserver-action [arguments]

Arguments

Table 3. Arguments for command midserver-action
Argument	Description
`-m` or `--mid-server`	Name or sys_id of the MID Server
`-a` or `--action`	Action to perform on the MID Server. The available options are: invalidate resume stop pause autoUpgrade upgrade restart file_discovery_refresh grab_logs validate

Example

Perform an action on a MID Server with the following command:

snc discovery midserver-action [options]

Restart the MID Server WinMidServer by executing the following command:

snc discovery midserver-action --mid-server="WinMidServer" --action="restart"

Return value

✔ Successfully submitted mid-server action
{
   "Action": "restart",
   "MidServer": "cb8d1625c3fdb110c72691477d01312e",
   "Output": "Mid server restart in-progress."
}

✔ Mid server action executed successfully
restart executed successfully.

quick-discovery

Executes a quick discovery against a specified configuration item (CI) or IP address.

Note:

When the callback retries exceed the maximum limit, you might receive the following error message:

✗ Discovery Failed.
{
"CurrentActivity": "",
"DiscoveryStatus": {},
"State": "Active"
}

The message indicates that callback retries were exceeded but although discovery failed, it’s still running in the background. Check the discovery logs by either executing the command

snc discovery
            get-discovery-logs

or checking the ServiceNow® instance for updates on the discovery status.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery quick-discovery [arguments]

Arguments

Table 4. Arguments for command quick-discovery
Argument	Description
`--type`	Target host type: either IP or CI.
`--target`	Details of the target host. IP: IP address CI: The available options are: Name Sys_id Serial number
`--error-logs-only`	Includes error logs only. Possible values: true or false (default: true).

Examples

Execute a quick discovery against a target entity using a specified criteria.

snc discovery quick-discovery

Execute a quick discovery against the IP address 192.168.1.100 by executing the following command and argument:
```
snc discovery quick-discovery --type="ip" --target="192.168.1.100"
```
Execute a quick discovery against the specified CI by executing the command with the name, sys_id, or serial number.
- To execute a quick discovery against the CI name ecommerce001, enter:
```
snc discovery quick-discovery --type="ci" --target="ecommerce001"
```
- To execute a quick discovery against the CI sys_id d0e8761137201000deeabfc8bcbe5da7, enter:
```
snc discovery quick-discovery --type="ci" --target="d0e8761137201000deeabfc8bcbe5da7"
```
- To execute a quick discovery against the CI serial number L3BB911, enter:
```
snc discovery quick-discovery --type="ci" --target="L3BB911"
```

Return value

snc discovery quick-discovery --type="ip" --target="192.168.1.100"
✔ Discovery job submitted
Status Number: DIS0010054
✔ Discovery is complete
{
   "DiscoveryLogs": [],
   "DiscoveryStatus": [
      {
         "Completed": "5",
         "Created": "2023-10-17 10:59:52",
         "Description": "Discover CI",
         "Discover": "CIs",
         "Duration": "1970-01-01 00:01:41",
         "Number": DIS0010054,
         "Schedule": "",
         "Started": "5",
         "State": "Completed",
         "Updated": "2023-10-17 11:02:06"
      }
   ],
   "State": "Completed"
}

run-command

Executes commands on remote devices using specified credentials, targets, and MID Servers.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery run-command [arguments]

Arguments

Table 5. Arguments for command run-command
Argument	Description
`--command`	Command to be executed.
`--command-type`	Operation type to be performed.
`--credential`	Credential used to execute the command.
`--midserver`	Name of the MID Server used to communicate with the target.
`--os-server`	CI class that represents the server operating system (server OS) on which to run the commands. For example, enter cmdb_ci_linux_server for the Linux server.
`--target`	Host IP address on which you want to run the command.

Example

Execute the following command to have the Windows Management Instrumentation (WMI) query ask the system to retrieve the UUID and IdentifyingNumber properties from the Win32_ComputerSystemProduct class in the \root\CIMV2 namespace:

snc discovery run-command --command="\"\\root\\CIMV2\" \"SELECT UUID,IdentifyingNumber FROM Win32_ComputerSystemProduct\"" --command-type="wmi" --credential="WinCred" --midserver="WinMidServer" --os-server="cmdb_ci_win_server" --target="192.168.1.1"

Return value

✔ The command is sent for execution.
{
"eccQueueOutputSysId": "9a3c55a3c33db910c72691477d0131cd"
}

✔ Command Executed Successfully...
{
"result": {
"IdentifyingNumber": "VMware-00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00",
"Name": "VMware Virtual Platform",
"Object Reference": null,
"UUID": "61410042-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"Version": "None",
"__CLASS": "Win32_ComputerSystemProduct",
"internal_classname": "Win32_ComputerSystemProduct",
"internal_namespace": "root/cimv2"
}
}

test-discovery-credential

Validates the discovery credentials against a specified target system using a designated MID Server. The command checks only credential readiness for network discovery tasks. It doesn't modify or affect the configuration of either the discovery credential or the target system.

Important:

This command requires a specific XML file to have been imported into the Module Access Policy list. For more information, see the Discovery CLI [KB1553142] article in the Now Support Knowledge Base.

Command group

Parent group: discovery

Roles required

discovery_admin

If using a service related to Discovery, you must have the required roles for that service.

Command structure

snc discovery test-discovery-credential [arguments]

Arguments

Table 6. Arguments for test-discovery-credential
Argument	Description
`--dbname`	Name of the database on which to test these credentials.
`--dbtype`	Type of database on which to test these credentials. The available options are: MSSQL—for Microsoft SQL Server MySQL Oracle
`--icf`	Name of the Java Naming and Directory Interface (JNDI) class that is used to create the InitialContext. The name of the JNDI class must include first the package name and then the class name. For example, to connect to the ActiveMQ JNDI class, you would enter: `org.apache.activemq.jndi.ActiveMQInitialContextFactory`.
`--midserver`	Name of the MID Server to use for this test. To test Windows credentials, you must use a Windows MID Server.
`--name`	Name of the credential.
`--port`	Port on the target to use for this test. The system pre-populates this field with the default port for the selected credential type.
`--target`	Target host on which these credentials are run. This value must be an IP address for all credential types except VMware, for which the value can be the host URL.

Example

Test the discovery credential WinCred against MID Server WinMidServer by executing the following command:

snc discovery test-discovery-credential --name="WinCred" --target="192.168.1.1" --midserver="WinMidServer"

The command returns a success message when the following conditions are met:

The credential is valid
The connection to the target system is successful
The specified MID Server is operational

If these conditions aren’t met, an error message detailing the issues is displayed.

Return value

✔ Discovery credentials tested successfully
Credential Test Id [ecc-sys-id]: "2b36e40ec3727990c72691477d0131c6"
✔ The credential test is complete
{
   "output": "Test Succeeded"
}

For more information about Discovery CLI, see the Discovery CLI [KB1553142] article in the Now Support Knowledge Base.