Binary reference

conky-status

Unified Rust gateway for Kodachi Conky data

Version10.0.3Size4.4MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	conky-status
Version	10.0.3
Build Date	Not disclosed
Rust Version	1.82.0
File Size	4.4MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Unified Rust gateway for Kodachi Conky data
Git Commit	unknown
Metadata Generated	2026-11-13T16:19:51Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

04ccc8bf0886a6617ebacdd11ad019bc0ba70f56de2737dcc8e74a845a56eaa1

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)
`--json-filter <FIELD1,FIELD2>`	Return only specified JSON fields (comma-separated)
`--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)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output

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: Collect fresh data now, ignoring the cache
--cached: Serve the cached snapshot when it is still within --ttl, instead of collecting
--ttl <seconds>: How old the cache may be and still count as fresh. --ttl 0 means nothing is ever fresh, so it forces a collection even together with --cached
--max-parallel <n>: How many adapters may run at once. Raising it speeds collection up but spawns more subprocesses; values below 1 are clamped to 1
--timeout-ms <ms>: Per-adapter timeout. An adapter that overruns is dropped and its fields fall back to defaults, so a low value trades completeness for speed. Values below 200 are clamped to 200. Without this option, a torrified system gives the network adapters (ip, online_info) a longer Tor-aware budget, because every lookup goes through a Tor circuit; a system that is not torrified keeps the default

Examples:

./conky-status snapshot --json

./conky-status snapshot --json-pretty

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

./conky-status snapshot --ttl 0

./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>] [--max-parallel <n>] [--timeout-ms <ms>] (key accepts a snapshot path, a legacy alias, a bare section 'data'/'meta'/'adapters', or user.<name>)

Options:

<KEY>: Key path or compatibility key to look up
--default <value>: Value to print when the key is missing or the lookup fails. Without it a missing key prints nothing, and a missing user.<name> command exits 4
--refresh: Collect a fresh snapshot before the lookup instead of reading the cache
--ttl <seconds>: How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection
--max-parallel <n>: Adapter concurrency used if this lookup has to collect. Clamped to at least 1
--timeout-ms <ms>: Per-adapter timeout used if this lookup has to collect. Clamped to at least 200

Examples:

./conky-status get data.auth.group

./conky-status get ip-cache.ip --default Offline

./conky-status get ip-public.ip --default Offline

./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 meta --json-pretty

./conky-status get user.hostname_short --default Unknown

`panel`

Get one batched subset of the snapshot (one call per Conky panel instead of one per field)

Usage:

conky-status panel <security|system|network|resources|gauges|all> [--refresh] [--ttl <sec>] [--max-parallel <n>] [--timeout-ms <ms>]

Options:

<PANEL>: Required. security (status pills), system (host/uptime/resources), network (VPN, Tor, DNS, public IP), resources (traffic plus the security booleans), gauges (CPU/load/swap/traffic/ping/uptime, pre-formatted for bars), all (the entire data section)
--refresh: Collect a fresh snapshot before building the panel instead of reading the cache
--ttl <seconds>: How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection
--max-parallel <n>: Adapter concurrency used if the panel has to collect. Defaults to 1 here (panels are called on a Conky interval, so they stay deliberately gentle)
--timeout-ms <ms>: Per-adapter timeout used if the panel has to collect. Clamped to at least 200

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> [NAME] [--default <value>] (--default applies to 'run')

Options:

<ACTION>: Required action: path, init, list, or run
[NAME]: Registered command name. Required when ACTION is run
--default <value>: Fallback printed when a run command fails or is missing. Applies only to ACTION run
path: Print the user command registry path
init: Create the user command registry template if it is missing
list: List the user command names in the registry
run <NAME> [--default <value>]: Run one user-defined command from the registry

Examples:

./conky-status user path

./conky-status user init

./conky-status user list --json-pretty

./conky-status user run hostname_short

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

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 <VERSION>

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. The snapshot is the single collection every other command reads from: get and panel just slice it.

Step 1: Collect a snapshot using the default behavior (fresh collection)

./conky-status snapshot --json

Expected Output: Envelope with meta, adapters and data sections

Step 2: Reuse the cached snapshot when it is at most 30 seconds old

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

Expected Output: A fast cached response, or a fresh collection if the cache is older than the TTL

Step 3: Force a fresh collection by declaring that nothing counts as fresh

./conky-status snapshot --ttl 0 --json

Expected Output: A freshly collected snapshot with meta.stale false

Note

--ttl 0 bypasses the cache even when --cached is also passed: a zero tolerance means the cached copy can never be fresh enough. Use it when a script must not get a stale reading.

Step 4: Force a new collection but give each adapter only 1.2 seconds

./conky-status snapshot --refresh --timeout-ms 1200

Expected Output: A fresh snapshot; slow adapters are dropped and their fields fall back to defaults

Note

A tight timeout trades completeness for speed. Check meta and the adapters section to see which ones were dropped.

Step 5: Collect faster by running more adapters at once

./conky-status snapshot --refresh --max-parallel 6 --json-pretty

Expected Output: Pretty-printed JSON snapshot, collected in less wall time

Note

Each adapter is a subprocess, so keep this moderate. The default is 2 for snapshot and 1 for panel.

Scenario 3: Get Native Keys

Read a snapshot key path directly. A key with no leading section is auto-prefixed with 'data.', and the three section roots ('data', 'meta', 'adapters') can also be fetched whole.

Step 1: Read authenticated user group

./conky-status get data.auth.group

Expected Output: Group value or '?'

Step 2: Fetch a whole section instead of one field: here the snapshot metadata

./conky-status get meta --json-pretty

Expected Output: The meta object, including 'stale' and the collection timestamp

Note

meta.stale is true when the values you are reading came from cache rather than a fresh collection. 'get data' and 'get adapters' fetch the other two sections the same way (adapters shows which collectors succeeded, timed out or were skipped).

Step 3: Read health score with default fallback

./conky-status get data.health.score_display --default 0

Expected Output: Numeric score string

Step 4: Force refresh before interface lookup

./conky-status get data.system.network.interface --refresh

Expected Output: Interface name like ens33/wlan0

Step 5: 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 (the Tor exit when torrified, the direct IP otherwise)

./conky-status get ip-cache.ip --default Offline

Expected Output: Effective IP or Offline

Note

This is the IP the outside world sees. Do not confuse it with ip-public.ip: under Tor the two differ, and showing the wrong one in a panel misrepresents the user's exposure.

Step 2: Direct WAN IP, regardless of Tor exit routing

./conky-status get ip-public.ip --default Offline

Expected Output: Public IP or Offline

Note

Always the real WAN address, even when torrified. Use ip-cache.ip when you want 'what the world sees'.

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 plus the security booleans)

./conky-status panel resources

Expected Output: Panel key=value lines

Step 5: Everything a bar or gauge needs, in one call

./conky-status panel gauges --json

Expected Output: cpu_percent, load1/load5/load15, processes, swap_percent, swap_count, traffic_iface, traffic_up_kib_s, traffic_down_kib_s, traffic_total_percent, ping_ms, uptime

Note

Different payload from 'panel resources': gauges returns pre-formatted numbers for bars, not the security booleans. Use it so a gauge conkyrc does not have to fetch CPU, RAM and traffic separately.

Step 6: Dump the full data section in human JSON mode

./conky-status panel all --json-human

Expected Output: Large JSON envelope with the whole data section

Scenario 6: Conky Integration

Drop-in conkyrc lines that replace the legacy per-field shell scripts. Each command below is the NEW line: paste it into the conkyrc as-is, in place of the old script call named in its notes.

Step 1: Render the effective external IP in a Conky text field

${exec ./conky-status get ip-cache.ip --default Offline}

Expected Output: The same scalar value the old script produced, for example 185.220.101.4 or Offline

Note

Replaces: ${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip}

Step 2: Render the authenticated group

${exec ./conky-status get auth-detail.group --default '?'}

Expected Output: The group name, or ? when not authenticated

Note

Replaces: ${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group}

Step 3: Render the primary nameserver

${exec ./conky-status get dns-cache.ns1 --default N/A}

Expected Output: The nameserver address, or N/A

Note

Replaces: ${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1}

Step 4: Fetch a whole panel on an interval instead of one exec per field

${execpi 20 ./conky-status panel security}

Expected Output: key=value lines that the panel section of the conkyrc renders

Note

One panel call replaces a whole column of ${exec} lines, which is the point: each ${exec} is a separate subprocess on every Conky tick. Run the same command in a shell first to check the output; no Conky restart is needed for that.

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: A single Conky-safe value on stdout

Note

A name that is not in the registry exits 4 and prints an error, so a typo does not look like an empty result. Failed commands retry once and can fall back to the stale cache.

Step 5: Run a registered command but never fail the conkyrc line that calls it

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

Expected Output: The command's value, or N/A if it is missing or fails

Note

With --default the exit code stays 0 even when the command is not in the registry. That is what you want in a live conkyrc, and the opposite of what you want while debugging.

Step 6: Conky-friendly key path for a custom user command

./conky-status get user.hostname_short --default Unknown

Expected Output: The scalar value produced by the registry-backed command

Note

custom.<name> is accepted as an alias for user.<name>.

Step 7: 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
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)
`KODACHI_FORCE_VERIFY`	Force the binary's own signature check to run in debug builds (release builds always verify). Startup fails with a SECURITY error if the signature is missing or invalid	unset	1
`KODACHI_SIG_DIR`	Directory to look for the binary's signature files in, instead of the default location	the signatures directory next to the binary	path to a signature directory
`KODACHI_BUILD_TEST`	Skip signature verification. Intended for build-pipeline self-tests on a not-yet-signed binary, not for normal use	unset	1

Exit Codes

Code	Description
0	Success
1	General error (with --json, the error's code field names its kind)
2	Invalid arguments
4	user run: the named user command is not configured and no --default was given