Conky Status
INFRASTRUCTURE TOOL
Operate Kodachi support services with confidence.
These guides cover workflows, logs, launchers, dependency checks, and status plumbing used by the rest of Kodachi.
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 | REDACTED-BUILD-TIME |
| Rust Version | 1.82.0 |
| File Size | 4.0MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Infrastructure & Management |
| Description | Unified Rust gateway for Kodachi Conky data |
| JSON Data | View Raw JSON |
SHA256 Checksum
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.
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