Skip to content

Conky Status

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.

File Information

Property Value
Binary Name conky-status
Version 9.0.1
Build Date 2026-03-12T16:16:06.160530314Z
Rust Version 1.82.0
File Size 1.7MB
Author Warith Al Maawali
License Proprietary
Category Infrastructure & Management
Description Unified Rust gateway for Kodachi Conky data
JSON Data View Raw JSON

SHA256 Checksum

158f385877278b026f7ba44cbc6c5c901f8d3633df7f56e573977aed367a8a42

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

Code Description
0 Success
1 General error
2 Invalid arguments
3 Permission denied
4 Network error
5 File not found

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.0.1

# 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.