swadhin / fetchx public

docs(readme): add example configurations

Swadhin Biswas committed 7 months ago

11397e5

1 parent 7ef0718

commit 11397e5

1 file changed

+150 -0

Files

README.md +150

Showing 1 changed file+150-0

README.md

▼README.md

+150-0

@@ -648,3 +648,153 @@ fetchx --stdout \| grep "OS:"
648	648	# Server/SSH — no image, useful info only
649	649
650	650	colors = "distro"
	651	+image_backend = "ascii"
	652	+ascii_distro = "auto"
	653	+
	654	+show_title = true
	655	+show_underline = true
	656	+show_os = true
	657	+show_host = true
	658	+show_kernel = true
	659	+show_uptime = true
	660	+show_packages = true
	661	+show_shell = true
	662	+show_cpu = true
	663	+show_memory = true
	664	+show_disk = true
	665	+show_local_ip = true
	666	+show_users = true
	667	+show_colors = true
	668	+
	669	+# Hide desktop-only fields
	670	+show_resolution = false
	671	+show_de = false
	672	+show_wm = false
	673	+show_wm_theme = false
	674	+show_theme = false
	675	+show_icons = false
	676	+show_terminal = false
	677	+show_term_font = false
	678	+show_gpu = false
	679	+
	680	+memory_bar = true
	681	+disk_bar = true
	682	+```
	683	+
	684	+</details>
	685	+
	686	+---
	687	+
	688	+## Usage
	689	+
	690	+```bash
	691	+fetchx # Default output with config
	692	+fetchx --json # JSON output (for scripting)
	693	+fetchx --logo-only # Logo only, no system info
	694	+fetchx --emoji # Emoji art mode
	695	+fetchx --nerd-font # Nerd Font icons on labels
	696	+fetchx --backend kitty # Use kitty image protocol
	697	+fetchx --backend chafa # Use chafa text-art backend
	698	+fetchx --custom-image ~/photo.png # Display a specific image
	699	+fetchx --ascii-distro arch # Force Arch logo
	700	+fetchx --ascii-distro cachyos # Force CachyOS logo
	701	+fetchx --no-color # Plain text (for piping)
	702	+fetchx --stdout # Disable all formatting
	703	+fetchx --gap 5 # Wider gap between logo and info
	704	+fetchx --separator " -> " # Custom separator
	705	+fetchx --select-image # Interactive image picker (fzf)
	706	+fetchx --init-api-image # Quick setup: enable API image fetching
	707	+fetchx --create-config # Create default config file
	708	+fetchx --print-config # Print default config to stdout
	709	+fetchx --show-config # Show config file path
	710	+fetchx --help # Full help
	711	+fetchx --version # Version info
	712	+```
	713	+
	714	+### All CLI Options
	715	+
	716	+```
	717	+Options:
	718	+ --no-color Disable colors in output
	719	+ --bold <BOLD> Enable/disable bold text
	720	+ -b, --backend <BACKEND> Image backend: ascii, kitty, sixel, chafa, w3m, iterm2, off
	721	+ -s, --source <SOURCE> Image source: auto, ascii, wallpaper, /path/to/image
	722	+ --ascii-distro <DISTRO> Which distro's ASCII art to display
	723	+ --emoji Use emoji mode
	724	+ --nerd-font Use Nerd Font icons for labels
	725	+ -c, --custom-image <PATH> Path to custom image
	726	+ -l, --logo-only Only show the logo, no info
	727	+ --gap <NUM> Gap between logo and info text
	728	+ --separator <SEP> Separator between label and value
	729	+ --stdout Disable formatting (for piping)
	730	+ --show-config Show the config file path
	731	+ --print-config Print the default config to stdout
	732	+ --create-config Create default config file
	733	+ --json Print output as JSON
	734	+ --select-image Interactive image selector (fzf)
	735	+ --init-api-image Quick setup: enable kitty + API images
	736	+ --daemon Run as background daemon
	737	+ --tray-status Compact status for tray widgets
	738	+ --block-range-start <N> Color block range start (0-15)
	739	+ --block-range-end <N> Color block range end (0-15)
	740	+ --block-width <N> Width of color blocks
	741	+ -h, --help Print help
	742	+ -V, --version Print version
	743	+```
	744	+
	745	+---
	746	+
	747	+## Image Backends
	748	+
	749	+\| Backend \| Protocol \| Terminal Support \| Requires \|
	750	+\| -------- \| ----------------------- \| ---------------------------- \| ---------------------- \|
	751	+\| `ascii` \| Text-based ASCII art \| All terminals \| Nothing \|
	752	+\| `kitty` \| Kitty graphics protocol \| Kitty \| Kitty terminal \|
	753	+\| `sixel` \| Sixel graphics \| xterm, mlterm, foot, WezTerm \| `img2sixel` or `chafa` \|
	754	+\| `chafa` \| Unicode block art \| All terminals \| `chafa` package \|
	755	+\| `w3m` \| w3m image display \| X11 terminals (urxvt, xterm) \| `w3m` package \|
	756	+\| `iterm2` \| OSC 1337 inline images \| iTerm2 \| iTerm2 (macOS) \|
	757	+\| `off` \| None \| All \| Nothing \|
	758	+
	759	+### How Smart Image Fetching Works
	760	+
	761	+When `image_source = "auto"` and you're using a graphics-capable backend (kitty, sixel, etc.):
	762	+
	763	+```
	764	+Run 1: No cached image → shows ASCII art
	765	+ └─ Background process downloads random image from API
	766	+
	767	+Run 2: Shows image from Run 1 (instant, zero delay)
	768	+ └─ Background process downloads NEW random image
	769	+
	770	+Run 3: Shows image from Run 2 (different image!)
	771	+ └─ Background process downloads another new image
	772	+
	773	+...and so on — new image every single run!
	774	+```
	775	+
	776	+Key design:
	777	+
	778	+- Zero delay — fetchx never waits for downloads; it shows what's cached and exits instantly
	779	+- Background child process — downloads survive after fetchx exits (not a thread)
	780	+- Atomic writes — image is written to a temp file first, then renamed, so you never see a half-downloaded image
	781	+- Any format — API may return WebP, JPEG, or PNG; fetchx auto-converts to PNG for compatibility
	782	+
	783	+One-command setup for kitty:
	784	+
	785	+```bash
	786	+fetchx --init-api-image
	787	+```
	788	+
	789	+This sets `image_backend = "kitty"` and `image_source = "auto"` in your config.
	790	+
	791	+---
	792	+
	793	+## Advanced Features
	794	+
	795	+### Interactive Image Selector
	796	+
	797	+Browse and pick images interactively:
	798	+
	799	+```bash
	800	+fetchx --select-image
651	801