Command-line printing (Linux & macOS)
Print a .pos template without opening the GUI.
Run posprint cli-help to print this section from the binary (no GUI required).
Syntax
posprint list
posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
posprint link <file.pos>
Short form:
posprint list
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
posprint print receipt.pos -p /dev/rfcomm0 --set StoreName="My Shop" --set DocumentNumber=1001
posprint link receipt.pos
Rules
posprint list: print discovered printers (USB, USB-serial, paired Classic Bluetooth SPP). Use the device path from the list as-p.--printer/-p(required): printer id fromposprint list(e.g.usb:28e9:0289:0:1orusb:28e9:0289),auto(first discovered printer), or serial device path (e.g./dev/ttyUSB0,/dev/ttyACM0,/dev/rfcomm0,/dev/cu.usbserial-*).--set NAME=VALUE(required for every parameter): one flag per${Name}or$[Name]in the template.- Checkbox params (
$[Name]): usetrue/false(also1/0,yes/no). - If any text
${Name}is missing or empty, or a$[Name]is omitted / not a boolean, the command fails. - The GUI is not started when using the
printsubcommand. posprint linkencodes the.posfile as aposprint://URL on stdout (see POSPRINT-URL.md). Warns if the URL is very long.
Permissions
Your user must be in the dialout group:
sudo usermod -aG dialout "$USER"
# log out and back in
groups
Examples
posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
--set StoreName="Corner Cafe" \
--set DocumentNumber=42 \
--set Date=2026-07-15 \
--set GrandTotal=19.99
Printer device
posprint list
ls -l /dev/ttyUSB* /dev/ttyACM* /dev/rfcomm* 2>/dev/null
Use the device node shown when the printer is connected. Pair a Classic Bluetooth SPP printer in the OS first; BLE is not supported.
Exit codes
| Code | Meaning |
|---|---|
0 | Printed successfully |
1 | Error (missing parameters, parse error, permission denied, etc.) |
Help
posprint print --help
posprint link --help
posprint --help
Launch the graphical designer by running posprint with no subcommand. Opening a posprint://… URL (from a browser) or posprint --print starts print-only mode: live preview on the left, parameters and printer on the right.
After package install, if posprint:// links do not open:
xdg-mime default posprint-url.desktop x-scheme-handler/posprint
Source
| 1 | # Command-line printing (Linux & macOS) |
| 2 | |
| 3 | Print a `.pos` template without opening the GUI. |
| 4 | |
| 5 | Run `posprint cli-help` to print this section from the binary (no GUI required). |
| 6 | |
| 7 | ## Syntax |
| 8 | |
| 9 | ```bash |
| 10 | posprint list |
| 11 | posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...] |
| 12 | posprint link <file.pos> |
| 13 | ``` |
| 14 | |
| 15 | Short form: |
| 16 | |
| 17 | ```bash |
| 18 | posprint list |
| 19 | posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001 |
| 20 | posprint print receipt.pos -p /dev/rfcomm0 --set StoreName="My Shop" --set DocumentNumber=1001 |
| 21 | posprint link receipt.pos |
| 22 | ``` |
| 23 | |
| 24 | ## Rules |
| 25 | |
| 26 | - **`posprint list`**: print discovered printers (USB, USB-serial, paired Classic Bluetooth SPP). Use the device path from the list as `-p`. |
| 27 | - **`--printer` / `-p`** (required): printer id from `posprint list` (e.g. `usb:28e9:0289:0:1` or `usb:28e9:0289`), `auto` (first discovered printer), or serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/rfcomm0`, `/dev/cu.usbserial-*`). |
| 28 | - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` or `$[Name]` in the template. |
| 29 | - Checkbox params (`$[Name]`): use `true`/`false` (also `1`/`0`, `yes`/`no`). |
| 30 | - If any text `${Name}` is missing or empty, or a `$[Name]` is omitted / not a boolean, the command **fails**. |
| 31 | - The GUI is not started when using the `print` subcommand. |
| 32 | - **`posprint link`** encodes the `.pos` file as a `posprint://` URL on stdout (see [POSPRINT-URL.md](POSPRINT-URL.md)). Warns if the URL is very long. |
| 33 | |
| 34 | ## Permissions |
| 35 | |
| 36 | Your user must be in the **`dialout`** group: |
| 37 | |
| 38 | ```bash |
| 39 | sudo usermod -aG dialout "$USER" |
| 40 | # log out and back in |
| 41 | groups |
| 42 | ``` |
| 43 | |
| 44 | ## Examples |
| 45 | |
| 46 | ```bash |
| 47 | posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \ |
| 48 | --set StoreName="Corner Cafe" \ |
| 49 | --set DocumentNumber=42 \ |
| 50 | --set Date=2026-07-15 \ |
| 51 | --set GrandTotal=19.99 |
| 52 | ``` |
| 53 | |
| 54 | ## Printer device |
| 55 | |
| 56 | ```bash |
| 57 | posprint list |
| 58 | ls -l /dev/ttyUSB* /dev/ttyACM* /dev/rfcomm* 2>/dev/null |
| 59 | ``` |
| 60 | |
| 61 | Use the device node shown when the printer is connected. Pair a Classic Bluetooth SPP printer in the OS first; BLE is not supported. |
| 62 | |
| 63 | ## Exit codes |
| 64 | |
| 65 | | Code | Meaning | |
| 66 | |------|---------| |
| 67 | | `0` | Printed successfully | |
| 68 | | `1` | Error (missing parameters, parse error, permission denied, etc.) | |
| 69 | |
| 70 | ## Help |
| 71 | |
| 72 | ```bash |
| 73 | posprint print --help |
| 74 | posprint link --help |
| 75 | posprint --help |
| 76 | ``` |
| 77 | |
| 78 | Launch the graphical designer by running `posprint` with **no** subcommand. Opening a `posprint://…` URL (from a browser) or `posprint --print` starts print-only mode: live preview on the left, parameters and printer on the right. |
| 79 | |
| 80 | After package install, if `posprint://` links do not open: |
| 81 | |
| 82 | ```bash |
| 83 | xdg-mime default posprint-url.desktop x-scheme-handler/posprint |
| 84 | ``` |