Skip to content

PCoIP Client Parameters

The following table outlines command line parameters that are available to use and customize:

Short Long                                          Default Description
-? --help Display help message. Set to false by default.
-v --version Print version information. Set to false by default.
-u --username Username sent to Connection Broker.
-p --password Password sent to Connection Broker.
-d --domain Domain sent to Connection Broker.
-b --connection-broker Connection broker URL.
-l --log-level Unset force log level (will override config/registry)
-w --windowed False run inside a window.
-f --fullscreen False run in full-screen mode. The default is to run in windowed mode.
-s --security-mode Security mode.
- --locale Set locale.
- --disable-usb Disable USB.
-h --hard-host Hard host URL. This option is ignored if connection-broker is provided
--quit-after-disconnect Do no re-enter the pre-session after leaving the in-session.
--usb-auto-forward Auto-forward all non-HID devices.
--vidpid-auto-forward String of VID, PID hex values separated by spaces.
--vidpid-black-list Blocks specific VID,PIDs from autoforward regardless of whether the usb-auto-forward parameter or the USB dialog is used.
--disable-menubar Disables the PCoIP Client menubar. Prevents the user from accessing menu functionality.
--disable-hotkeys Disables session hot keys.
--full-screen Activates full-screen mode from windowed mode in a PCoIP Session.
--set-host-resolution Locks the resolution of your host application displays.
--enable-scaling Enables scaling on the PCoIP Client without having to specify the desktop resolution.
--maintain-aspect-ratio Maintains the aspect ratio between the host and client.
--force-native-resolution Sets the resolution of the client monitor to the native resolution when the session client's launched .
--desktop Enables users to select which desktop they which to use.

For example, running the --help command will have the following format:

$ /Applications/PCoIPClient.app/Contents/MacOS/PCoIPClient --help

Enabling Accessibility Permissions for PCoIP Client

The keyboard handling of the PCoIP Client for macOS has be updated to handle new default handling for the CMD key to capture and send to remote systems. In order for this new keyboard handling to function, the PCoIP Client application must be authorized under System Preferences > Security & Privacy > Accessibility, not authorizing the application will result in the Keyboard not functioning in a PCoIP session.

When the PCoIP Client is opened for the first time on a Mac it should prompt the user to authorize the Accessibility permission. This requires the user to accept the prompt and enter the password. If this is declined, the prompt will not appear again and the Accessibility permission must be configured manually from within System Preferences.

The following steps outline how to manually set the accessibility permission:

  1. Open System Preferences.
  2. Click on Security & Privacy.
  3. Select the Privacy tab.
  4. Select the Accessibility option.
  5. Click the Lock icon on the bottom left corner and authenticate using your password or touch ID.
  6. Click the check mark beside PCoIP Client as outlined in the image below.

Alt Text

Customizable Session Features

The following PCoIP session features can be customized:

Examples show command-line usage

Some of the examples shown here invoke the PCoIP Software Client via the command line. You can also set these priorities when invoking the PCoIP Software Client programmatically.

Session Menu Bar Visibility

To enhance the user experience the PCoIP Session Client enables the menu bar by default, however some use cases may require that it be disabled, or hidden, in order to prevent the user from accessing menu functionality. To disable the menu bar feature use the parameter disable-menubar.

Disable Hot Keys

To improve usability, session hot keys, such as Ctrl+Delete+F12 (which disconnects a PCoIP session) are available to users by default. The parameter for this feature is disable-hotkeys.

Windowed or Fullscreen Mode

Depending on your application needs, you can display the PCoIP session in either windowed or fullscreen mode. Fullscreen mode allows the display topology to support multiple monitors as an extended desktop; windowed mode gives you the flexibility to display multiple application windows in parallel and switch between them quickly. Windowed mode improves the user experience, as well as resulting in an increase in performance. Windowed mode is the default mode, and to activate fullscreen mode use the full-screen parameter.

Set Host Resolution

Normally, the session client opens with arbitrary window dimensions. In some cases, you may wish to lock the resolution of your host application displays. This ensures the user’s viewing experience is consistent across different monitors and their native resolutions. The parameter for this feature is set-host-resolution.

  • Host Resolution Limitations: It is only possible to specify one target resolution for all displays. The host resolution will not perform to its optimal capability if you have monitors with different resolutions.

Image Scaling

The image scaling feature enables scaling on the client without having to specify the desktop resolution. You can apply image scaling when the resolution of the client monitor is not the same as the resolution provided by the host. This feature provides a smoother process for image scaling on the client. The parameter for this feature is enable-scaling.

Maintain Aspect Ratio

If the host and client aspect ratios do not match, and this parameter is not used then the display will be stretched to fit. The parameter for this feature is maintain-aspect-ratio. If the native aspect ratios of the host’s display and the client’s display do not match, the host’s aspect ratio will be preserved and will appear in the client with black bars either on the sides or top and bottom of the display.

PCoIP Client Keyboard Handling

When the PCoIP Software Client for macOS is the foreground application it will capture system level keyboard shortcuts such as CMD+TAB and CMD+SPACE and send them to the remote machine. This is enabled by default with the mac_system_shortcut_capture OS setting which you need to set in the com.teradici.Teradici PCoIP Client.plist file. These shortcuts will no longer be actioned on the local machine when the PCoIP Software Client for macOS is in focus. The CMD key will no longer be mapped to the CTRL key even if the remap_cmd_to_ctrl setting is enabled and set in the com.teradici.Teradici PCoIP Client.plist file. You will need to enable accessibility permissions on the PCoIP Client in order for the keyboard to function with these changes. Instructions for how to enable these permissions are outlined above.

The mac_capture_all_keys setting captures all keys and modifiers on the PCoIP Software Client system when the PCoIP Software Client for macOS is in focus, except for the Fn keys when they are enabling special functions, such as keyboard brightness, volume, etc. This setting is enabled by default.

The remap_cmd_to_ctrl setting is a pre-existing setting which controlled whether the command key would map to Control, or the Windows (Super on Linux) key. This setting is disabled by default. It can be enabled if necessary by first disabling the mac_system_shortcut_capture and mac_capture_all_keys setting.

Launching PCoIP Software Client with a URI

It is possible to launch the PCoIP Software Client with a URI. The Teradici URI uses JSON Web Tokens (JWT). For more information on the use of JWT, see here. The URI is defined as the following:

pcoip://[broker]/connect[?data={jwt}]

When additional parameters are passed through the encoded JWT a session can be launched:

Field Description Optional vs Required
pcoip:// Scheme registered to operating system so that PCoIP Client can be launched Required
broker Broker through which a pcoip session is supposed to be brokered through Optional
/connect Connecting to a PCoIP Client with the parameters defined in "?data" Required
?data Query parameter to store a jwt encoded user credentials Optional

The table below details supported optional JWT payload claims:

Claim Description
usr Username
dom Domain
vm Virtual machine/resource name
sid Broker JSESSIONID

Below is an example of a JWT payload:

{
    "usr": "username",
    "dom": "mydomain.com",
    "vm": "mydesktopname"
}
The following is an example of a connect command:

pcoip://fake.broker.com/connect?data=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3IiOiJ1c2VybmFtZSIsImRvbSI6Im15ZG9tYWluLmNvbSIsInZtIjoibXlkZXNrdG9wbmFtZSJ9.Mf3uoeZT8VQbVq7Gp0QQGbh8EqYtrIlp_E9jF2iI31Q