Keywords: Programming, CUPS Command File Format

# 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

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

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

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

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