conky-status

Unified Rust gateway for Kodachi Conky data

Version: 9.8.4 (build 319) | Size: 4.0MB | Author: Warith Al Maawali

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

File Information

Property	Value
Binary Name	conky-status
Version	9.8.4 (build 319)
Build Date	REDACTED-BUILD-TIME
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-06-28T11:16:40Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

5b3b4668ddc2e845f39ae76c417b7e342c1a74386b2b81c8167e3c01b9dc61f0

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