Skip to content

conky-status

Unified Rust gateway for Kodachi Conky data

Version: 9.0.1 | Size: 1.7MB | Author: Warith Al Maawali

License: Proprietary | Website: https://www.digi77.com

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
JSON Data View Raw JSON

SHA256 Checksum

158f385877278b026f7ba44cbc6c5c901f8d3633df7f56e573977aed367a8a42

Features

Feature Description
Feature Bounded parallel adapter collection
Feature Unified snapshot cache with lock + atomic writes
Feature Privacy-first redaction for sensitive identifiers
Feature Compatibility aliases for legacy Conky scripts
Feature User-defined Conky command registry via JSON config
Feature Kodachi-standard CLI flags via cli-core

Security Features

Feature Description
Authentication Secure authentication with certificate pinning
Encryption TLS 1.3 for all network communications
Inputvalidation All inputs are validated and sanitized
Ratelimiting Built-in rate limiting for network operations

System Requirements

Requirement Value
OS Linux (Debian-based)
Privileges root/sudo for system operations
Dependencies OpenSSL, libcurl

Global Options

Flag Description
-h, --help Print help information
-v, --version Print version information
-n, --info Display detailed information
-e, --examples Show usage examples
--json Output in JSON format
--json-pretty Pretty-print JSON output with indentation
--json-human Enhanced JSON output with improved formatting (like jq)
--verbose Enable verbose output
--quiet Suppress non-essential output
--no-color Disable colored output
--config <FILE> Use custom configuration file
--timeout <SECS> Set timeout (default: 30)
--retry <COUNT> Retry attempts (default: 3)

Commands

Data

snapshot

Collect and output unified conky-status snapshot

Usage: 

conky-status snapshot [--refresh] [--cached] [--ttl <sec>] [--max-parallel <n>] [--timeout-ms <ms>]

Options: - --refresh: Force refresh now - --cached: Prefer cache if fresh - --ttl <seconds>: Cache freshness threshold

Examples: 

./conky-status snapshot --json

./conky-status snapshot --json-pretty

./conky-status snapshot --json-human

./conky-status snapshot --cached --ttl 30

./conky-status snapshot --refresh --max-parallel 2 --timeout-ms 1500

get

Get a single key value (snapshot key or user. registry command)

Usage: 

conky-status get <key> [--default <value>] [--refresh] [--ttl <sec>] # key supports user.<name>

Options: - --default <value>: Fallback value when key is missing - --refresh: Force refresh before lookup

Examples: 

./conky-status get data.auth.group

./conky-status get ip-cache.ip

./conky-status get auth-detail.sessionid

./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 dns-cache.mode --default Unknown

./conky-status get user.hostname_short

./conky-status get user.uptime_pretty --default N/A

panel

Get a batched subset for a panel

Usage: 

conky-status panel <security|system|network|resources|gauges|all> [--refresh]

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

user

Manage and execute user-defined Conky commands from JSON registry

Usage: 

conky-status user <path|init|list|run> [args]

Examples: 

./conky-status user path

./conky-status user init

./conky-status user list

./conky-status user run hostname_short

./conky-status user run uptime_pretty --json-pretty

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Core Flags

Kodachi-standard global flags and output modes

Step 1: Show full CLI help

./conky-status -h
Expected Output: Command/option reference

Step 2: Show binary version

./conky-status -v
Expected Output: conky-status version 9.0.1

Step 3: Show program metadata using JSON pretty mode

./conky-status -n --json-pretty
Expected Output: Envelope with info payload

Step 4: Show comprehensive usage examples

./conky-status -e
Expected Output: Category-based examples list

Step 5: Use human-readable JSON rendering (jq-like)

./conky-status snapshot --json-human
Expected Output: Enhanced JSON envelope

Note

Falls back to pretty JSON if jq is unavailable

Scenario 2: Snapshot Modes

Refresh, cache, concurrency, and timeout controls

Step 1: Collect snapshot using default refresh behavior

./conky-status snapshot --json
Expected Output: Envelope with meta/adapters/data

Step 2: Prefer cached snapshot if age <= 30 seconds

./conky-status snapshot --cached --ttl 30
Expected Output: Fast cached response when fresh

Step 3: Force new collection with tighter adapter timeout

./conky-status snapshot --refresh --timeout-ms 1200
Expected Output: Fresh snapshot with possible degraded adapters

Step 4: Override adapter concurrency budget

./conky-status snapshot --refresh --max-parallel 6 --json-pretty
Expected Output: Pretty JSON snapshot

Note

Use moderate values to avoid subprocess storms

Scenario 3: Get Native Keys

Read direct snapshot key paths

Step 1: Read authenticated user group

./conky-status get data.auth.group
Expected Output: Group value or '?'

Step 2: Read health score with default fallback

./conky-status get data.health.score_display --default 0
Expected Output: Numeric score string

Step 3: Force refresh before interface lookup

./conky-status get data.system.network.interface --refresh
Expected Output: Interface name like ens33/wlan0

Step 4: Structured JSON response for a single key

./conky-status get data.tor.torrified_onoff --json
Expected Output: Envelope with key, resolved_key, value, stale

Scenario 4: Get Compatibility Keys

Legacy script-compatible key aliases for Conky migration

Step 1: Effective external IP (Tor exit when torrified, direct IP otherwise)

./conky-status get ip-cache.ip --default Offline
Expected Output: Effective IP or Offline

Step 2: Direct/public WAN IP regardless of Tor exit routing

./conky-status get ip-public.ip --default Offline
Expected Output: Public IP or Offline

Step 3: Equivalent of auth-detail.sh sessionid

./conky-status get auth-detail.sessionid
Expected Output: Masked session token or N/A

Step 4: Equivalent of dns-cache.sh mode

./conky-status get dns-cache.mode --default Unknown
Expected Output: DNS mode string

Step 5: Gauge-ready swap usage percent from gateway

./conky-status get system-status.swapperc --default 0
Expected Output: Integer 0-100

Step 6: Gauge-ready total bandwidth percent (0-100)

./conky-status get net-traffic.totalpercent --default 0
Expected Output: Integer 0-100

Note

Computed from total uploaded+downloaded bytes against 10 GiB scale

Step 7: Equivalent of security-status.sh vpn

./conky-status get security-status.vpn --json-pretty
Expected Output: JSON envelope with boolean value

Step 8: Equivalent of cloud-status.sh cards

./conky-status get cloud-status.cards
Expected Output: Cloud cards count or '?'

Scenario 5: Panel Modes

Batched panel subsets for exec/execpi integration

Step 1: Key=value output for security panel

./conky-status panel security
Expected Output: Multiple lines: internet/login/group/...

Step 2: System panel subset in JSON

./conky-status panel system --json-pretty
Expected Output: Envelope with panel data map

Step 3: Refresh before network panel render

./conky-status panel network --refresh
Expected Output: Updated panel key=value lines

Step 4: Resource panel subset (traffic + booleans)

./conky-status panel resources
Expected Output: Panel key=value lines

Step 5: Dump full data section in human JSON mode

./conky-status panel all --json-human
Expected Output: Large JSON envelope

Scenario 6: Conky Integration

Drop-in commands for wrapper scripts and panel configs

Step 1: Replace legacy IP script call

${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip} -> ${exec ./conky-status get ip-cache.ip --default Offline}
Expected Output: Same scalar value in Conky text field

Step 2: Replace auth detail script call

${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group} -> ${exec ./conky-status get auth-detail.group --default '?'}
Expected Output: Same group text output

Step 3: Replace DNS cache script call

${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1} -> ${exec ./conky-status get dns-cache.ns1 --default N/A}
Expected Output: Primary nameserver text

Step 4: Use panel mode for grouped values

${execpi 20 ./conky-status panel security}
Expected Output: key=value lines for panel rendering

Note

No Conky restart required to validate command output

Scenario 7: User Command Registry

Configure custom commands in JSON so Conky can call unsupported fields through the gateway

Step 1: Show registry file path

./conky-status user path
Expected Output: ~/.config/kodachi/conky/config/user-commands.json

Step 2: Create template registry if missing

./conky-status user init
Expected Output: created: or existing:

Step 3: List registered custom command names

./conky-status user list --json-pretty
Expected Output: JSON list with command count

Step 4: Execute one configured command directly

./conky-status user run hostname_short
Expected Output: Single Conky-safe value

Note

Failed commands retry once and can fall back to stale cache/default

Step 5: Conky-friendly key path for custom user command

./conky-status get user.hostname_short --default Unknown
Expected Output: Scalar value from registry-backed command

Note

Also accepts custom. as alias

Step 6: Direct Conky call without exposing command logic in bash

${exec ./conky-status get user.hostname_short --default Unknown}
Expected Output: Rendered value in panel

Scenario 8: Signature Verification

Binary self-signature verification diagnostics and enforcement

Step 1: Force signature check in debug builds

KODACHI_FORCE_VERIFY=1 ./conky-status -v
Expected Output: Version output if signature verifies

Note

Fails with SECURITY error when signature is missing/invalid

Step 2: Use custom signature directory

KODACHI_SIG_DIR=./results/signatures ./conky-status snapshot --json
Expected Output: Snapshot output with successful startup

Step 3: Skip signature check in controlled build-test mode

KODACHI_BUILD_TEST=1 ./conky-status -v
Expected Output: Version output

Note

Intended for build pipeline self-tests only

Step 4: Release behavior with mandatory signature verification

./conky-status -v
Expected Output: Version output or SECURITY failure message

Environment Variables

Variable Description Default Values
RUST_LOG Set logging level info error
NO_COLOR Disable all colored output when set unset 1

Exit Codes

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