{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:37Z", "binary_name": "conky-status" }, "binary": { "name": "conky-status", "path": "/opt/kodachi/dashboard/hooks/conky-status", "timestamp": "2026-07-21T01:54:37Z", "file_info": { "size": 4215904, "sha256": "ebb46dbb3c23f6df6e1fa9018edf506dcad98c1ed23cd4788e3fec5a26bcd224" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Kodachi OS", "description": "Unified Rust gateway for Kodachi Conky data", "features": [ "Bounded parallel adapter collection", "Unified snapshot cache with lock + atomic writes", "Privacy-first redaction for sensitive identifiers", "Compatibility aliases for legacy Conky scripts", "User-defined Conky command registry via JSON config", "Kodachi-standard CLI flags via cli-core" ], "license": "Proprietary", "name": "conky-status", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.139946466Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "conky-status", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.284999501Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Data", "commands": [ { "description": "Collect and output unified conky-status snapshot", "examples": [ "./conky-status snapshot --json", "./conky-status snapshot --json-pretty", "./conky-status snapshot --cached --ttl 30", "./conky-status snapshot --ttl 0", "./conky-status snapshot --refresh --max-parallel 2 --timeout-ms 1500" ], "name": "snapshot", "options": [ { "default": "on, unless --cached is passed", "description": "Collect fresh data now, ignoring the cache", "flag": "--refresh", "required": false }, { "default": "false", "description": "Serve the cached snapshot when it is still within --ttl, instead of collecting", "flag": "--cached", "required": false }, { "default": "30", "description": "How old the cache may be and still count as fresh. --ttl 0 means nothing is ever fresh, so it forces a collection even together with --cached", "flag": "--ttl ", "required": false }, { "default": "2", "description": "How many adapters may run at once. Raising it speeds collection up but spawns more subprocesses; values below 1 are clamped to 1", "flag": "--max-parallel ", "required": false }, { "default": "12000", "description": "Per-adapter timeout. An adapter that overruns is dropped and its fields fall back to defaults, so a low value trades completeness for speed. Values below 200 are clamped to 200", "flag": "--timeout-ms ", "required": false } ], "requires_sudo": false, "usage": "conky-status snapshot [--refresh] [--cached] [--ttl ] [--max-parallel ] [--timeout-ms ]" }, { "description": "Get a single key value (snapshot key or user. registry command)", "examples": [ "./conky-status get data.auth.group", "./conky-status get ip-cache.ip --default Offline", "./conky-status get ip-public.ip --default Offline", "./conky-status get data.health.score_display --default 0", "./conky-status get security-status.vpn --json", "./conky-status get data.system.network.interface --refresh", "./conky-status get meta --json-pretty", "./conky-status get user.hostname_short --default Unknown" ], "name": "get", "options": [ { "description": "Key path or compatibility key to look up", "flag": "", "required": true }, { "description": "Value to print when the key is missing or the lookup fails. Without it a missing key prints nothing, and a missing user. command exits 4", "flag": "--default ", "required": false }, { "default": "false", "description": "Collect a fresh snapshot before the lookup instead of reading the cache", "flag": "--refresh", "required": false }, { "default": "30", "description": "How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection", "flag": "--ttl ", "required": false }, { "default": "2", "description": "Adapter concurrency used if this lookup has to collect. Clamped to at least 1", "flag": "--max-parallel ", "required": false }, { "default": "12000", "description": "Per-adapter timeout used if this lookup has to collect. Clamped to at least 200", "flag": "--timeout-ms ", "required": false } ], "requires_sudo": false, "usage": "conky-status get [--default ] [--refresh] [--ttl ] [--max-parallel ] [--timeout-ms ] (key accepts a snapshot path, a legacy alias, a bare section 'data'/'meta'/'adapters', or user.)" }, { "description": "Get one batched subset of the snapshot (one call per Conky panel instead of one per field)", "examples": [ "./conky-status panel security", "./conky-status panel system --json-pretty", "./conky-status panel network --refresh", "./conky-status panel resources", "./conky-status panel gauges --json", "./conky-status panel all --json-human" ], "name": "panel", "options": [ { "description": "Required. security (status pills), system (host/uptime/resources), network (VPN, Tor, DNS, public IP), resources (traffic plus the security booleans), gauges (CPU/load/swap/traffic/ping/uptime, pre-formatted for bars), all (the entire data section)", "flag": "", "required": true }, { "default": "false", "description": "Collect a fresh snapshot before building the panel instead of reading the cache", "flag": "--refresh", "required": false }, { "default": "30", "description": "How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection", "flag": "--ttl ", "required": false }, { "default": "1", "description": "Adapter concurrency used if the panel has to collect. Defaults to 1 here (panels are called on a Conky interval, so they stay deliberately gentle)", "flag": "--max-parallel ", "required": false }, { "default": "12000", "description": "Per-adapter timeout used if the panel has to collect. Clamped to at least 200", "flag": "--timeout-ms ", "required": false } ], "requires_sudo": false, "usage": "conky-status panel [--refresh] [--ttl ] [--max-parallel ] [--timeout-ms ]" }, { "description": "Manage and execute user-defined Conky commands from JSON registry", "examples": [ "./conky-status user path", "./conky-status user init", "./conky-status user list --json-pretty", "./conky-status user run hostname_short", "./conky-status user run uptime_pretty --default N/A" ], "name": "user", "options": [ { "description": "Required action: path, init, list, or run", "flag": "", "required": true }, { "description": "Registered command name. Required when ACTION is run", "flag": "[NAME]", "required": false }, { "description": "Fallback printed when a run command fails or is missing. Applies only to ACTION run", "flag": "--default ", "required": false } ], "requires_sudo": false, "usage": "conky-status user [NAME] [--default ] (--default applies to 'run')" } ] } ], "description": "Unified Rust gateway for Kodachi Conky data", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "Force the binary's own signature check to run in debug builds (release builds always verify). Startup fails with a SECURITY error if the signature is missing or invalid", "name": "KODACHI_FORCE_VERIFY", "values": "1" }, { "default": "the signatures directory next to the binary", "description": "Directory to look for the binary's signature files in, instead of the default location", "name": "KODACHI_SIG_DIR", "values": "path to a signature directory" }, { "default": "unset", "description": "Skip signature verification. Intended for build-pipeline self-tests on a not-yet-signed binary, not for normal use", "name": "KODACHI_BUILD_TEST", "values": "1" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter " }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" } ], "name": "conky-status", "usage": "conky-status [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.440653596Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Kodachi-standard global flags and output modes", "examples": [ { "command": "./conky-status -h", "description": "Show full CLI help", "expectedOutput": "Command/option reference" }, { "command": "./conky-status -v", "description": "Show binary version", "expectedOutput": "conky-status version " }, { "command": "./conky-status -n --json-pretty", "description": "Show program metadata using JSON pretty mode", "expectedOutput": "Envelope with info payload" }, { "command": "./conky-status -e", "description": "Show comprehensive usage examples", "expectedOutput": "Category-based examples list" }, { "command": "./conky-status snapshot --json-human", "description": "Use human-readable JSON rendering (jq-like)", "expectedOutput": "Enhanced JSON envelope", "notes": "Falls back to pretty JSON if jq is unavailable" } ], "id": "1_core_flags", "title": "Core Flags" }, { "description": "Refresh, cache, concurrency and timeout controls. The snapshot is the single collection every other command reads from: get and panel just slice it.", "examples": [ { "command": "./conky-status snapshot --json", "description": "Collect a snapshot using the default behavior (fresh collection)", "expectedOutput": "Envelope with meta, adapters and data sections" }, { "command": "./conky-status snapshot --cached --ttl 30", "description": "Reuse the cached snapshot when it is at most 30 seconds old", "expectedOutput": "A fast cached response, or a fresh collection if the cache is older than the TTL" }, { "command": "./conky-status snapshot --ttl 0 --json", "description": "Force a fresh collection by declaring that nothing counts as fresh", "expectedOutput": "A freshly collected snapshot with meta.stale false", "notes": "--ttl 0 bypasses the cache even when --cached is also passed: a zero tolerance means the cached copy can never be fresh enough. Use it when a script must not get a stale reading." }, { "command": "./conky-status snapshot --refresh --timeout-ms 1200", "description": "Force a new collection but give each adapter only 1.2 seconds", "expectedOutput": "A fresh snapshot; slow adapters are dropped and their fields fall back to defaults", "notes": "A tight timeout trades completeness for speed. Check meta and the adapters section to see which ones were dropped." }, { "command": "./conky-status snapshot --refresh --max-parallel 6 --json-pretty", "description": "Collect faster by running more adapters at once", "expectedOutput": "Pretty-printed JSON snapshot, collected in less wall time", "notes": "Each adapter is a subprocess, so keep this moderate. The default is 2 for snapshot and 1 for panel." } ], "id": "2_snapshot_modes", "title": "Snapshot Modes" }, { "description": "Read a snapshot key path directly. A key with no leading section is auto-prefixed with 'data.', and the three section roots ('data', 'meta', 'adapters') can also be fetched whole.", "examples": [ { "command": "./conky-status get data.auth.group", "description": "Read authenticated user group", "expectedOutput": "Group value or '?'" }, { "command": "./conky-status get meta --json-pretty", "description": "Fetch a whole section instead of one field: here the snapshot metadata", "expectedOutput": "The meta object, including 'stale' and the collection timestamp", "notes": "meta.stale is true when the values you are reading came from cache rather than a fresh collection. 'get data' and 'get adapters' fetch the other two sections the same way (adapters shows which collectors succeeded, timed out or were skipped)." }, { "command": "./conky-status get data.health.score_display --default 0", "description": "Read health score with default fallback", "expectedOutput": "Numeric score string" }, { "command": "./conky-status get data.system.network.interface --refresh", "description": "Force refresh before interface lookup", "expectedOutput": "Interface name like ens33/wlan0" }, { "command": "./conky-status get data.tor.torrified_onoff --json", "description": "Structured JSON response for a single key", "expectedOutput": "Envelope with key, resolved_key, value, stale" } ], "id": "3_get_native_keys", "title": "Get Native Keys" }, { "description": "Legacy script-compatible key aliases for Conky migration", "examples": [ { "command": "./conky-status get ip-cache.ip --default Offline", "description": "Effective external IP (the Tor exit when torrified, the direct IP otherwise)", "expectedOutput": "Effective IP or Offline", "notes": "This is the IP the outside world sees. Do not confuse it with ip-public.ip: under Tor the two differ, and showing the wrong one in a panel misrepresents the user's exposure." }, { "command": "./conky-status get ip-public.ip --default Offline", "description": "Direct WAN IP, regardless of Tor exit routing", "expectedOutput": "Public IP or Offline", "notes": "Always the real WAN address, even when torrified. Use ip-cache.ip when you want 'what the world sees'." }, { "command": "./conky-status get auth-detail.sessionid", "description": "Equivalent of auth-detail.sh sessionid", "expectedOutput": "Masked session token or N/A" }, { "command": "./conky-status get dns-cache.mode --default Unknown", "description": "Equivalent of dns-cache.sh mode", "expectedOutput": "DNS mode string" }, { "command": "./conky-status get system-status.swapperc --default 0", "description": "Gauge-ready swap usage percent from gateway", "expectedOutput": "Integer 0-100" }, { "command": "./conky-status get net-traffic.totalpercent --default 0", "description": "Gauge-ready total bandwidth percent (0-100)", "expectedOutput": "Integer 0-100", "notes": "Computed from total uploaded+downloaded bytes against 10 GiB scale" }, { "command": "./conky-status get security-status.vpn --json-pretty", "description": "Equivalent of security-status.sh vpn", "expectedOutput": "JSON envelope with boolean value" }, { "command": "./conky-status get cloud-status.cards", "description": "Equivalent of cloud-status.sh cards", "expectedOutput": "Cloud cards count or '?'" } ], "id": "4_get_compat_keys", "title": "Get Compatibility Keys" }, { "description": "Batched panel subsets for exec/execpi integration", "examples": [ { "command": "./conky-status panel security", "description": "Key=value output for security panel", "expectedOutput": "Multiple lines: internet/login/group/..." }, { "command": "./conky-status panel system --json-pretty", "description": "System panel subset in JSON", "expectedOutput": "Envelope with panel data map" }, { "command": "./conky-status panel network --refresh", "description": "Refresh before network panel render", "expectedOutput": "Updated panel key=value lines" }, { "command": "./conky-status panel resources", "description": "Resource panel subset (traffic plus the security booleans)", "expectedOutput": "Panel key=value lines" }, { "command": "./conky-status panel gauges --json", "description": "Everything a bar or gauge needs, in one call", "expectedOutput": "cpu_percent, load1/load5/load15, processes, swap_percent, swap_count, traffic_iface, traffic_up_kib_s, traffic_down_kib_s, traffic_total_percent, ping_ms, uptime", "notes": "Different payload from 'panel resources': gauges returns pre-formatted numbers for bars, not the security booleans. Use it so a gauge conkyrc does not have to fetch CPU, RAM and traffic separately." }, { "command": "./conky-status panel all --json-human", "description": "Dump the full data section in human JSON mode", "expectedOutput": "Large JSON envelope with the whole data section" } ], "id": "5_panel_modes", "title": "Panel Modes" }, { "description": "Drop-in conkyrc lines that replace the legacy per-field shell scripts. Each command below is the NEW line: paste it into the conkyrc as-is, in place of the old script call named in its notes.", "examples": [ { "command": "${exec ./conky-status get ip-cache.ip --default Offline}", "description": "Render the effective external IP in a Conky text field", "expectedOutput": "The same scalar value the old script produced, for example 185.220.101.4 or Offline", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip}" }, { "command": "${exec ./conky-status get auth-detail.group --default '?'}", "description": "Render the authenticated group", "expectedOutput": "The group name, or ? when not authenticated", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group}" }, { "command": "${exec ./conky-status get dns-cache.ns1 --default N/A}", "description": "Render the primary nameserver", "expectedOutput": "The nameserver address, or N/A", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1}" }, { "command": "${execpi 20 ./conky-status panel security}", "description": "Fetch a whole panel on an interval instead of one exec per field", "expectedOutput": "key=value lines that the panel section of the conkyrc renders", "notes": "One panel call replaces a whole column of ${exec} lines, which is the point: each ${exec} is a separate subprocess on every Conky tick. Run the same command in a shell first to check the output; no Conky restart is needed for that." } ], "id": "6_conky_integration", "title": "Conky Integration" }, { "description": "Configure custom commands in JSON so Conky can call unsupported fields through the gateway", "examples": [ { "command": "./conky-status user path", "description": "Show registry file path", "expectedOutput": "~/.config/kodachi/conky/config/user-commands.json" }, { "command": "./conky-status user init", "description": "Create template registry if missing", "expectedOutput": "created: or existing: " }, { "command": "./conky-status user list --json-pretty", "description": "List registered custom command names", "expectedOutput": "JSON list with command count" }, { "command": "./conky-status user run hostname_short", "description": "Execute one configured command directly", "expectedOutput": "A single Conky-safe value on stdout", "notes": "A name that is not in the registry exits 4 and prints an error, so a typo does not look like an empty result. Failed commands retry once and can fall back to the stale cache." }, { "command": "./conky-status user run uptime_pretty --default N/A", "description": "Run a registered command but never fail the conkyrc line that calls it", "expectedOutput": "The command's value, or N/A if it is missing or fails", "notes": "With --default the exit code stays 0 even when the command is not in the registry. That is what you want in a live conkyrc, and the opposite of what you want while debugging." }, { "command": "./conky-status get user.hostname_short --default Unknown", "description": "Conky-friendly key path for a custom user command", "expectedOutput": "The scalar value produced by the registry-backed command", "notes": "custom. is accepted as an alias for user.." }, { "command": "${exec ./conky-status get user.hostname_short --default Unknown}", "description": "Direct Conky call without exposing command logic in bash", "expectedOutput": "Rendered value in panel" } ], "id": "7_user_command_registry", "title": "User Command Registry" }, { "description": "Binary self-signature verification diagnostics and enforcement", "examples": [ { "command": "KODACHI_FORCE_VERIFY=1 ./conky-status -v", "description": "Force signature check in debug builds", "expectedOutput": "Version output if signature verifies", "notes": "Fails with SECURITY error when signature is missing/invalid" }, { "command": "KODACHI_SIG_DIR=./results/signatures ./conky-status snapshot --json", "description": "Use custom signature directory", "expectedOutput": "Snapshot output with successful startup" }, { "command": "KODACHI_BUILD_TEST=1 ./conky-status -v", "description": "Skip signature check in controlled build-test mode", "expectedOutput": "Version output", "notes": "Intended for build pipeline self-tests only" }, { "command": "./conky-status -v", "description": "Release behavior with mandatory signature verification", "expectedOutput": "Version output or SECURITY failure message" } ], "id": "8_signature_verification", "title": "Signature Verification" } ], "description": "Usage examples for conky-status", "name": "conky-status", "quickReference": [ "./conky-status -h", "./conky-status -e", "./conky-status panel security", "./conky-status panel gauges --json", "./conky-status get ip-cache.ip --default Offline", "./conky-status snapshot --cached --ttl 30 --json", "./conky-status user list" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.766787242Z", "version": "9.8.4 (build 320)", "warnings": [] } } }