CUPS Command File Format

Introduction

This specification describes the CUPS command file format (application/vnd.cups-command) which is used to send printer maintenance commands to a printer in a device-independent way. The current specification supports basic maintenance functions such as head cleaning and self-test pages and query functions such as auto-configure, report supply levels, and report status.

Printer drivers advertise support for the CUPS command file format by providing a filter for the application/vnd.cups-command file type. Applications can determine if a printer supports printing of CUPS command files by checking the printer-type attribute for the CUPS_PRINTER_COMMANDS capability bit.

In addition, the PPD file for a printer can contain a cupsCommands keyword that provides a list of supported commands separated by spaces, for example:

*cupsCommand: "AutoConfigure Clean PrintSelfTestPage ReportLevels ReportStatus"

If no cupsCommands keyword is provided, the command filter must support AutoConfigure, Clean, PrintSelfTestPage, and ReportLevels. The scheduler also provides the printer-commands attribute containing the list of supported commands.

File Syntax

CUPS command files are ASCII text files. The first line of a CUPS command file MUST contain:

#CUPS-COMMAND

After that, each line is either a command or a comment. Comments begin with the # character, e.g.:

# This is a comment

Commands are any sequence of letters, numbers, and punctuation characters optionally followed by parameters separated by whitespace, e.g.:

Clean all
PrintSelfTestPage

Command names are case-insensitive, so "PRINTSELFTESTPAGE", "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific commands should use a domain name prefix, e.g.:

com.vendor.foo
com.vendor.bar param param2 ... paramN

Standard Commands

The following are the standard commands supported by the format. The only required command is PrintSelfTestPage.

AutoConfigure

The AutoConfigure command updates the printer's PPD file and driver state information to reflect the current configuration of the printer. There are no arguments for this command.

Example:

#CUPS-COMMAND
AutoConfigure

Clean

Clean colorname

The Clean command performs a standard print head cleaning. The "colorname" parameter specifies which color or head to clean. If a printer does not support cleaning of individual colors or cartridges, then all colors are cleaned. Command filters MUST support the "all" colorname. Other standard color names include "black", "color", "photo", "cyan", "magenta", "yellow", "light-cyan", "light-magenta", "light-black", "light-gray", and "dark-gray".

Example:

#CUPS-COMMAND
Clean all

PrintAlignmentPage

PrintAlignmentPage pass

The PrintAlignmentPage command prints a head alignment page on the printer. The "pass" parameter provides a pass number from 1 to N. The number of passes is device-dependent.

Example:

#CUPS-COMMAND
PrintAlignmentPage 1

PrintSelfTestPage

The PrintSelfTestPage command prints a self-test page on the printer. Typically this page shows whether all jets on a print head are functioning and that the print feed mechanisms are working properly.

Example:

#CUPS-COMMAND
PrintSelfTestPage

ReportLevels

The ReportLevels command queries the supply levels on a printer and reports "marker-colors", "marker-levels", "marker-names", and "marker-types" attributes using "ATTR:" messages sent to the scheduler. This command should also report the current printer status using "STATE:" messages like the ReportStatus command.

Example:

#CUPS-COMMAND
ReportLevels

ReportStatus

The ReportStatus command queries the printer for its current status and reports it using "STATE:" messages sent to the scheduler.

Example:

#CUPS-COMMAND
ReportLevels

SetAlignment

SetAlignment pass value ... valueN

The SetAlignment command sets print head alignment values. The "pass" parameter is a number from 1 to N. All parameters are device-dependent.

Example:

#CUPS-COMMAND
SetAlignment 1 14