Inkcheck 🖨️

Inkcheck is a powerful and fast CLI tool built in Rust to monitor printer supply levels via SNMP.

It supports SNMP v1, v2c and v3, allowing you to check toners, drums, fusers, and waste reservoirs for a wide range of printers. It works with IPv4/IPv6 addresses and hostnames.

🚀 Features

• Async Core: Built on the Tokio runtime; supply levels are queried concurrently for fast results.
• Protocol Support: Full support for SNMP v1, v2c, and v3.
• Network Discovery: Effortlessly find local network printers using mDNS.
• Inventory: Manage your printers via a configuration file and query them by alias.
• Detailed Supplies: Checks Toner, Drum, Fuser, and Waste Reservoir levels.
• Metrics: Optional display of total, mono, and color impression counts.
• Automation Ready: Output data in JSON or CSV formats for easy integration with spreadsheets and monitoring tools.
• Robustness: Configurable timeout and retry logic for unreliable networks.
• Low Supply Highlighting: Levels at or below 25% are shown in yellow, and at or below 10% in red.
• Security: Granular control over SNMPv3 security levels (AuthPriv, AuthNoPriv, etc.) and context names.
• Theming: Multiple visual themes for the terminal.

📦 Installation

You can find pre-built binaries, installers (.msi), and automated installation scripts (.ps1, .sh) on the Releases page.

Windows Users: If you encounter a "SmartScreen" warning when running the MSI, click "More info" → "Run anyway". This is normal for unsigned open-source tools.

Or install from source (Cargo)

Prerequisites

• Rust (latest stable version).

Cloning the Repository

git clone https://github.com/allansomensi/inkcheck.git
cd inkcheck

Install

cargo install --path .

💻 Development Setup

To use the development scripts, install just:

cargo install just

⚙️ Configuration (Inventory)

Inkcheck features an inventory system that allows you to save frequently accessed printers.

1. Initialize the configuration:

Run the following command to create the default configuration file:

inkcheck --init

This will create an inkcheck.toml file in your system's default configuration directory and print its location:

OS	Path
Linux	~/.config/inkcheck/inkcheck.toml
macOS	~/Library/Application Support/com.allansomensi.inkcheck/inkcheck.toml
Windows	%APPDATA%\allansomensi\inkcheck\config\inkcheck.toml

On Linux and macOS the file is created readable only by you (0600), since it may contain SNMP passwords.

2. Add Printers:

Edit the generated file to add your printers using aliases.

Example:

[[printers]]
alias = "reception"
host = "192.168.1.50"
community = "public"
snmp_version = "v2c"

Available keys: alias, host, port, snmp_version, community, security_level, username, context_name, auth_protocol, auth_password, privacy_protocol, privacy_password, extra_supplies, metrics, timeout and retries. Unknown keys and invalid values are reported as errors.

3. Use the Alias:

inkcheck reception

Options passed on the command line take precedence over the values saved for the alias, e.g. inkcheck reception -t 10.

🔧 Usage

Run with the following command:

inkcheck [COMMAND | HOST | ALIAS] [OPTIONS]

Commands

• scan - Discovers printers on the local network using mDNS (-t, --timeout sets how long to listen, default: 5s).

General Options

• --init - Initialize the configuration file
• -p, --port [PORT] - SNMP service port (default: 161)
• -t, --timeout [SECONDS] - Timeout in seconds (default: 5)
• -r, --retries [COUNT] - Number of retries after a timeout (default: 3)
• -m, --metrics - Show impression counts (Total/Mono/Color)
• -e, --extra-supplies - Show extra supplies (drums, fuser, waste reservoir) and the serial number
• -d, --data-dir [DIR] - Directory with custom printer OID mappings (falls back to the built-in data)
• -o, --output [FORMAT] - Output format: text, json or csv (default: text)
• --theme [THEME] - CLI theme (default: solid)
• -h, --help - Display help information
• -V, --version - Display version information

SNMP Connection Options

• -v, --snmp-version [VERSION] - SNMP version (default: v2c)
• -c, --community [STRING] - SNMP community (default: public)

SNMPv3 Security Options

• -u, --username [NAME] - Username
• -l, --security-level [LEVEL] - Security Level (default: auth-no-priv)
• -n, --context-name [NAME] - Context Name
• -a, --auth-protocol [PROTOCOL] - Auth Protocol (default: SHA1)
• -A, --auth-password [PASS] - Auth Password
• -x, --privacy-protocol [PROTOCOL]- Privacy Protocol (default: AES128)
• -X, --privacy-password [PASS] - Privacy Password

Environment Variables

To keep secrets out of your shell history and process list, credentials can also be provided through environment variables. Command-line options take precedence over them.

• INKCHECK_COMMUNITY
• INKCHECK_USERNAME
• INKCHECK_AUTH_PASSWORD
• INKCHECK_PRIVACY_PASSWORD

Examples:

To discover printers on your local network with a custom timeout of 10 seconds:

inkcheck scan --timeout 10

To check the supply levels of a printer at 192.168.1.10, using the moon theme, displaying extra supplies, and setting a timeout of 10 seconds:

inkcheck 192.168.1.10 --theme moon -e -t 10

Using an Inventory Alias with Metrics:

inkcheck hr-printer -m

Exporting to JSON (status messages go to stderr, so the output can be piped directly):

inkcheck reception -o json | jq .toners

SNMPv3 with AuthPriv:

inkcheck 10.0.0.5 -v v3 -u admin -l auth-priv -a sha1 -A pass123 -x aes128 -X pass321 -n context123 -t 6 -r 4 -m -e

The same, reading the passwords from environment variables:

export INKCHECK_AUTH_PASSWORD=pass123 INKCHECK_PRIVACY_PASSWORD=pass321
inkcheck 10.0.0.5 -v v3 -u admin -l auth-priv -a sha1 -x aes128 -n context123

🎨 Themes

Supports multiple visual themes for better readability and personalization. Below are the available themes:

• Solid
• Shades
• Moon
• Circles
• Stars
• Vintage
• Diamonds
• Blocks
• Emoji

---

🖨️ Tested Printers

Below is a list of printers that have been tested:

• Brother MFC-L6702DW
• Brother MFC-L8900CDW
• Brother MFC-J6935DW
• Brother MFC-7460DN
• Brother DCP-L5652DN
• Brother DCP-8152DN
• Brother DCP-8157DN
• Brother HL-L6202DW
• Brother HL-L2360DW
• Brother HL-5350DN
• Brother L2540
• OKI B431
• Xerox C8030
• Epson WF-C5790

If you've tested with another printer model, feel free to contribute by adding it to the list!

If your printer is not supported yet, you can describe its OIDs in a JSON file and point Inkcheck to it with --data-dir. See the contributing guide for the file format.

---

📬 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests. Please read the contributing guide first.