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:
*cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels ReportStatus"
cupsCommands keyword is provided, the command filter
ReportLevels. The scheduler also
printer-commands attribute containing the list of
CUPS command files are ASCII text files. The first line of a CUPS command file MUST contain:
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
The following are the standard commands supported by the format. The only
required command is
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.
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".
#CUPS-COMMAND Clean all
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.
#CUPS-COMMAND PrintAlignmentPage 1
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.
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
ReportStatus command queries the printer for its current
status and reports it using "STATE:" messages sent to the scheduler.
SetAlignment pass value ... valueN
SetAlignment command sets print head alignment values. The
"pass" parameter is a number from 1 to N. All parameters are
#CUPS-COMMAND SetAlignment 1 14