Conky Status Guide
One Rust gateway that feeds every Kodachi Conky panel from a single cached snapshot. This guide is scenario-first: real run order, legacy script migration, stale-data recovery, and low-power polling.
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
At a Glance
conky-status v9.8.4 (build 319), 4.0MB, by Warith Al Maawali, Proprietary license. Unified Rust gateway for Kodachi Conky data.
This guide stays scenario-first. For the full file metadata table, SHA256 checksum, global options, and the autogenerated command catalog, see the conky-status CLI reference.
Key Features
Unified Desktop Telemetry Gateway
| Feature | Description |
|---|---|
| Single Snapshot Source | Collects Conky data once and serves all panels from a shared snapshot |
| Bounded Parallel Adapters | Polls multiple providers concurrently with controlled limits |
| Atomic Cache Writes | Prevents partial/corrupted cache state when multiple reads occur |
| Conky-Safe Outputs | Supports simple scalar responses for ${exec} and batched output for ${execpi} |
| Legacy Compatibility Aliases | Preserves existing wrapper script keys while migrating to one Rust binary |
| JSON Modes for Automation | Standard, pretty, and human-readable output modes for scripts and audits |
Why Conky Status is Essential
| Benefit | Description |
|---|---|
| Lower Desktop Load | Replaces many shell script polls with one gateway process path |
| Stable UI Rendering | Cache + TTL controls reduce flicker and transient N/A values |
| Safer Data Exposure | Privacy-first redaction protects sensitive identifiers before rendering |
| Faster Troubleshooting | One binary gives direct visibility into panel keys and adapter state |
TL;DR - Essential Commands
# Collect full telemetry snapshot
conky-status snapshot --json-pretty
# Read one Conky-compatible value
conky-status get ip-cache.ip --default Offline
# Render grouped panel values
conky-status panel security --refresh
# Inspect binary metadata and options
conky-status -n --json-pretty
Understanding Unified Conky Telemetry
Snapshot Collection and Cache Lifecycle
conky-status gathers data from adapters and stores a reusable snapshot so multiple panels do not trigger duplicate system calls.
# Fresh collection
conky-status snapshot --refresh --json
# Prefer cache when fresh (faster desktop polling)
conky-status snapshot --cached --ttl 30
# Tune collection parallelism and per-adapter timeout
conky-status snapshot --refresh --max-parallel 6 --timeout-ms 1500
Single-Key Lookups for Wrapper Scripts
Use get when a panel needs one scalar value.
# Native key path
conky-status get data.health.score_display --default 0
# Compatibility key path
conky-status get dns-cache.mode --default Unknown
# Force refresh before key lookup
conky-status get data.system.network.interface --refresh
Panel Mode for Batched Widget Rendering
Use panel to fetch grouped values in one call.
# Security panel key=value output
conky-status panel security
# Network panel with refresh
conky-status panel network --refresh
# Full panel payload in JSON
conky-status panel all --json-human
Compatibility Aliases for Legacy Scripts
| Legacy Script Call | Gateway Replacement |
|---|---|
${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip} |
${exec conky-status get ip-cache.ip --default Offline} |
${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group} |
${exec conky-status get auth-detail.group --default '?'} |
${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1} |
${exec conky-status get dns-cache.ns1 --default N/A} |
${execpi 20 ~/.config/kodachi/conky/scripts/security-status.sh} |
${execpi 20 conky-status panel security} |
Signature and Runtime Controls
# Force signature verification in debug/test environments
KODACHI_FORCE_VERIFY=1 conky-status -v
# Use custom signature directory
KODACHI_SIG_DIR=./results/signatures conky-status snapshot --json
# Controlled build-test bypass
KODACHI_BUILD_TEST=1 conky-status -v
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
RUST_LOG |
Set logging level | info | error|warn|info|debug|trace |
NO_COLOR |
Disable all colored output when set | unset | 1|true|yes (any value disables color) |
KODACHI_FORCE_VERIFY |
Force startup signature verification path | unset | 1 |
KODACHI_SIG_DIR |
Override signature directory location | built-in path | filesystem path |
KODACHI_BUILD_TEST |
Allow controlled build-pipeline bypass mode | unset | 1 |
Exit Codes
conky-status returns the standard Kodachi exit codes: 0 success, 1 general error, 2 invalid arguments, 3 permission denied, 4 network error, 5 file not found. See the CLI reference for the full table.
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Snapshot Tuning | TTL, refresh mode, timeout, and max parallel controls |
| Key Resolution | Native + compatibility key path lookups |
| Panel Modes | Security/system/network/resources/gauges/all outputs |
| JSON Formatting | JSON, JSON pretty, and human JSON output |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Keep Signature Checks Enabled | Do not disable signature verification outside controlled build tests |
| Use Fallback Defaults | Prevent leaking internal failures to UI by always setting --default values |
| Limit Refresh Frequency | Excessively low polling intervals can increase system fingerprinting surface |
| Prefer Panel Batching | Reduce process storms by grouping reads through panel mode |
| Audit Key Exposure | Review keys used in Conky configs to avoid displaying sensitive identifiers |
Performance
| Metric | Value |
|---|---|
| Cache Hit Path | Near-instant local snapshot read |
| Refresh Cost | Bound by --timeout-ms and active adapter count |
| Concurrency Control | Tuned via --max-parallel to prevent process storms |
| Desktop Polling Stability | Improved with --cached --ttl <sec> |
| Write Safety | Atomic cache updates with lock coordination |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Baseline Telemetry Validation After Login
Validate that Conky gateway data is healthy after boot/login.
# Step 1: Confirm binary version and startup
conky-status -v
# Expected: conky-status version 9.8.4 (build 319)
# Step 2: Capture runtime metadata for diagnostics
conky-status -n --json-pretty > /tmp/conky-status-info.json
# Expected: Metadata JSON with feature/security fields
# Step 3: Build fresh snapshot baseline
conky-status snapshot --refresh --json-pretty > /tmp/conky-snapshot.json
# Expected: Snapshot payload with data/adapters/meta fields
# Step 4: Verify panel rendering path
conky-status panel security
# Expected: key=value lines for security panel fields
# Step 5: Verify scalar key fallback behavior
conky-status get data.health.score_display --default 0
# Expected: Numeric display value (or 0 fallback)
Cross-binary workflow: conky-status + health-control + ip-fetch
When to run: After login, after binary updates, or when Conky shows placeholders unexpectedly.
Scenario 2: Legacy Script Migration to Gateway Keys
Replace legacy wrapper scripts with conky-status keys while preserving output compatibility.
# Step 1: Validate compatibility IP key
conky-status get ip-cache.ip --default Offline
# Expected: Same value as legacy ip-cache.sh ip
# Step 2: Validate compatibility auth key
conky-status get auth-detail.group --default '?'
# Expected: Same group label as legacy auth-detail.sh group
# Step 3: Validate DNS compatibility key
conky-status get dns-cache.ns1 --default N/A
# Expected: Same primary DNS nameserver output
# Step 4: Validate grouped panel output for execpi usage
conky-status panel security --refresh
# Expected: Batched key=value block usable by Conky panel parser
# Step 5: Export full mapping state for migration review
conky-status snapshot --json-pretty > /tmp/conky-migration-snapshot.json
# Expected: JSON snapshot for field-by-field comparison
Cross-binary workflow: conky-status + Conky wrapper scripts + workflow-manager
When to run: During migration from shell script polling to unified gateway-based panel reads.
Scenario 3: Stale Data Debugging and Forced Refresh Recovery
Diagnose stale telemetry and restore current values without restarting Conky.
# Step 1: Inspect cached snapshot behavior
conky-status snapshot --cached --ttl 30 --json
# Expected: Fast response, may indicate stale=true on older cache data
# Step 2: Force new collection with strict timeout budget
conky-status snapshot --refresh --timeout-ms 1200 --json-pretty
# Expected: Fresh snapshot, potentially with degraded adapter notes
# Step 3: Re-check critical security key with explicit refresh
conky-status get security-status.vpn --refresh --json-pretty
# Expected: Updated VPN state from fresh collection
# Step 4: Re-render panel output after refresh
conky-status panel security --refresh
# Expected: Updated security key=value lines
# Step 5: Validate related security telemetry source
health-control security-status
# Expected: Current security posture summary
Cross-binary workflow: conky-status + health-control + dns-switch
When to run: When panel values appear frozen, outdated, or inconsistent with live system state.
Scenario 4: Low-Power Desktop Polling Optimization
Tune Conky polling strategy for stable rendering on low-resource systems.
# Step 1: Benchmark default snapshot path
time conky-status snapshot --cached --ttl 30 >/dev/null
# Expected: Fast execution for cache-hit path
# Step 2: Reduce adapter fan-out for constrained devices
conky-status snapshot --refresh --max-parallel 3 --timeout-ms 1000 --json
# Expected: Stable collection with tighter resource budget
# Step 3: Use panel batching instead of multiple key polls
conky-status panel resources
# Expected: One grouped call returns multiple fields
# Step 4: Keep scalar reads only for isolated fields
conky-status get data.system.network.interface --default N/A
# Expected: Single field output for targeted widget
# Step 5: Persist optimized snapshot capture for review
conky-status snapshot --cached --ttl 45 --json-pretty > /tmp/conky-optimized.json
# Expected: Cached snapshot tuned for lower polling overhead
Cross-binary workflow: conky-status + workflow-manager
When to run: On laptops/VMs/Raspberry Pi builds where aggressive polling causes UI lag or fan spikes.
Scenario 5: Signature Verification and Release Integrity Checks
Validate startup signature controls and safe runtime behavior.
# Step 1: Verify default release startup behavior
conky-status -v
# Expected: Version output (or SECURITY error if signature invalid)
# Step 2: Force signature verification explicitly
KODACHI_FORCE_VERIFY=1 conky-status -v
# Expected: Successful version output only when signature validates
# Step 3: Test custom signature directory resolution
KODACHI_SIG_DIR=./results/signatures conky-status snapshot --json
# Expected: Snapshot output when signatures are found and valid
# Step 4: Controlled build-test bypass (CI only)
KODACHI_BUILD_TEST=1 conky-status -v
# Expected: Version output for controlled pipeline tests
# Step 5: Archive integrity snapshot for change tracking
conky-status snapshot --json-pretty > /tmp/conky-integrity-baseline.json
# Expected: Baseline JSON captured for diff/audit workflows
Cross-binary workflow: conky-status + integrity-check + logs-hook
When to run: Before release packaging, after binary updates, or while diagnosing signature startup failures.
Related Workflows
- Conky Desktop Section, Panel layout, gauges, and desktop integration
- IP Fetch, IP geolocation fields used by Conky security panel
- Health Control, Security score and runtime posture signals
- DNS Switch, DNS mode and encryption status fields
- Online Auth, Auth group/session fields consumed by telemetry
- Logs Hook, Centralized logging for telemetry and diagnostics
- Full CLI Reference: conky-status commands