docs: add comprehensive README with installation and usage guides
This commit is contained in:
@@ -0,0 +1,109 @@
|
|||||||
|
# color-tool
|
||||||
|
|
||||||
|
A feature-rich, portable CLI color utility for Linux, specializing in color picking, conversion, and formatting. Designed primarily for **KDE Plasma on Wayland**, `color-tool` provides a seamless bridge between your screen and your development environment.
|
||||||
|
|
||||||
|
## 🌈 Key Features
|
||||||
|
|
||||||
|
- **Advanced Color Picking:** Integration with KWin's DBus ColorPicker for pixel-perfect selection on Wayland.
|
||||||
|
- **Robust Conversions:** Support for HEX, RGB, HSL, and their Alpha-enabled counterparts (HEXA, RGBA, HSLA).
|
||||||
|
- **Format Flexibility:** Request multiple formats at once, or use `all` for a complete breakdown.
|
||||||
|
- **Smart JSON Output:** Generate machine-readable JSON tables for easy integration with other tools.
|
||||||
|
- **Color Naming:** Resolve hex values to human-readable names via thecolorapi.com.
|
||||||
|
- **Visual Previews:** Render color swatches directly in your terminal using truecolor ANSI escapes.
|
||||||
|
- **Desktop Integration:** Built-in support for clipboard copying (`wl-copy`/`xclip`) and desktop notifications.
|
||||||
|
- **Highly Configurable:** Separate configuration profiles for standard terminal usage and desktop/launcher mode.
|
||||||
|
- **Portable Design:** The entire tool is contained within a single Bash script, with embedded Python helpers.
|
||||||
|
|
||||||
|
## 📋 Prerequisites
|
||||||
|
|
||||||
|
To utilize all features, ensure the following are installed:
|
||||||
|
- **KDE Plasma + Wayland:** Required for the `--pick` functionality.
|
||||||
|
- **Python 3 + PyQt6:** Required for the picker helper.
|
||||||
|
- **curl + jq:** Required for color naming support.
|
||||||
|
- **wl-clipboard** (Wayland) or **xclip** (X11): Required for clipboard support.
|
||||||
|
- **libnotify:** Required for desktop notifications (`notify-send`).
|
||||||
|
|
||||||
|
## 🚀 Installation
|
||||||
|
|
||||||
|
Simply download the `color-tool` script and run the install command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod +x color-tool
|
||||||
|
./color-tool --install
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
1. Move the script to `~/.local/share/color-tool/`.
|
||||||
|
2. Symlink the binary to `~/.local/bin/color-tool`.
|
||||||
|
3. Generate a sample configuration at `~/.config/color-tool/config.toml`.
|
||||||
|
4. Create a `.desktop` entry so you can launch the picker from your application menu.
|
||||||
|
|
||||||
|
## 🛠 Usage
|
||||||
|
|
||||||
|
```text
|
||||||
|
Usage: color-tool [OPTIONS] [COLOR ...]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--[no-]pick Open the KDE Plasma color picker
|
||||||
|
--output FMT Format(s): hex, rgb, hsl, rgba, hsla, hexa, all (comma-separated)
|
||||||
|
--[no-]json Output as a JSON table of selected formats
|
||||||
|
--[no-]name Fetch nearest color name from thecolorapi.com
|
||||||
|
--[no-]swatch Include a color swatch in the terminal output
|
||||||
|
--[no-]copy Copy result to clipboard
|
||||||
|
--[no-]notify Show desktop notification
|
||||||
|
--desktop GUI mode: pick → copy → notify
|
||||||
|
--install Install to ~/.local/share/ and symlink to ~/.local/bin/
|
||||||
|
--help, -h Show this help message
|
||||||
|
```
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Pick a color and get HSL + RGB:**
|
||||||
|
```bash
|
||||||
|
color-tool --pick --output hsl,rgb
|
||||||
|
```
|
||||||
|
|
||||||
|
**Convert a hex value with a visual swatch and color name:**
|
||||||
|
```bash
|
||||||
|
color-tool "#ff5500" --swatch --name
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output all formats as JSON for a piped input:**
|
||||||
|
```bash
|
||||||
|
echo "rgba(255, 85, 0, 0.5)" | color-tool --output all --json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Launch in "Silent" Desktop Mode (via terminal or launcher):**
|
||||||
|
```bash
|
||||||
|
color-tool --desktop --no-name
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚙️ Configuration
|
||||||
|
|
||||||
|
You can define your preferred defaults in `~/.config/color-tool/config.toml`. The tool uses a priority hierarchy: **CLI Flags > Desktop Config > Default Config**.
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[defaults]
|
||||||
|
output = "hex" # default output format(s)
|
||||||
|
json = false # output in JSON format
|
||||||
|
swatch = false # show color swatch in terminal
|
||||||
|
name = false # fetch color name
|
||||||
|
copy = false # copy result to clipboard
|
||||||
|
pick = false # auto-launch picker
|
||||||
|
notify = false # show desktop notification
|
||||||
|
|
||||||
|
[desktop]
|
||||||
|
output = "hex"
|
||||||
|
json = false
|
||||||
|
name = false
|
||||||
|
copy = true
|
||||||
|
notify = true
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚖️ License
|
||||||
|
|
||||||
|
Copyright © 2026 Rootiest.
|
||||||
|
|
||||||
|
This program is free software: you can redistribute it and/or modify it under the terms of the **GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.**
|
||||||
|
|
||||||
|
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [GNU General Public License](https://www.gnu.org/licenses/) for more details.
|
||||||
Reference in New Issue
Block a user