# LeenFetch Documentation

## Table of Contents
- [LeenFetch Documentation](#leenfetch-documentation)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
  - [Quick Start](#quick-start)
  - [Features](#features)
  - [Architecture](#architecture)
  - [Installation](#installation)
    - [From crates.io (Recommended)](#from-cratesio-recommended)
    - [Arch Linux (AUR)](#arch-linux-aur)
    - [Debian / Ubuntu (.deb)](#debian--ubuntu-deb)
    - [Fedora / RHEL (.rpm)](#fedora--rhel-rpm)
    - [Windows (.zip)](#windows-zip)
    - [Build from Source](#build-from-source)
    - [Shell Completions](#shell-completions)
  - [Configuration](#configuration)
    - [Configuration Overview](#configuration-overview)
    - [flags section](#flags-section)
    - [modules array](#modules-array)
    - [Reloading Configs](#reloading-configs)
  - [Information Blocks](#information-blocks)
    - [ASCII Art Block](#ascii-art-block)
    - [Titles](#titles)
    - [Operating System \& Distribution](#operating-system--distribution)
    - [Hardware Model](#hardware-model)
    - [OS Age](#os-age)
    - [Uptime](#uptime)
    - [Package Managers](#package-managers)
    - [Shell](#shell)
    - [Window Manager](#window-manager)
    - [Desktop Environment](#desktop-environment)
    - [Kernel](#kernel)
    - [CPU](#cpu)
    - [GPU](#gpu)
    - [Memory](#memory)
    - [Disk Usage](#disk-usage)
    - [Resolution](#resolution)
    - [Theme](#theme)
    - [Battery](#battery)
    - [Now Playing](#now-playing)
    - [Terminal Color Swatch](#terminal-color-swatch)
  - [ASCII Art \& Colors](#ascii-art--colors)
  - [Usage](#usage)
    - [Interactive Examples](#interactive-examples)
    - [Command-Line Options](#command-line-options)
    - [Exit Codes](#exit-codes)
  - [Customization](#customization)
    - [Profiles \& Version Control](#profiles--version-control)
    - [Theming Recipes](#theming-recipes)
  - [Scripting \& Automation](#scripting--automation)
  - [Performance \& Diagnostics](#performance--diagnostics)
  - [Troubleshooting](#troubleshooting)
  - [Frequently Asked Questions](#frequently-asked-questions)
  - [Contributing](#contributing)
  - [Support](#support)
  - [License](#license)
  - [Inspiration](#inspiration)
  - [Appendix](#appendix)
    - [Default Modules Example](#default-modules-example)
    - [Color Index Reference](#color-index-reference)
    - [Glossary](#glossary)

---

## Overview

**LeenFetch** is a fast, minimal, and highly customizable system information tool written in Rust. It is designed as a modern alternative to Neofetch, providing beautiful, colorized terminal output and deep configuration for power users. Every element that LeenFetch prints can be reordered and restyled without touching the source code. Users who love to tinker get full control, while sane defaults make the first run delightful.

---

## Quick Start

1. Install LeenFetch via `cargo install leenfetch`.
2. Run `leenfetch` to generate the default configuration file.
3. Open `config.jsonc` in `~/.config/leenfetch/` (Linux) or `C:\Users\<you>\AppData\Roaming\leenfetch\` (Windows).
4. Edit the `flags` or `modules` sections, then re-run `leenfetch` to see your changes instantly.

---

## Features
- Blazing fast startup thanks to Rust and minimal I/O.
- Modular design: enable or disable any information block independently.
- Fully customizable output layout, labels, and color palette.
- Rich ASCII art support with distro detection and custom artwork.
- Remote fetching over SSH with pretty or JSON output.
- Tracks packages, shell, GPU, DE/WM, theme, and more per platform.
- Commented configuration file shipped in human-readable JSONC format.
- Machine-readable JSON output for scripting (`--format json`).
- Works on Linux and Windows with feature-aware fallbacks (macOS in progress).
- Plays nicely in scripts, status bars, and login shells.

---

## Architecture

LeenFetch separates data gathering from rendering:
- **Collectors** probe the system for raw information (CPU, GPU, packages, etc.).
- **Flags** control how the collected data is transformed or formatted.
- **Layout** orders and labels the final output, stitching in ASCII art and colors.

Collectors rely on platform-specific backends where necessary. When a value cannot be fetched on the current platform, LeenFetch falls back to safe defaults or hides the block entirely if configured to do so. This design keeps runtime fast and makes new modules easy to add.

---

## Installation

### Arch Linux (AUR)

Install from the AUR with your preferred helper:

```bash
yay -S leenfetch
# or
paru -S leenfetch
```

Manual AUR build:

```bash
git clone https://aur.archlinux.org/leenfetch.git
cd leenfetch
makepkg -si
```

### Debian / Ubuntu (.deb)

Download the `.deb` from GitHub Releases and install with `dpkg` (replace `1` with the latest tag if needed):

- AMD64 (x86_64)
```bash
wget https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-debian-x86_64.deb
sudo dpkg -i leenfetch-*.deb
```

- AArch64 (ARM64)
```bash
wget https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-debian-aarch64.deb
sudo dpkg -i leenfetch-*.deb
```

### Fedora / RHEL (.rpm)

Grab the `.rpm` from GitHub Releases (update the tag as needed):

- AMD64 (x86_64)
```bash
wget https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-REHL-x86_64.rpm
sudo rpm -i leenfetch-*.rpm
```

- AArch64 (ARM64)
```bash
wget https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-REHL-aarch64.rpm
sudo rpm -i leenfetch-*.rpm
```

### Windows (.zip)

Download the zip for your architecture from GitHub Releases and extract it (update the tag as needed):

- AMD64 (x86_64)
```powershell
Invoke-WebRequest -Uri "https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-windows-x86_64.zip" -OutFile "leenfetch-win.zip"
Expand-Archive .\leenfetch-win.zip -DestinationPath .
.\leenfetch-v1.2.1-windows-x86_64.exe
```

- AArch64 (ARM64)
```powershell
Invoke-WebRequest -Uri "https://github.com/drunkleen/leenfetch/releases/download/v1.2.1/leenfetch-v1.2.1-windows-aarch64.zip" -OutFile "leenfetch-win.zip"
Expand-Archive .\leenfetch-win.zip -DestinationPath .
.\leenfetch-v1.2.1-windows-aarch64.exe
```

> Run the executable from the same directory you extracted to, or move it into a directory on your `PATH`.

### Build from Source

```bash
git clone https://github.com/drunkleen/leenfetch.git
cd leenfetch
cargo build --release
```

Add to PATH:

```bash
cp target/release/leenfetch ~/.local/bin/
```

Then run:

```bash
leenfetch
```

### From crates.io (fallback)

If you prefer installing from crates.io, make sure you have [Rust & Cargo](https://rustup.rs/) installed:

```bash
cargo install leenfetch
```

Then run:

```bash
leenfetch
```

If you have issues with `PATH`, add Cargo's bin directory:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

### Shell Completions

LeenFetch does not ship completions by default. You can still leverage your shell's history or aliasing to streamline usage:
- Add `alias lf='leenfetch'` to your shell rc file.
- Combine with other tools, for example `alias lff='leenfetch --list-options | fzf'`.

---

## Configuration

LeenFetch stores its settings in a single JSON-with-comments file so you get structured data and helpful inline guidance.

- **Linux:** `~/.config/leenfetch/config.jsonc`
- **Windows:** `C:\Users\<username>\AppData\Roaming\leenfetch\config.jsonc`

### Configuration Overview

| Section | Purpose | Typical Changes |
| ------- | ------- | ---------------- |
| `flags` | Formatting, measurement units, ASCII art preferences | Switch palettes, change CPU display detail, adjust disk layout |
| `modules` (`layout`) | Ordering, separators, and custom rows | Reorder modules, add headings, insert breaks |
| `logo` (optional) | ASCII art source and padding overrides | Point to a custom file, add spacing, nudge the logo

The file is authored in JSONC, which is JSON plus `//` comments. Every default entry includes a brief explanation right in the file.

### flags section

The `flags` object tunes how each block of information is displayed. Each key has a descriptive comment explaining valid values. Highlights include:

- **ascii_distro**: `"auto"` detects the current distro or accepts a specific name (e.g., `"arch"`, `"ubuntu"`).
- **ascii_colors**: Use `"distro"` for defaults or provide a comma-separated list such as `"1,2,4,5"`.
- **custom_ascii_path**: Absolute or relative path to custom ASCII art. Leave empty for built-ins.
- **battery_display**: Choose `off`, `bar`, `infobar`, or `barinfo` to control battery appearance.
- **color_blocks**: Characters used for the color bar (e.g., `███` or `###`).
- **cpu_brand / cpu_cores / cpu_frequency / cpu_speed**: Boolean flags to display respective CPU details.
- **cpu_temp**: Choose `"C"` or `"F"` for temperature units.
- **cpu_show_temp**: Toggle temperature visibility without losing other CPU info.
- **de_version**: Show or hide desktop environment version numbers.
- **distro_display**: Granularity of OS info. Options include `name`, `name_version`, `name_arch`, `name_model`, `name_model_version`, `name_model_arch`, `name_model_version_arch`.
- **disk_display**: Render disks as `info`, `percentage`, `infobar`, `barinfo`, or `bar`.
- **disk_subtitle**: Subtitle strategy per disk (`name`, `dir`, `none`, `mount`).
- **memory_percent**: Show memory as a percentage alongside absolute values.
- **memory_unit**: Select `kib`, `mib`, or `gib` to standardize units.
- **package_managers**: Display `off`, `on`, or `tiny` counts depending on how much detail you want.
- **refresh_rate**: Enable detection of display refresh rates (supported on select setups).
- **shell_path** / **shell_version**: Control whether LeenFetch prints the full shell path or version.
- **uptime_shorthand**: Choose `full`, `tiny`, or `seconds` based on your preferred format.
- **os_age_shorthand**: Match `uptime_shorthand` but for the dedicated OS install age module.

Most options are purely visual. If a certain value is unsupported on your system, LeenFetch gracefully falls back to the closest available presentation.
Piped input (for example `fortune | cowsay | leenfetch`) always overrides `ascii_distro` and `custom_ascii_path`.

**Quick reference for `flags`:**

| Key | Allowed values | Default | Notes |
| --- | --- | --- | --- |
| `ascii_distro` | `"auto"` or distro name | `"auto"` | Select bundled ASCII art; piped input overrides it. |
| `ascii_colors` | `"distro"` or comma list of color IDs | `"distro"` | Palette for ASCII art and color swatches. |
| `custom_ascii_path` | `""` or file path | `""` | Use your own ASCII art from disk. |
| `battery_display` | `"off"`, `"bar"`, `"infobar"`, `"barinfo"` | `"off"` | Battery appearance (or hide completely). |
| `color_blocks` | Any string glyph | `"●"` | Characters drawn in the color swatch. |
| `cpu_brand` | `true` / `false` | `true` | Include CPU vendor prefix. |
| `cpu_cores` | `true` / `false` | `true` | Show logical/physical core counts. |
| `cpu_frequency` | `true` / `false` | `true` | Print advertised CPU frequency. |
| `cpu_speed` | `true` / `false` | `true` | Print current CPU speed reading. |
| `cpu_temp` | `"C"` / `"F"` | `"C"` | Temperature unit; any other value disables conversion. |
| `cpu_show_temp` | `true` / `false` | `false` | Toggle temperature column without touching other CPU data. |
| `de_version` | `true` / `false` | `true` | Append the desktop-environment version where possible. |
| `distro_display` | `name`, `name_version`, `name_arch`, `name_model`, `name_model_version`, `name_model_arch`, `name_model_version_arch` | `"name"` | Level of OS detail shown. |
| `disk_display` | `info`, `percentage`, `infobar`, `barinfo`, `bar` | `"info"` | Disk usage layout. |
| `disk_subtitle` | `name`, `dir`, `none`, `mount` | `"dir"` | Per-disk subtitle label. |
| `memory_percent` | `true` / `false` | `true` | Add percentage to the memory row. |
| `memory_unit` | `kib`, `mib`, `gib` | `"mib"` | Preferred unit for memory. |
| `package_managers` | `off`, `on`, `tiny` | `"tiny"` | Package counter verbosity. |
| `refresh_rate` | `true` / `false` | `true` | Append display refresh rate. |
| `shell_path` | `true` / `false` | `false` | Show full shell path versus just the binary name. |
| `shell_version` | `true` / `false` | `true` | Append shell version. |
| `uptime_shorthand` | `full`, `tiny`, `seconds` | `"tiny"` | Session uptime format. |
| `os_age_shorthand` | `full`, `tiny`, `seconds` | `"tiny"` | Installation age format. |

Every key above can be overridden from the CLI for quick experiments—for example `leenfetch --battery-display barinfo` or `leenfetch --shell-version false`. See [Command-Line Options](#command-line-options) for the full list.

```jsonc
{
  "flags": {
    "ascii_distro": "auto",
    "battery_display": "barinfo",
    "shell_version": true
  }
}
```

### logo section (optional)

The `logo` object controls ASCII art. Use it to point to a file (`source`), specify how LeenFetch should select art (`type`), or adjust spacing (`padding`). Leave the section out entirely to keep automatic behavior.

```jsonc
{
  "logo": {
    "type": "file",
    "source": "~/.config/leenfetch/branding/about.txt",
    "padding": { "top": 2, "right": 6, "left": 0 }
  }
}
```

Use `type: "auto"` to keep built-in detection. `padding.top`, `.right`, and `.left` accept integers, letting you add leading blank lines, widen the gap between art and text, or nudge the art horizontally.

### modules array

The `modules` array (also accepted as `layout`) governs ordering, headings, and custom rows. Entries can be literal strings (use `"break"` for a blank spacer line) or objects describing a module.

```jsonc
{
  "modules": [
    "break",
    { "type": "custom", "format": "== System ==" },
    { "type": "titles", "key": "User" },
    { "type": "distro", "key": "Distro" },
    { "type": "cpu", "key": "CPU" },
    { "type": "colors", "key": "" }
  ]
}
```

- **type**: Matches the collectors listed below under [Information Blocks](#information-blocks).
- **key**: Optional label printed before the value. Leave empty (`""`) for no label.
- **format**: When `type` is `custom`, print the supplied string as-is.
- Duplicate entries are allowed if you want to emphasize a field in multiple places.
- Remove entries to hide a block entirely, or insert `"break"` for spacing.

### Reloading Configs

LeenFetch reads configuration at startup. When you update `config.jsonc`:
1. Save your changes.
2. Re-run `leenfetch` to apply them.
3. If the output looks wrong, check the terminal for parse errors. LeenFetch prints helpful messages indicating which line failed to parse.

---

## Information Blocks

Each entry in the `modules` array triggers a collector. The summaries below highlight the module name, which flags influence it, and any notable behavior so you can tailor layouts quickly.

### ASCII Art Block
- **Module entry**: Implicit (renders alongside the `titles` module)
- **Flags**: `ascii_distro`, `ascii_colors`, `custom_ascii_path`
- **Data**: Distro-specific or custom ASCII artwork.
- **Notes**: Pair with `titles` for the classic banner look, or pipe input to override art on the fly.

### Titles
- **Module entry**: `titles`
- **Flags**: Inherits ASCII palette; no dedicated flags.
- **Data**: Current user and hostname.
- **Notes**: Commonly the first info row, aligning the banner with text output.

### Operating System & Distribution
- **Module entry**: `distro`
- **Flags**: `distro_display`
- **Data**: Distro name, version, architecture, and optionally hardware model depending on `distro_display`.
- **Notes**: Windows reports edition and build when available.

### Hardware Model
- **Module entry**: `model`
- **Flags**: None directly; `distro_display` can embed the same info in the distro row.
- **Data**: Motherboard, laptop chassis, or device identifier.
- **Notes**: Useful for multi-device screenshots or inventory output.

### OS Age
- **Module entry**: `os_age`
- **Flags**: `os_age_shorthand`
- **Data**: Time since the current OS install or root filesystem creation.
- **Notes**: Combine with `uptime` to show both install age and current session length.

### Uptime
- **Module entry**: `uptime`
- **Flags**: `uptime_shorthand`
- **Data**: Time since the last boot using the best available system clock.
- **Notes**: `tiny` formatting condenses the value for compact layouts.

### Package Managers
- **Module entry**: `packages`
- **Flags**: `package_managers`
- **Data**: Package counts aggregated from supported managers on your platform. Unsupported managers are skipped silently.
- **Notes**: `tiny` mode displays a short summary such as `pacman(1200)`.

### Shell
- **Module entry**: `shell`
- **Flags**: `shell_path`, `shell_version`
- **Data**: Active shell process. On Windows, respects PowerShell, cmd, and third-party shells.
- **Notes**: Disable both flags for the cleanest single-word shell output.

### Window Manager
- **Module entry**: `wm`
- **Flags**: None in the `flags` section.
- **Data**: Currently running window manager, including Wayland compositors where detected.
- **Notes**: Requires a graphical session; falls back gracefully otherwise.

### Desktop Environment
- **Module entry**: `de`
- **Flags**: `de_version`
- **Data**: Desktop environment name and optional version.
- **Notes**: Set `de_version=false` to avoid noise when the version cannot be detected.

### Kernel
- **Module entry**: `kernel`
- **Flags**: None in the `flags` section.
- **Data**: Kernel or OS build string.
- **Notes**: On Windows, shows the NT kernel version.

### CPU
- **Module entry**: `cpu`
- **Flags**: `cpu_brand`, `cpu_cores`, `cpu_frequency`, `cpu_speed`, `cpu_temp`, `cpu_show_temp`
- **Data**: CPU vendor, model, clock speeds, core counts, and optional temperature.
- **Notes**: Temperature collection depends on platform sensors; disable `cpu_show_temp` if sensors are unreliable.

### GPU
- **Module entry**: `gpu`
- **Flags**: None in the `flags` section.
- **Data**: Active graphics adapter(s).
- **Notes**: Multi-GPU systems are collapsed or listed individually depending on platform.

### Memory
- **Module entry**: `memory`
- **Flags**: `memory_percent`, `memory_unit`
- **Data**: RAM usage, optionally with percentage.
- **Notes**: `memory_unit` enforces consistent units across outputs.

### Disk Usage
- **Module entry**: `disk`
- **Flags**: `disk_display`, `disk_subtitle`
- **Data**: Mounted filesystem usage.
- **Notes**: `infobar` and `barinfo` draw textual bars for a quick overview.

### Resolution
- **Module entry**: `resolution`
- **Flags**: `refresh_rate`
- **Data**: Connected monitor resolutions, optionally including refresh rate when supported.
- **Notes**: Ideal for showcasing multi-monitor setups.

### Theme
- **Module entry**: `theme`
- **Flags**: None in the `flags` section.
- **Data**: GTK/Qt theme names when available.
- **Notes**: Falls back silently if the theme cannot be detected.

### Battery
- **Module entry**: `battery`
- **Flags**: `battery_display`
- **Data**: Battery charge, status, and optionally bars.
- **Notes**: Desktop users can remove the module entirely to avoid empty placeholders.

### Now Playing
- **Module entry**: `song`
- **Flags**: None in the `flags` section.
- **Data**: Integrates with common media players via MPRIS or platform APIs.
- **Notes**: Appears only when playback is active and a song title is available.

### Terminal Color Swatch
- **Module entry**: `colors`
- **Flags**: `color_blocks`, `ascii_colors`
- **Data**: Color palette preview showing up to 16 colors.
- **Notes**: Customize `color_blocks` to change the glyph used in the swatch.

---

## ASCII Art & Colors

ASCII art is central to LeenFetch's personality. You can:
- Set `ascii_distro` to `auto` for automatic distro detection.
- Pick any built-in art by name (e.g., `"arch"`, `"ubuntu"`, `"fedora"`, `"windows"`).
- Supply a custom art file via `custom_ascii_path`.
- Override palette with `ascii_colors`. Use terminal color indexes (`0`-`7` for standard, `8`-`15` for bright).

Tips:
- Keep custom art within 30-40 characters wide for the best fit.
- Mix and match ASCII art with a minimalist data layout for wallpapers or screenshots.
- Pair ASCII palettes with the `color_blocks` glyph to maintain a unified look.

---

## Usage

Run LeenFetch directly from the terminal. It reads configs, gathers data, and prints the decorated output in one pass.

### Remote over SSH

LeenFetch can gather data from remote hosts and render it locally. It runs `leenfetch --format json` on the remote side over SSH, parses the result, and prints a pretty block per host.

```bash
# Pretty output for one host (leverages your SSH config/agent)
leenfetch --ssh user@server.example.com
leenfetch --ssh user@server.example.com:port

# Multiple hosts
leenfetch --ssh user@server1 --ssh user@server2:port ...

# Script-friendly JSON
leenfetch --ssh user@server --format json
leenfetch --ssh user@server:port --format json
```

Notes:
- The remote host must have `leenfetch` installed and in `PATH`.
- SSH options are inherited from your usual SSH configuration; the flag accepts one or more hosts.
- ASCII logo and colors reflect the remote distro for each host while using your local layout.
- A short SSH connect timeout is used; authentication is handled by your existing SSH config/agent.
- Combine with `--format json` to get one JSON object per host for scripting.

### Interactive Examples

```bash
# Show default output
leenfetch

# Dump all available configuration keys (with inline docs)
leenfetch --list-options

# Pipe into a file for sharing
leenfetch > leenfetch.txt
```

Combine with other tools:

- `watch -n 5 leenfetch` monitors uptime or battery over time.
- `tmux display-message "$(leenfetch | head -n 12)"` shows a compact summary inside tmux.
- `leenfetch` can be run inside login scripts to greet you with fresh system info.

### Command-Line Options

- **Core utilities**
  - `leenfetch -h | --help` — Show usage information.
  - `leenfetch -V | --version` — Print version and exit.
  - `leenfetch -i | --init` — Generate default configs in `~/.config/leenfetch/`.
  - `leenfetch -r | --reinit` — Recreate configs from bundled defaults.
  - `leenfetch --config <path>` — Load configuration from a custom JSONC file.
  - `leenfetch --no-config` — Ignore files and boot with compiled-in defaults.
  - `leenfetch --list-options` — Print every config key with a short description.

- **ASCII & formatting overrides**

  | Option | Example | Effect |
  | ------ | ------- | ------ |
  | `--ascii_distro <name>` | `--ascii_distro arch_small` | Force a specific ASCII logo. |
  | `--ascii_colors <list>` | `--ascii_colors 1,5,2,4` | Override palette with comma-separated color indices. |
  | `--custom_ascii_path <file>` | `--custom_ascii_path ~/.config/art.txt` | Load ASCII art from disk. |
  | `--color-blocks <glyph>` | `--color-blocks ███` | Change the glyph used for the color swatch. |
  | `--battery-display <mode>` | `--battery-display barinfo` | Swap between `off`, `bar`, `infobar`, and `barinfo`. |
  | `--disk-display <mode>` | `--disk-display percentage` | Choose disk representation (`info`, `percentage`, `infobar`, `barinfo`, `bar`). |
  | `--disk-subtitle <mode>` | `--disk-subtitle mount` | Pick disk labels (`name`, `dir`, `none`, `mount`). |
  | `--memory-unit <unit>` | `--memory-unit gib` | Standardize memory units (`kib`, `mib`, `gib`). |
  | `--packages <mode>` | `--packages tiny` | Control package summaries (`off`, `on`, `tiny`). |
  | `--uptime <mode>` | `--uptime seconds` | Set uptime shorthand (`full`, `tiny`, `seconds`). |
  | `--os-age <mode>` | `--os-age full` | Set OS age shorthand (same accepted values as uptime). |
  | `--distro-display <mode>` | `--distro-display name_model_arch` | Adjust distro detail level. |
  | `--cpu-temp-unit <unit>` | `--cpu-temp-unit off` | Choose `C`, `F`, or disable CPU temperature output. |
  | `--format <pretty|json>` | `--format json` | Choose machine-readable JSON or the default pretty output. |

- **Remote fetch**
  - `--ssh <host>...` — Fetch info from one or more hosts over SSH. Each host is queried via `leenfetch --format json` remotely; output is rendered locally using the chosen `--format`.

- **Boolean toggles**

  Every toggle uses a single flag with an explicit value. Examples:
  - `--memory-percent true`
  - `--cpu-show-temp false`
  - `--cpu-speed true`
  - `--cpu-frequency false`
  - `--cpu-cores true`
  - `--cpu-brand false`
  - `--shell-path true`
  - `--shell-version false`
  - `--refresh-rate true`
  - `--de-version false`

- **Layout helpers**
  - `--only cpu,memory,shell` — Render only the listed modules (order comes from the config).
  - `--hide gpu,colors` — Remove specific modules from the current layout.

Use these overrides for quick tests; persistent changes still live in `config.jsonc`.

### Exit Codes

- `0` — Execution succeeded, output was printed.
- `1` — General failure (configuration parsing, IO error, unsupported platform call).

---

## Customization

LeenFetch thrives on personalization. Since configs are regular text files, you can use your favorite editor, track changes in version control, and share profiles with friends.

### Profiles & Version Control

- Store multiple config sets under version control, e.g., `~/.config/leenfetch/profiles/`.
- Symlink or copy the desired `config.jsonc` before running LeenFetch.
- For remote machines, keep configs in a dotfiles repository and bootstrap them with shell scripts.

### Theming Recipes

Ideas to get you started:
- **Minimal**: Disable ASCII art by piping input or using an empty custom ASCII, and keep only titles and distro within the `modules` array.
- **Screenshots**: Enable ASCII art, color swatches, CPU, GPU, resolution, and theme. Stick to `memory_percent=false` for clean numbers.
- **Monitoring**: Enable uptime, disks with `barinfo`, memory percent, and battery infobar.
- **Music Showcase**: Add the `song` module with a custom `key` like `Now Playing`, and keep color blocks bright.

---

## Scripting & Automation

LeenFetch plays nicely with automation:
- Use it in login shells to verify machine identity.
- Embed the output in status bars by capturing `leenfetch` output and slicing the lines you need.
- Combine with cron or systemd timers to snapshot system info periodically.
- Pair with screenshot tools to publish desktop showcase posts with consistent styling.

When scripting, trim the `modules` array to only the collectors you need to reduce noise and speed up execution even further.

---

## Performance & Diagnostics

LeenFetch is optimized for speed, but you can fine-tune it:
- Disable heavy collectors (package counts, now playing) if you prefer bare minimum output.
- Keep ASCII art short to reduce terminal scrollback.
- Monitor configuration parse errors: LeenFetch prints descriptive messages for invalid JSONC syntax, including line numbers.
- When debugging, temporarily set `package_managers="off"` or remove the `colors` module to isolate problematic sections.

---

## Troubleshooting

- **Tool fails to start**: Check terminal output for parse errors. The message includes file paths and line numbers.
- **Missing blocks**: Make sure the module appears in `modules` and any related flag (like `package_managers`) isn't disabling the data.
- **Wrong ASCII art**: Verify `ascii_distro` is spelled correctly or set it to `"auto"`.
- **Incorrect colors**: Terminal themes can override ANSI colors; test in a default theme to confirm.
- **Package count is zero**: The manager might not be supported on your platform yet. Contributions are welcome.
- **Media info missing**: Make sure your player exposes MPRIS (Linux) or the relevant Windows API. Not every application provides hooks.
- **Battery not detected**: Desktop systems without batteries should disable the block. For laptops, ensure the OS power subsystem is accessible.
- **Windows path issues**: Run the terminal as the same user that installed LeenFetch so the config directory resolves correctly.

Deleting any config file forces LeenFetch to regenerate it on the next run, restoring defaults without manual editing.

---

## Frequently Asked Questions

- **Does LeenFetch support macOS?** Not yet. macOS support is on the roadmap; community feedback speeds it up.
- **Can I show multiple disks?** Yes. `disk_display` applies to every detected mount. Customize subtitles via `disk_subtitle`.
- **How do I highlight GPU vendors?** Adjust the `key` in the `modules` array or use the ASCII art colors to accent hardware lines.
- **Is there a way to localize labels?** Absolutely. Set the `key` field in the `modules` array to any text you like (ASCII recommended).
- **Why is temperature missing?** Sensors may require elevated permissions or additional packages. Toggle `cpu_show_temp` off if temperatures are unavailable.

---

## Contributing

1. Fork the repo.
2. Create a feature branch: `git checkout -b feature/my-feature`.
3. Make your changes. Keep modules documented and configurations commented.
4. Run tests or `cargo fmt`/`cargo clippy` if applicable.
5. Commit with a descriptive message: `git commit -m 'feat: add my feature'`.
6. Push to your fork and open a Pull Request.

We welcome clean PRs, detailed documentation, and new collectors. Please open an issue before adding large features to coordinate design.

---

## Support

If you find LeenFetch valuable, consider supporting development:
- [PayPal](https://www.paypal.com/paypalme/RDarvishifar)
- **BTC:** `bc1qsmvxpn79g6wkel3w67k37r9nvzm5jnggeltxl6`
- **ETH/BNB/MATIC:** `0x8613aD01910d17Bc922D95cf16Dc233B92cd32d6`
- **USDT/TRON:** `TGNru3vuDfPh5zBJ31DKzcVVvFgfMK9J48`
- **DOGE:** `D8U25FjxdxdQ7pEH37cMSw8HXBdY1qZ7n3`

---

## License

[MIT](./LICENSE) License © [DrunkLeen](https://github.com/drunkleen)

---

## Inspiration

- [Neofetch](https://github.com/dylanaraps/neofetch)
- [Fastfetch](https://github.com/fastfetch-cli/fastfetch)
- [Rust](https://www.rust-lang.org/) — the foundation of LeenFetch

---

## Appendix

### Default Modules Example

Below is a trimmed example of the default `modules` section. Your generated file includes inline comments for every entry.

```jsonc
{
  "modules": [
    "break",
    { "type": "custom", "format": "== System ==" },
    { "type": "titles", "key": "User" },
    { "type": "distro", "key": "Distro" },
    { "type": "kernel", "key": "Kernel" },
    { "type": "uptime", "key": "Uptime" },
    { "type": "packages", "key": "Packages" },
    { "type": "shell", "key": "Shell" },
    { "type": "cpu", "key": "CPU" },
    { "type": "gpu", "key": "GPU" },
    { "type": "memory", "key": "Memory" },
    { "type": "disk", "key": "Disk" },
    { "type": "battery", "key": "Battery" },
    { "type": "colors", "key": "" }
  ]
}
```

### Color Index Reference

ANSI color indexes used in `ascii_colors`:
- `0` Black
- `1` Red
- `2` Green
- `3` Yellow
- `4` Blue
- `5` Magenta
- `6` Cyan
- `7` White
- `8` Bright Black (Gray)
- `9` Bright Red
- `10` Bright Green
- `11` Bright Yellow
- `12` Bright Blue
- `13` Bright Magenta
- `14` Bright Cyan
- `15` Bright White

### Glossary

- **Collector**: Module that queries the system for data (CPU info, disk stats, etc.).
- **JSONC**: JSON with `//` comments, the format used for LeenFetch configuration.
- **Block**: A single line or section in the LeenFetch output (CPU, Memory, etc.).
- **Palette**: The set of colors used to render ASCII art and color swatches.
- **Module entry**: A string or object in the `modules` array that controls which collector runs and how it is labeled.
