Binary reference

conky-status

Unified Rust gateway for Kodachi Conky data

Version9.8.4 (build 320)Size4.0MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	conky-status
Version	9.8.4 (build 320)
Build Date	Not disclosed
Rust Version	1.82.0
File Size	4.0MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Unified Rust gateway for Kodachi Conky data
Git Commit	unknown
Metadata Generated	2026-07-11T18:16:30Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

58d876dd2242557454790506c97e0e563a0e69c3a7212247b2f83e2722386269

Features

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

Security Features

Feature	Description
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core

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
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)
`--retry <COUNT>`	Retry attempts (optional; no default applied)

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.<name> 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: <path> or existing: <path>

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.<name> 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\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

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