printer-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. printer_cli-0.1.0/.gitignore +15 -0
  2. printer_cli-0.1.0/CHANGELOG.md +24 -0
  3. printer_cli-0.1.0/LICENSE +21 -0
  4. printer_cli-0.1.0/PKG-INFO +229 -0
  5. printer_cli-0.1.0/README.md +194 -0
  6. printer_cli-0.1.0/pyproject.toml +61 -0
  7. printer_cli-0.1.0/src/prt/__init__.py +3 -0
  8. printer_cli-0.1.0/src/prt/__main__.py +3 -0
  9. printer_cli-0.1.0/src/prt/cache.py +43 -0
  10. printer_cli-0.1.0/src/prt/cli.py +834 -0
  11. printer_cli-0.1.0/src/prt/config.py +127 -0
  12. printer_cli-0.1.0/src/prt/discovery.py +121 -0
  13. printer_cli-0.1.0/src/prt/drivers/__init__.py +0 -0
  14. printer_cli-0.1.0/src/prt/drivers/base.py +90 -0
  15. printer_cli-0.1.0/src/prt/drivers/epson.py +88 -0
  16. printer_cli-0.1.0/src/prt/drivers/fake.py +86 -0
  17. printer_cli-0.1.0/src/prt/drivers/ipp.py +335 -0
  18. printer_cli-0.1.0/src/prt/drivers/registry.py +54 -0
  19. printer_cli-0.1.0/src/prt/fixtures/__init__.py +0 -0
  20. printer_cli-0.1.0/src/prt/fixtures/epson-xp6000.json +62 -0
  21. printer_cli-0.1.0/src/prt/maintenance.py +49 -0
  22. printer_cli-0.1.0/src/prt/media.py +60 -0
  23. printer_cli-0.1.0/src/prt/models.py +192 -0
  24. printer_cli-0.1.0/src/prt/printing.py +103 -0
  25. printer_cli-0.1.0/src/prt/style.py +325 -0
  26. printer_cli-0.1.0/src/prt/testpage.py +71 -0
  27. printer_cli-0.1.0/src/prt/transport/__init__.py +0 -0
  28. printer_cli-0.1.0/src/prt/transport/escl.py +201 -0
  29. printer_cli-0.1.0/src/prt/transport/ipp.py +364 -0
  30. printer_cli-0.1.0/src/prt/transport/snmp.py +140 -0
  31. printer_cli-0.1.0/src/prt/tui/__init__.py +0 -0
  32. printer_cli-0.1.0/src/prt/tui/app.py +495 -0
  33. printer_cli-0.1.0/src/prt/tui/app.tcss +308 -0
  34. printer_cli-0.1.0/src/prt/tui/widgets.py +181 -0
  35. printer_cli-0.1.0/tests/conftest.py +33 -0
  36. printer_cli-0.1.0/tests/fixtures/escl-caps.xml +1 -0
  37. printer_cli-0.1.0/tests/test_cli.py +256 -0
  38. printer_cli-0.1.0/tests/test_config.py +49 -0
  39. printer_cli-0.1.0/tests/test_drivers.py +148 -0
  40. printer_cli-0.1.0/tests/test_ipp.py +87 -0
  41. printer_cli-0.1.0/tests/test_transports.py +93 -0
  42. printer_cli-0.1.0/tests/test_tui.py +150 -0
@@ -0,0 +1,15 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .pytest_cache/
6
+ dist/
7
+ build/
8
+ .DS_Store
9
+ # local scan/print outputs
10
+ *.scan.pdf
11
+ scan-*.pdf
12
+ scan-*.jpg
13
+ .tmpcfg/
14
+ .tmpcache/
15
+ .idd/cache/
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
4
+
5
+ ## [0.1.0] - 2026-11-22
6
+
7
+ First public release of printer-cli (command: `prt`), a CLI and full-screen TUI for network printers.
8
+
9
+ ### Added
10
+ - `prt status`, `prt ink` and `prt overview`: printer state, alerts, ink levels, paper trays, waste pad, firmware, uptime and SNMP page count. `status --watch N` samples continuously.
11
+ - `prt discover` (mDNS) and `prt printers list/add/remove/default` to find and save printers under short names.
12
+ - `prt maintain nozzle-check | clean | test-page | identify`. Head cleaning is refused while ink is low or the waste pad is flagged (`--force` overrides); nozzle check, cleaning and the test page ask for confirmation first (`--yes` in scripts).
13
+ - `prt print` over IPP, with JPEG conversion for images and the local CUPS queue for PDF; `prt jobs` / `prt jobs cancel`.
14
+ - `prt scan` over eSCL/AirScan, to PDF or JPEG, including `-o -` for stdout.
15
+ - `prt tui`: keyboard-driven dashboard with ink tanks in cartridge colours, Maintain, Print, Scan and Jobs tabs, and switching between saved printers.
16
+ - Drivers: generic IPP Everywhere / AirPrint, Epson (ESC/P2 remote mode on port 9100 for maintenance), and a replay driver; `-p demo` runs every command against a captured Epson XP-6000.
17
+ - Global options `--format json`, `--no-color`, `-q`, `--timeout`, `--config`, `--verbose` protocol trace; tab-separated output when piped; shell completion.
18
+ - Last known status is cached and shown, marked as cached, when the printer is asleep.
19
+ - Configuration in `~/.config/prt/config.toml`, with `PRT_CONFIG`, `PRT_PRINTER` and `PRT_TIMEOUT` overrides.
20
+ - Multi-colour (tri-colour) cartridges are drawn as striped tanks; duplicate trays that differ only in margins are merged.
21
+ - Logo, MIT license, and a `printer-cli` command alias alongside `prt`.
22
+
23
+
24
+ [0.1.0]: https://github.com/luongnv89/printer-cli/releases/tag/v0.1.0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luong NGUYEN
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.5
2
+ Name: printer-cli
3
+ Version: 0.1.0
4
+ Summary: Your printer's dashboard in the terminal: ink, paper, alerts, nozzle checks, head cleaning, printing and scanning for network printers (IPP, eSCL, SNMP, Epson ESC/P2).
5
+ Project-URL: Homepage, https://github.com/luongnv89/printer-cli
6
+ Project-URL: Repository, https://github.com/luongnv89/printer-cli
7
+ Project-URL: Issues, https://github.com/luongnv89/printer-cli/issues
8
+ Project-URL: Changelog, https://github.com/luongnv89/printer-cli/blob/main/CHANGELOG.md
9
+ Author: Luong NGUYEN
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: airprint,cli,epson,escl,ink,ipp,printer,scanner,snmp,tui
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: Intended Audience :: System Administrators
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Printing
24
+ Classifier: Topic :: System :: Hardware
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.11
27
+ Requires-Dist: httpx>=0.27
28
+ Requires-Dist: pillow>=10.1
29
+ Requires-Dist: rich>=13.7
30
+ Requires-Dist: shellingham>=1.5.4
31
+ Requires-Dist: textual>=0.80
32
+ Requires-Dist: typer>=0.12
33
+ Requires-Dist: zeroconf>=0.132
34
+ Description-Content-Type: text/markdown
35
+
36
+ <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-white.svg"><img src="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-black.svg" alt="printer-cli" width="360"></picture></p>
37
+
38
+ <p align="center"><a href="https://pypi.org/project/printer-cli/"><img src="https://img.shields.io/pypi/v/printer-cli" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"> <a href="https://github.com/luongnv89/printer-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a></p>
39
+
40
+ Check ink, paper and alerts, run nozzle checks and head cleaning, print and scan on network printers, from a scriptable CLI or a full-screen TUI.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ uv tool install printer-cli
46
+ ```
47
+
48
+ Requires Python 3.11+. Puts `prt` on your PATH (`printer-cli` works too). Other methods: [Install options](#install-options).
49
+
50
+ ## Quick start
51
+
52
+ Check a printer's ink, paper and alerts. No printer handy? The built-in `demo` printer replays a real Epson XP-6000:
53
+
54
+ ```bash
55
+ prt -p demo status
56
+ ```
57
+
58
+ ```
59
+ ╭─┐EPSON XP-6000 Series · office┌──────────────────────────────────────────╮
60
+ │ ● idle firmware 20.50.NU30Q6 · up 4h02m │
61
+ ├──────────────────────────────────────────────────────────────────────────┤
62
+ │ ink │
63
+ │ Photo Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■···· 92% │
64
+ │ Cyan ········································ 1% ✗ replace │
65
+ │ Magenta ········································ 1% ✗ replace │
66
+ │ Yellow ■■■■···································· 12% ▲ low │
67
+ │ Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■····· 89% │
68
+ ├──────────────────────────────────────────────────────────────────────────┤
69
+ │ paper main A4 ✓ photo 4×6 ✓ disc Disc ✓ (levels not reported) │
70
+ │ waste ▲ almost full — service soon │
71
+ ╰─┘4 alerts · checked 17:42└───────────────────────────────────────────────╯
72
+ ```
73
+
74
+ Next: [Use your own printer](#use-your-own-printer) · [Commands](#commands) · [The TUI](#the-tui) · [Safety](#safety)
75
+
76
+ ## Why printer-cli
77
+
78
+ It started because the Epson XP-6000's web dashboard stopped working. printer-cli talks to the printer directly over standard protocols (IPP, eSCL, SNMP, plus Epson's ESC/P2 remote mode for maintenance). It works with most AirPrint/Mopria printers from any brand, and you can manage several printers from one place.
79
+
80
+ ## Use your own printer
81
+
82
+ ```bash
83
+ prt discover # find printers on the LAN
84
+ prt printers add office EPSON721655.local --default # save one under a short name
85
+ prt status # ink, paper, alerts
86
+ prt tui # full-screen dashboard
87
+ ```
88
+
89
+ Every command also works against the built-in replay: `prt -p demo status`, `prt -p demo tui`.
90
+
91
+ ## Status
92
+
93
+ | | Verified against the real XP-6000 | Covered by tests (replay of its data) |
94
+ |---|---|---|
95
+ | Ink, state, alerts, paper, firmware (IPP) | ✅ read live during development | ✅ |
96
+ | Page counter (SNMP) | ✅ | ✅ |
97
+ | Scanner capabilities (eSCL) | ✅ | ✅ |
98
+ | Scanning a page | ⏳ not yet | ✅ (mocked HTTP) |
99
+ | Printing (IPP / CUPS) | ⏳ not yet | ✅ (fake transport) |
100
+ | Nozzle check / head cleaning (ESC/P2 on 9100) | ⏳ not yet: bytes match gutenprint `escputil`, port 9100 is open | ✅ (byte-exact) |
101
+
102
+ ## Commands
103
+
104
+ | Command | What it does |
105
+ |---|---|
106
+ | `prt status [--watch N]` | State, alerts, ink, paper, waste pad. `--watch` prints one line per sample |
107
+ | `prt ink` | Ink levels only |
108
+ | `prt overview` | System, software and hardware: model, serial, firmware, uptime, page count, formats, media, scanner, capabilities |
109
+ | `prt discover` | mDNS scan for printers and scanners |
110
+ | `prt printers list/add/remove/default` | Manage saved printers |
111
+ | `prt maintain nozzle-check` | Print the nozzle check pattern |
112
+ | `prt maintain clean [--force]` | Head cleaning, with a safety check first (see [Safety](#safety)) |
113
+ | `prt maintain test-page` | Colour test page: ink bars, gradients, grey steps, fine lines |
114
+ | `prt maintain identify` | Flash the printer's panel |
115
+ | `prt print FILE… [-n 2] [--media 4x6] [--tray photo] [--quality high] [--mono] [--duplex]` | Print |
116
+ | `prt jobs [--all]` / `prt jobs cancel ID` | List or cancel jobs |
117
+ | `prt scan [-o file.pdf] [--type jpeg] [--dpi 600] [--mode gray] [--area full]` | Flatbed scan (`-o -` writes to stdout) |
118
+ | `prt tui` | Full-screen dashboard |
119
+
120
+ **Global options**, which can go before or after the command:
121
+ - `-p/--printer NAME|HOST` picks the printer.
122
+ - `-f/--format json` prints machine-readable output.
123
+ - `--no-color` turns colour off.
124
+ - `-q` hides notes and prints only results.
125
+ - `--timeout S` sets the network timeout in seconds.
126
+ - `--config PATH` uses a different config file.
127
+
128
+ ### Scripting
129
+
130
+ ```bash
131
+ prt ink -f json | jq -r '.inks[] | select(.state != "ok") | "\(.name): \(.level)%"'
132
+ prt status | grep '^alert' # piped output is tab-separated, no colour
133
+ prt scan -o - --type jpeg > page.jpg
134
+ ```
135
+
136
+ Exit codes: `0` ok · `1` runtime/network error (also when only cached status is shown) · `2` usage error · `3` bad input file · `130` Ctrl-C.
137
+
138
+ ## The TUI
139
+
140
+ `prt tui` opens a keyboard-driven dashboard. Inks are drawn as vertical tanks in their real cartridge colours, alongside system info, paper and alerts. Tabs: **Dashboard · Maintain · Print · Scan · Jobs**.
141
+
142
+ | Key | Action |
143
+ |---|---|
144
+ | `r` | Refresh (auto-refreshes every 10 s) |
145
+ | `n` / `c` / `i` | Nozzle check / head cleaning (both ask first) / identify |
146
+ | `p` / `s` / `j` | Print, Scan, Jobs tabs |
147
+ | `1`–`9` | Switch between saved printers |
148
+ | `q` | Quit |
149
+
150
+ ## Safety
151
+
152
+ - **Head cleaning is refused** while any ink is at or below its low level, or while the waste ink pad is flagged. Cleaning flushes ink into the pad, and a full pad locks the printer until it's serviced. `--force` overrides this, and the TUI offers "Clean anyway".
153
+ - Nozzle check, cleaning and the test page ask for confirmation first. In scripts, pass `--yes`.
154
+ - printer-cli never resets the waste ink counter or writes to the printer's EEPROM.
155
+
156
+ ## How it talks to printers
157
+
158
+ | Feature | Protocol | Notes |
159
+ |---|---|---|
160
+ | Status, ink, info, jobs, identify | IPP (631) | Small IPP codec built in, no `ipptool` needed |
161
+ | Printing | IPP Print-Job | JPEG/PWG/URF go direct; PNG etc. are converted to JPEG; **PDF and other files go through the local CUPS queue** for the same printer, matched by UUID (the XP-6000 doesn't accept PDF) |
162
+ | Scanning | eSCL / AirScan (443) | Certificate checks are skipped for the scanner host only, because printers ship self-signed certificates |
163
+ | Page counter | SNMP v1 | Printer-MIB lifetime count |
164
+ | Nozzle check, cleaning | ESC/P2 remote mode on 9100 | Byte sequences from gutenprint's `escputil` (Epson only) |
165
+
166
+ When the printer is asleep, `status` and the TUI show the **last known status** from `~/.cache/prt/`, marked as cached.
167
+
168
+ ## Configuration
169
+
170
+ `~/.config/prt/config.toml`. Override the location with `PRT_CONFIG` or `--config`. Priority order: **command-line flags > environment variables (`PRT_PRINTER`, `PRT_TIMEOUT`) > config file > defaults**.
171
+
172
+ ```toml
173
+ default = "office"
174
+
175
+ [printers.office]
176
+ host = "EPSON721655.local"
177
+
178
+ [printers.pantum]
179
+ host = "192.168.1.80"
180
+ driver = "ipp"
181
+ ```
182
+
183
+ ## Install options
184
+
185
+ With pipx:
186
+
187
+ ```bash
188
+ pipx install printer-cli
189
+ ```
190
+
191
+ From source (add `--editable` to track local changes):
192
+
193
+ ```bash
194
+ git clone https://github.com/luongnv89/printer-cli.git && cd printer-cli
195
+ uv tool install .
196
+ ```
197
+
198
+ Optional tab completion for your shell:
199
+
200
+ ```bash
201
+ prt --install-completion
202
+ ```
203
+
204
+ ## Adding a printer brand
205
+
206
+ Drivers live in `src/prt/drivers/`:
207
+ - `IPPDriver` covers any IPP Everywhere / AirPrint printer.
208
+ - `EpsonDriver` adds maintenance and counters on top of it.
209
+ - `FakeDriver` replays a captured fixture, for tests and the demo.
210
+
211
+ To add a vendor, subclass `IPPDriver`, declare its `capabilities`, override what it can do, and register it in `drivers/registry.py`. The CLI and TUI hide actions a driver doesn't support.
212
+
213
+ ## Development
214
+
215
+ ```bash
216
+ uv sync
217
+ uv run pytest # 88 tests, no printer needed
218
+ uv run prt -p demo tui
219
+ ```
220
+
221
+ ## Troubleshooting
222
+
223
+ - **"cannot reach printer"**: the printer is probably asleep. Press any button on it, or check `prt discover`.
224
+ - **Shell completion isn't detected**: write the script out manually, e.g. `_PRT_COMPLETE=source_zsh prt > ~/.zfunc/_prt`.
225
+ - **PDF won't print**: add the printer in System Settings → Printers so a CUPS queue exists, or print a JPEG.
226
+
227
+ ## License
228
+
229
+ [MIT](https://github.com/luongnv89/printer-cli/blob/main/LICENSE) © Luong NGUYEN
@@ -0,0 +1,194 @@
1
+ <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-white.svg"><img src="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-black.svg" alt="printer-cli" width="360"></picture></p>
2
+
3
+ <p align="center"><a href="https://pypi.org/project/printer-cli/"><img src="https://img.shields.io/pypi/v/printer-cli" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"> <a href="https://github.com/luongnv89/printer-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a></p>
4
+
5
+ Check ink, paper and alerts, run nozzle checks and head cleaning, print and scan on network printers, from a scriptable CLI or a full-screen TUI.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ uv tool install printer-cli
11
+ ```
12
+
13
+ Requires Python 3.11+. Puts `prt` on your PATH (`printer-cli` works too). Other methods: [Install options](#install-options).
14
+
15
+ ## Quick start
16
+
17
+ Check a printer's ink, paper and alerts. No printer handy? The built-in `demo` printer replays a real Epson XP-6000:
18
+
19
+ ```bash
20
+ prt -p demo status
21
+ ```
22
+
23
+ ```
24
+ ╭─┐EPSON XP-6000 Series · office┌──────────────────────────────────────────╮
25
+ │ ● idle firmware 20.50.NU30Q6 · up 4h02m │
26
+ ├──────────────────────────────────────────────────────────────────────────┤
27
+ │ ink │
28
+ │ Photo Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■···· 92% │
29
+ │ Cyan ········································ 1% ✗ replace │
30
+ │ Magenta ········································ 1% ✗ replace │
31
+ │ Yellow ■■■■···································· 12% ▲ low │
32
+ │ Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■····· 89% │
33
+ ├──────────────────────────────────────────────────────────────────────────┤
34
+ │ paper main A4 ✓ photo 4×6 ✓ disc Disc ✓ (levels not reported) │
35
+ │ waste ▲ almost full — service soon │
36
+ ╰─┘4 alerts · checked 17:42└───────────────────────────────────────────────╯
37
+ ```
38
+
39
+ Next: [Use your own printer](#use-your-own-printer) · [Commands](#commands) · [The TUI](#the-tui) · [Safety](#safety)
40
+
41
+ ## Why printer-cli
42
+
43
+ It started because the Epson XP-6000's web dashboard stopped working. printer-cli talks to the printer directly over standard protocols (IPP, eSCL, SNMP, plus Epson's ESC/P2 remote mode for maintenance). It works with most AirPrint/Mopria printers from any brand, and you can manage several printers from one place.
44
+
45
+ ## Use your own printer
46
+
47
+ ```bash
48
+ prt discover # find printers on the LAN
49
+ prt printers add office EPSON721655.local --default # save one under a short name
50
+ prt status # ink, paper, alerts
51
+ prt tui # full-screen dashboard
52
+ ```
53
+
54
+ Every command also works against the built-in replay: `prt -p demo status`, `prt -p demo tui`.
55
+
56
+ ## Status
57
+
58
+ | | Verified against the real XP-6000 | Covered by tests (replay of its data) |
59
+ |---|---|---|
60
+ | Ink, state, alerts, paper, firmware (IPP) | ✅ read live during development | ✅ |
61
+ | Page counter (SNMP) | ✅ | ✅ |
62
+ | Scanner capabilities (eSCL) | ✅ | ✅ |
63
+ | Scanning a page | ⏳ not yet | ✅ (mocked HTTP) |
64
+ | Printing (IPP / CUPS) | ⏳ not yet | ✅ (fake transport) |
65
+ | Nozzle check / head cleaning (ESC/P2 on 9100) | ⏳ not yet: bytes match gutenprint `escputil`, port 9100 is open | ✅ (byte-exact) |
66
+
67
+ ## Commands
68
+
69
+ | Command | What it does |
70
+ |---|---|
71
+ | `prt status [--watch N]` | State, alerts, ink, paper, waste pad. `--watch` prints one line per sample |
72
+ | `prt ink` | Ink levels only |
73
+ | `prt overview` | System, software and hardware: model, serial, firmware, uptime, page count, formats, media, scanner, capabilities |
74
+ | `prt discover` | mDNS scan for printers and scanners |
75
+ | `prt printers list/add/remove/default` | Manage saved printers |
76
+ | `prt maintain nozzle-check` | Print the nozzle check pattern |
77
+ | `prt maintain clean [--force]` | Head cleaning, with a safety check first (see [Safety](#safety)) |
78
+ | `prt maintain test-page` | Colour test page: ink bars, gradients, grey steps, fine lines |
79
+ | `prt maintain identify` | Flash the printer's panel |
80
+ | `prt print FILE… [-n 2] [--media 4x6] [--tray photo] [--quality high] [--mono] [--duplex]` | Print |
81
+ | `prt jobs [--all]` / `prt jobs cancel ID` | List or cancel jobs |
82
+ | `prt scan [-o file.pdf] [--type jpeg] [--dpi 600] [--mode gray] [--area full]` | Flatbed scan (`-o -` writes to stdout) |
83
+ | `prt tui` | Full-screen dashboard |
84
+
85
+ **Global options**, which can go before or after the command:
86
+ - `-p/--printer NAME|HOST` picks the printer.
87
+ - `-f/--format json` prints machine-readable output.
88
+ - `--no-color` turns colour off.
89
+ - `-q` hides notes and prints only results.
90
+ - `--timeout S` sets the network timeout in seconds.
91
+ - `--config PATH` uses a different config file.
92
+
93
+ ### Scripting
94
+
95
+ ```bash
96
+ prt ink -f json | jq -r '.inks[] | select(.state != "ok") | "\(.name): \(.level)%"'
97
+ prt status | grep '^alert' # piped output is tab-separated, no colour
98
+ prt scan -o - --type jpeg > page.jpg
99
+ ```
100
+
101
+ Exit codes: `0` ok · `1` runtime/network error (also when only cached status is shown) · `2` usage error · `3` bad input file · `130` Ctrl-C.
102
+
103
+ ## The TUI
104
+
105
+ `prt tui` opens a keyboard-driven dashboard. Inks are drawn as vertical tanks in their real cartridge colours, alongside system info, paper and alerts. Tabs: **Dashboard · Maintain · Print · Scan · Jobs**.
106
+
107
+ | Key | Action |
108
+ |---|---|
109
+ | `r` | Refresh (auto-refreshes every 10 s) |
110
+ | `n` / `c` / `i` | Nozzle check / head cleaning (both ask first) / identify |
111
+ | `p` / `s` / `j` | Print, Scan, Jobs tabs |
112
+ | `1`–`9` | Switch between saved printers |
113
+ | `q` | Quit |
114
+
115
+ ## Safety
116
+
117
+ - **Head cleaning is refused** while any ink is at or below its low level, or while the waste ink pad is flagged. Cleaning flushes ink into the pad, and a full pad locks the printer until it's serviced. `--force` overrides this, and the TUI offers "Clean anyway".
118
+ - Nozzle check, cleaning and the test page ask for confirmation first. In scripts, pass `--yes`.
119
+ - printer-cli never resets the waste ink counter or writes to the printer's EEPROM.
120
+
121
+ ## How it talks to printers
122
+
123
+ | Feature | Protocol | Notes |
124
+ |---|---|---|
125
+ | Status, ink, info, jobs, identify | IPP (631) | Small IPP codec built in, no `ipptool` needed |
126
+ | Printing | IPP Print-Job | JPEG/PWG/URF go direct; PNG etc. are converted to JPEG; **PDF and other files go through the local CUPS queue** for the same printer, matched by UUID (the XP-6000 doesn't accept PDF) |
127
+ | Scanning | eSCL / AirScan (443) | Certificate checks are skipped for the scanner host only, because printers ship self-signed certificates |
128
+ | Page counter | SNMP v1 | Printer-MIB lifetime count |
129
+ | Nozzle check, cleaning | ESC/P2 remote mode on 9100 | Byte sequences from gutenprint's `escputil` (Epson only) |
130
+
131
+ When the printer is asleep, `status` and the TUI show the **last known status** from `~/.cache/prt/`, marked as cached.
132
+
133
+ ## Configuration
134
+
135
+ `~/.config/prt/config.toml`. Override the location with `PRT_CONFIG` or `--config`. Priority order: **command-line flags > environment variables (`PRT_PRINTER`, `PRT_TIMEOUT`) > config file > defaults**.
136
+
137
+ ```toml
138
+ default = "office"
139
+
140
+ [printers.office]
141
+ host = "EPSON721655.local"
142
+
143
+ [printers.pantum]
144
+ host = "192.168.1.80"
145
+ driver = "ipp"
146
+ ```
147
+
148
+ ## Install options
149
+
150
+ With pipx:
151
+
152
+ ```bash
153
+ pipx install printer-cli
154
+ ```
155
+
156
+ From source (add `--editable` to track local changes):
157
+
158
+ ```bash
159
+ git clone https://github.com/luongnv89/printer-cli.git && cd printer-cli
160
+ uv tool install .
161
+ ```
162
+
163
+ Optional tab completion for your shell:
164
+
165
+ ```bash
166
+ prt --install-completion
167
+ ```
168
+
169
+ ## Adding a printer brand
170
+
171
+ Drivers live in `src/prt/drivers/`:
172
+ - `IPPDriver` covers any IPP Everywhere / AirPrint printer.
173
+ - `EpsonDriver` adds maintenance and counters on top of it.
174
+ - `FakeDriver` replays a captured fixture, for tests and the demo.
175
+
176
+ To add a vendor, subclass `IPPDriver`, declare its `capabilities`, override what it can do, and register it in `drivers/registry.py`. The CLI and TUI hide actions a driver doesn't support.
177
+
178
+ ## Development
179
+
180
+ ```bash
181
+ uv sync
182
+ uv run pytest # 88 tests, no printer needed
183
+ uv run prt -p demo tui
184
+ ```
185
+
186
+ ## Troubleshooting
187
+
188
+ - **"cannot reach printer"**: the printer is probably asleep. Press any button on it, or check `prt discover`.
189
+ - **Shell completion isn't detected**: write the script out manually, e.g. `_PRT_COMPLETE=source_zsh prt > ~/.zfunc/_prt`.
190
+ - **PDF won't print**: add the printer in System Settings → Printers so a CUPS queue exists, or print a JPEG.
191
+
192
+ ## License
193
+
194
+ [MIT](https://github.com/luongnv89/printer-cli/blob/main/LICENSE) © Luong NGUYEN
@@ -0,0 +1,61 @@
1
+ [project]
2
+ name = "printer-cli"
3
+ version = "0.1.0"
4
+ description = "Your printer's dashboard in the terminal: ink, paper, alerts, nozzle checks, head cleaning, printing and scanning for network printers (IPP, eSCL, SNMP, Epson ESC/P2)."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "Luong NGUYEN" }]
10
+ keywords = ["printer", "cli", "tui", "ipp", "escl", "airprint", "snmp", "epson", "scanner", "ink"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Environment :: Console",
14
+ "Intended Audience :: End Users/Desktop",
15
+ "Intended Audience :: System Administrators",
16
+ "Operating System :: MacOS",
17
+ "Operating System :: POSIX :: Linux",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Topic :: Printing",
23
+ "Topic :: System :: Hardware",
24
+ "Topic :: Utilities",
25
+ ]
26
+ dependencies = [
27
+ "typer>=0.12",
28
+ "rich>=13.7",
29
+ "textual>=0.80",
30
+ "httpx>=0.27",
31
+ "zeroconf>=0.132",
32
+ "pillow>=10.1",
33
+ "shellingham>=1.5.4",
34
+ ]
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/luongnv89/printer-cli"
38
+ Repository = "https://github.com/luongnv89/printer-cli"
39
+ Issues = "https://github.com/luongnv89/printer-cli/issues"
40
+ Changelog = "https://github.com/luongnv89/printer-cli/blob/main/CHANGELOG.md"
41
+
42
+ [project.scripts]
43
+ prt = "prt.cli:main"
44
+ printer-cli = "prt.cli:main"
45
+
46
+ [dependency-groups]
47
+ dev = ["pytest>=8", "pytest-asyncio>=0.23"]
48
+
49
+ [build-system]
50
+ requires = ["hatchling>=1.27"]
51
+ build-backend = "hatchling.build"
52
+
53
+ [tool.hatch.build.targets.wheel]
54
+ packages = ["src/prt"]
55
+
56
+ [tool.pytest.ini_options]
57
+ testpaths = ["tests"]
58
+ asyncio_mode = "auto"
59
+
60
+ [tool.hatch.build.targets.sdist]
61
+ exclude = ["assets", ".idd.yml", "uv.lock"]
@@ -0,0 +1,3 @@
1
+ """printer-cli (`prt`) — printer control for the terminal."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from prt.cli import entry
2
+
3
+ entry()
@@ -0,0 +1,43 @@
1
+ """Last-known-status cache so a sleeping printer still shows something useful."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+
8
+ from prt.config import cache_dir
9
+ from prt.models import Alert, Ink, Severity, Status, Tray, to_dict
10
+
11
+
12
+ def _file(name: str, base: Path | None = None) -> Path:
13
+ safe = "".join(c if c.isalnum() or c in "-_." else "_" for c in name)
14
+ return (base or cache_dir()) / f"status-{safe}.json"
15
+
16
+
17
+ def save(name: str, status: Status, base: Path | None = None) -> None:
18
+ try:
19
+ path = _file(name, base)
20
+ path.parent.mkdir(parents=True, exist_ok=True)
21
+ path.write_text(json.dumps(to_dict(status)))
22
+ except OSError:
23
+ pass # the cache is a convenience; never fail a command over it
24
+
25
+
26
+ def load(name: str, base: Path | None = None) -> Status | None:
27
+ try:
28
+ data = json.loads(_file(name, base).read_text())
29
+ except (OSError, ValueError):
30
+ return None
31
+ try:
32
+ return Status(
33
+ state="offline", accepting=False,
34
+ inks=[Ink(name=i["name"], color=i["color"], level=i["level"], low=i.get("low", 15),
35
+ high=i.get("high", 100), kind=i.get("kind", "ink-cartridge")) for i in data["inks"]],
36
+ trays=[Tray(**t) for t in data.get("trays", [])],
37
+ alerts=[Alert(a["code"], Severity(a["severity"]), a["message"]) for a in data.get("alerts", [])],
38
+ reasons=data.get("reasons", []), waste=data.get("waste"),
39
+ waste_level=data.get("waste_level"), queued_jobs=data.get("queued_jobs", 0),
40
+ checked_at=data.get("checked_at", 0), stale=True,
41
+ )
42
+ except (KeyError, TypeError, ValueError):
43
+ return None