You are here: Administration > Tools - database, server-command scripting, and APIs (Advanced) > Configure the User Client using the command-line

Configure the User Client using the command-line

The User ClientThe User Client tool is an add-on that resides on a user's desktop. It allows users to view their current account balance via a popup window, provides users with the opportunity to confirm what they are about to print, allows users to select shared accounts via a popup, if administrators have granted access to this feature, and displays system messages, such as the "low credit" warning message or print policy popups. is used to display user balances, system notifications, and request information from the users. This is discussed in more detail in User Client. The User Client implements a number of command-line options that change its behavior.

Command-line options

Note: The command-line arguments listed below are usually used in the area/method used to start the client - a login script, shortcut, or the relevant registry key in HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run\.
Table 96: User Client command-line options
Option Description
--silent The silent option tells the client not to report errors if it has problems connecting to the server. If the server is unavailable at time of startup (e.g. the client is not connected to the network), or if the user does not currently exist in the database, the client sleeps, waiting for the condition to change. This option can also be set by adding a silent=Y line to the client config.properties.
--debug The debug option tells the client to log activity to a file called user-client.log, which is created in the user's home directory. This option can also be set by adding a debug=Y line to the client config.properties.
--minimized The minimized option tells the client to start minimized. On Windows, the client is minimized to the task tray. On a Mac, the balance window is hidden and the Status menu displays the PaperCut menulet. This option is recommended if the user's balance is not important to the user. For example, if a user is only allowed to assign print jobs to a shared accountA shared account is an account that is shared by multiple users. For example, in business, shared accounts can be used to track printing costs by business unit, project, or client. Organizations like legal firms, engineering firms, or accounting offices often have long lists of accounts, projects, clients, or matters. In a school or university, shared accounts can be used to track printing by departments, classes, or subjects., then their personal balance is of little importance, so the User Client should be minimized. This option can also be set by adding a minimized=Y line to the client config.properties.
--noquit Stops the user from closing or quitting the client where possible. This option can also be set by adding a noquit=Y line to the client config.properties.
--disabletasktrayicon The option tells the client to hide the task tray icon. This option can also be set by adding a disabletasktrayicon=Y line to the client config.properties.
--disable-toast-notifications This option instructs the client to display messages in notification area balloon tips (if enabled) rather than messages in Toast notification popups. (Windows only) This option can also be set by adding a disable-toast-notifications=Y line to the client config.properties.
--disable-balloon-tips This option instructs the client to display messages in Toast notification popups (if enabled) rather than notification area balloon tips. (Windows only) This option can also be set by adding a disable-balloon-tips=Y line to the client config.properties.
--hide-balance This option instructs the client to hide the user balance. On Windows, the balance window is not displayed. On other platforms, the balance is hidden from the balance window. This option can also be set by adding a hide-balance=Y line to the client config.properties.
--user <username> The user option allows the client to be run using a different username. This is useful if the user is logged into a machine with a username different to the username authenticated with the server/printers. For example, if a user is using a laptop that is not a part of the domain. This option can also be set by adding a user=<username> line to the client config.properties.
--cache <cache directory> This argument is actioned by pc-client-local-cache.exe. It defines the location of the globally writable cache directory on the system's local hard drive. The cache is used to minimize network traffic on future launches. The default location is C:\Cache. Standard users need WRITE and READ access to this directory. You can also use system variables, such as --cache %TEMP% to write to e.g. C:\Users\[username]\AppData\Local\Temp, in order to minimize potential permissions issues for non admin users writing to the C: drive.
--neverrequestidentity The client uses the username of the logged-in user to identify itself with the server. In a domain environment, users always log in using their network identity and the names always match. However, on non-domain systems where local accounts are used (e.g. laptops), these names might not match. The client displays a popup requesting the user to confirm their identity. This option suppresses this dialog. This option can also be set by adding a neverrequestidentity=Y line to the client config.properties.
--windowposition <position> Specify where the client window should be displayed. The valid options include top-left, top-right, bottom-left or bottom-right. In addition to the above set of fixed positions, coordinates of the window can also be specified by setting the <position> parameter to XY<x>,<y>. The <x> value sets the x-coordinate of the window (if negative, the value indicates the distance from the right of screen). The <y> value sets the y-coordinate of the window (if negative, the value indicates the distance from the bottom of screen). Some examples include:
  • XY100,100 - position the window 100 pixels from the left and 100 pixels from the top of the screen.

  • XY-50,100 - position the window 50 pixels from the right and 50 pixels from the top of the screen.

  • XY50,-100 - position the window 50 pixels from the left and 100 pixels from the bottom of the screen.

The window position can also be set by adding a windowposition=<position> line to the client config.properties.
--windowtitle <title> Allows the window title to be customized. If the <title> includes {0} then this is replaced by the user's username. The window title can also be set by adding a windowtitle=<title> line to the client config.properties.
--background-color <color> Changes the background color of the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the background color to red, use:

--background-color=FF0000

The balance window background color can also be set by adding a background-color=<color> line to the client config.properties.
--text-color <color> Changes the text color of the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the text color to blue, use:

--text-color=0000FF

The balance window text color can also be set by adding a text-color=<color> line to the client config.properties.
--link-color <color> Changes the color of the link on the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the link color to a dark gray, use:

--link-color=333333

The balance window link color can also be set by adding a link-color=<color> line to the client config.properties.
--link-hover-color <color> Changes the color of the mouseover link on the client's balance window. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set the link color to a black, use:

--link-hover-color=000000

The balance window mouseover link color can also be set by adding a link-hover-color=<color> line to the client config.properties.
--negative-balance-color <color> Changes the color of the credit balance when it is negative. By default this is red. The colors are coded in standard hexadecimal RGB ("web colors", see http://en.wikipedia.org/wiki/Web_colors for an explanation). E.g. to set negative balance color to black, use:

--negative-balance-color=000000

The negative balance color can also be set by adding or enabling the negative-balance-color=<color> line in the client config.properties file.
--default-selection <option> Specifies the default selected option on the account selection popup. Use this option to save mouse clicks / keyboard presses by setting the default selected option to the one that is most commonly used. Options include:
  • charge-personal - The "Charge to my personal account" option is selected.

  • charge-account-list - The "Charge to shared account" option is selected.

  • charge-account-pin - The "Charge to shared account using PIN / Code" option is selected.

  • print-as-user - The "Perform print as user" option is selected.

For example, applying a default selection of charge-account-list ensures that the option Charge to shared account is selected, and the list of accounts is highlighted. This allows the user to begin navigating the list of shared accounts immediately via the keyboard, and saves them having to select the option first. This option can also be set by adding or enabling the default-selection=<option> line in the client config.properties file.
--default-account <option> Specifies the default selected account on the account selection popup. Use this option to save mouse clicks / keyboard presses by setting the default selected account to the one that is most commonly used. NOTE: The default shared account can also be set on the user's account selection options. See The account selection popup. For example, setting the default account to "sales\invoices" results in this account being selected when the account selection popup shows. This allows the user to quickly confirm the selection by just clicking OK when the print should be charged to this account. The selection can still be changed if the print should not be charged to this account. This option can also be set by adding or enabling the default-account=<option> line in the client config.properties file. If set, this overrides the default account setting on the user's account selection options.
--default-account-pin <option> Specifies the default account PIN entered on the account selection popup. Use this option to save typing by setting the default account PIN to the one that is most commonly used. Without this option, the account PIN field on the account selection popup shows the account PIN last entered in this field. If the option is specified but left blank (--default-account-pin ""), the account PIN field is blank on every popup. You can also specify this option by adding or enabling the default-account-pin=<option> line in the client config.properties file.
--accounts-file <account-file-path> Specifies the location of the local accounts file to load. For more information, see Manage large client billing databases.
--auth-ttl-values <ttl-value-mins> Comma-separated list of authentication time-to-live values in minutes. This overrides the values configured on the server. See Popup authentication. This option can also be set by adding or enabling the auth-ttl-values= line in the client config.properties file.
--auth-ttl-default <default-mins> The default time-to-live value automatically selected when the login authentication window displays. This overrides the value configured on the server. This option can also be set by adding or enabling the auth-ttl-default= line in the client config.properties file.
--lockdir <lockdir> Define an alternate lock directory location.
--disable-auth-by-id-number Reverts user authentication method to user/password instead of ID Number and PIN.

Configuration properties file

The command-line arguments can also be set in the config.properties file. This is particularly helpful on Apple Mac systems where command-line arguments are difficult to implement. The config.properties file is located in the same directory as the client executable on Linux and Windows. On the Mac it is located at:

[app-path]/PCClient.app/Contents/Resources/config.properties

Additionally, you can change the settings at the user-level by placing a file in the user's Library Preferences folder located at:

~/Library/Preferences/PCClient/config.properties

The file should contain the options in a properties file form like:

user=mary

minimized=Y

windowposition=top-left

windowtitle=Print Balance: {0}

Other options allow text in the Print Job Notification window to be customized. For example:

account-from-list-text=Charge to a cost center

makes the Print Job Notification window look like the image below after the client is restarted. The full set of options is defined in the config.properties.tmpl file in the client directory above.

Changing the time after which jobs are deleted when awaiting popup response

If a user does not respond to the account selection popup after a defined time, their print job is automatically deleted. This is to prevent a buildup of old jobs in the print queueA print queue displays information about documents that are waiting to be printed, such as the printing status, document owner, and number of pages to print. You can use the print queue to view, pause, resume, restart, and cancel print jobs.. The default timeout is 10 minutes. Change the timeout as follows:

  1. Click the Options tab.

    The General page is displayed.

  2. In the Client Software area, in Delete jobs awaiting popup response after, enter the number of minutes to wait for users to respond to the popup before their job is deleted.

  3. Click Apply.


Comments

Share your findings and experience with other PaperCut users. Feel free to add comments and suggestions about this Knowledge Base article. Please don't use this for support requests.