WinRM CLI Documentation

Windows Remote Management (WinRM) is a protocol designed for remote management and command execution on Windows systems. Built on the WS-Management protocol, it enables secure communication between systems, streamlining administrative tasks and facilitating data retrieval. Refer to Installation and Configuration for Windows Remote Management for more details.

The MetricsHub WinRM CLI connects to a remote Windows host and lets you:

• run WQL queries (wql)
• execute remote commands (command)
• open an interactive shell (shell).

It authenticates using NTLM (default), Kerberos, or HTTP Basic, over HTTP or HTTPS.

Before using the CLI, ensure your platform supports WinRM monitoring by checking the Supported Platforms.

Syntax

The CLI takes a set of connection options followed by one of the wql, command, or shell subcommands:

winrmcli [OPTIONS] wql "QUERY"
winrmcli [OPTIONS] command COMMAND LINE...
winrmcli [OPTIONS] shell

command can also be invoked through its aliases cmd, exec, or run.

Options

Option	Description	Default Value
-h, --hostname	(Required) Hostname or IP address of the target host.	None
-u, --username	(Required) Username for authentication, optionally as DOMAIN\user.	None
-p, --password	(Avoid in automation) Password for authentication. Visible to local processes. If omitted, you are prompted interactively.	None
-pf, --password-file	(Preferred for automation) Reads a UTF-8 password from a file. Mutually exclusive with --password.	None
-P, --port	Port for the WinRM service.	5985 for HTTP, 5986 for HTTPS
-t, --timeout	Operation timeout, in milliseconds.	60000
-d, --directory	Working directory of the remote command or shell. Applies to command and shell only.	None
--env	Environment variable for the remote command or shell, as NAME=VALUE. Repeatable. Applies to command and shell only.	None
-i, --stdin	Forwards the local standard input to the remote command. Applies to command only.	None
--https	Uses HTTPS instead of HTTP.	HTTP
--https-permissive	(Not secure - For testing purposes only) Trusts any HTTPS certificate and skips hostname verification. Requires --https.	Certificate is validated
--ntlm	Uses NTLM authentication.	Enabled by default
--kerberos	Uses Kerberos authentication. Requires --https.	None
--basic	Uses HTTP Basic authentication. Use --https to protect the credential.	None
--kerberos-kdc	Sets the Kerberos KDC host; the realm is inferred from its DNS suffix. Requires --kerberos.	None
--kerberos-realm	Overrides the realm inferred from --kerberos-kdc. Requires --kerberos-kdc.	None
--version	Displays the build version.	None
--help	Displays detailed help information about the available options.	None

note

--ntlm, --kerberos, and --basic are mutually exclusive. Kerberos and HTTP Basic must be used over HTTPS (--https). NTLM works over HTTP — the payload is protected by NTLM message encryption — as well as over HTTPS.

Output

• wql results are written to standard output as UTF-8 JSON Lines, one row per line, as the enumeration pages arrive.
• command and shell forward the remote standard output and standard error to your local streams live, while the command runs.

Diagnostics are written to standard error, so you can safely redirect or pipe the result.

Examples

Example 1: Basic WQL Query

winrmcli --hostname dev-01 --username admin --password secret \
wql "SELECT Name, State FROM Win32_Service"

Example 2: WQL Query over HTTPS with a Password File

winrmcli --hostname dev-01 --username 'ACME\admin' --password-file password.txt --https \
wql "SELECT * FROM Win32_LogicalDisk"

Example 3: Running a Remote Command

winrmcli -h dev-01 -u Administrator -pf password.txt exec ipconfig /all

Example 4: Opening an Interactive Shell

winrmcli -h dev-01 -u 'ACME\admin' -pf password.txt shell

Example 5: Kerberos Authentication over HTTPS

winrmcli --hostname dev-01 --username 'ACME\admin' --password secret --https --kerberos \
--kerberos-kdc dc-01.acme.com \
wql "SELECT * FROM Win32_OperatingSystem"

Example 6: Query with Interactive Password Input

winrmcli --hostname dev-01 --username admin wql "SELECT * FROM CIM_ManagedElement"

The CLI prompts for the password if neither --password nor --password-file is provided.