Use the macOS command line interface for Windows App

Windows App for macOS provides a command line interface (CLI) that you can use to perform various tasks as an alternative to the user interface. Using the CLI can be more efficient for some tasks, especially when you need to perform the same task multiple times or automate a task. On macOS, you use the in-built Terminal app to run the CLI commands.

This article shows you how to use the macOS CLI for Windows App.

Prerequisites

Before you can use the CLI for Windows App on macOS, you need to install the Windows App for macOS. For more information, see Get started with Windows App to connect to devices and apps.

Run commands

To run a command using the CLI for Windows App:

1. Open the Terminal app on your macOS device.

2. The default path that contains the Windows App executable is /Applications/Windows App.app/Contents/MacOS, which is case-sensitive. Change to this directory by running the following command:

   cd '/Applications/Windows App.app/Contents/MacOS'
   

3. From this location, you can run the Windows App executable with different modules. To check you can run commands, print the help message by running the following command:

   ./'Windows App' --script
   

   The output is as follows:

   Usage:
   
     --script <module> <parameters>
   
     Modules:
   
       bookmark  Create, edit or delete a connection bookmark.
       feed      Subscribe to a resource feed, or edit or delete a subscription.
       gateway   Create, edit or delete a Remote Desktop gateway.
       defaults  Display client settings configurable through the defaults command
   
     To get help for a specific module:
   
       --script <module> help
   
     Examples:
   
       --script bookmark help
       --script feed help
       --script gateway help
   

4. The available modules are listed in the output from the previous command. You can get the full syntax for each module by adding the module name, followed by help, as shown in the output of the previous step. For example, to print the help information for the bookmark module, run the following command:

   ./'Windows App' --script bookmark help
   

   The output is as follows:

   Usage:
   
     --script bookmark <command> <unique ID> <parameter>
   
     Commands:
   
       write   Create or edit a connection bookmark.
       delete  Delete a connection bookmark.
       list    List all stored bookmarks.
       export  Output a bookmark as a formatted string.
   
     To get help for a specific command:
   
       --script bookmark <command> help
   
     Examples:
   
       --script bookmark write help
       --script bookmark delete help
       --script bookmark list help
       --script bookmark export help
   

5. Finally, you can also iterate through each command for each module to print the help information by adding the command name, followed by help, as shown in the output of the previous step

The help information available in Windows App for each module and command provides usage instructions, parameter details, and examples of how to use each command.

Module tips

The following tips can help you use the CLI for Windows App more effectively:

• For commands that require a unique ID, you can run the command uuidgen in the Terminal app to generate a unique ID.

• To edit a saved bookmark, enter the same unique ID as the one you used to create the bookmark. The write command updates the existing bookmark with the new information.

• For the feed module, only a Remote Desktop Services environment that uses username and password authentication can be added. You can't add Azure Virtual Desktop, Windows 365, or Microsoft Dev Box resources because it uses claims-based authentication.