Binary reference

global-launcher

Global launcher for Kodachi dashboard binaries with execution folder containment

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

File Information

Property	Value
Binary Name	global-launcher
Version	9.8.4 (build 320)
Build Date	Not disclosed
Rust Version	rustc 1.97.0 (2d8144b78 2026-07-07)
File Size	2.0MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Global launcher for Kodachi dashboard binaries with execution folder containment
Git Commit	5d16df5d
Metadata Generated	2026-08-10T13:22:55Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

340320788d2d527f2ee68aa9efad8b67e8732e7ac359e9ad631de75660b1644f

Features

#	Feature
1	Dynamic binary discovery and deployment
2	Execution folder containment for security
3	Symlink-based global access
4	Comprehensive error handling and logging
5	Support for both Rust and Gambas binaries
6	Deployment verification and rollback
7	JSON and text output formats
8	Zero hardcoded paths - fully dynamic

Security Features

Feature	Description
Authentication	Uses OS filesystem permissions; symlink ownership verified by comparing symlink target to current executable path
Encryption	No encryption; configuration is statically embedded in the binary to prevent tampering via external config files
Input Validation	All binary names and paths are validated against security rules
Rate Limiting	Configurable timeouts prevent resource exhaustion

System Requirements

Requirement	Value
OS	Linux (Debian-based, specifically Kodachi OS)
Privileges	root/sudo for global deployment
Dependencies	cli-core library, logs-hook service, symlink support in filesystem

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 human-readable formatting (like jq)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--timeout <SECONDS>`	No effect on the launcher itself. Management mode (deploy/verify/cleanup) ignores it, and in symlink execution mode every argument is forwarded verbatim to the target binary, so --timeout is consumed by that binary. To bound the launcher's own execution timeout use the GLOBAL_LAUNCHER_TIMEOUT environment variable (default: 900 seconds)
`--user-override <USERNAME>`	No effect today. The value is parsed and then discarded; it does not change path or user resolution, including under sudo. Do not rely on it
`-o, --output-format <FORMAT>`	Force output format: text (default) or json. '-o json' is equivalent to --json

Commands

Management Commands

`deploy`

Deploy global symlinks for all dashboard binaries

Usage:

global-launcher deploy [OPTIONS]

Options:

--force: Force deployment even if binaries exist
--no-verify: Skip the post-deployment check that every new symlink resolves and is executable. Faster, but a broken symlink will not be reported until you run 'verify' yourself
--save-hashes: Write results/deployment-hashes.json (SHA256 of each source binary plus the launcher)

Examples:

sudo ./global-launcher deploy

sudo ./global-launcher deploy --force

sudo ./global-launcher deploy --no-verify

sudo ./global-launcher deploy --save-hashes --json

`verify`

Verify deployed symlinks are working

Usage:

global-launcher verify [OPTIONS]

Options:

--detailed: Show detailed verification info
--save-hashes: Write results/verification-hashes.json (SHA256 of each source binary plus the launcher)

Examples:

./global-launcher verify

./global-launcher verify --detailed

./global-launcher verify --save-hashes --json

`cleanup`

Remove all deployed symlinks

Usage:

global-launcher cleanup [OPTIONS]

Options:

--yes: No effect. Cleanup is always non-interactive and never prompts, so this flag is accepted only so existing scripts keep working. It is not a safety gate

Examples:

sudo ./global-launcher cleanup

sudo ./global-launcher cleanup --json

Operational Scenarios

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

Scenario 1: Deployment Operations

Create the /usr/local/bin symlinks so every hook binary is callable from anywhere. Run these from the hooks directory.

Step 1: Deploy global access for all discovered dashboard binaries

sudo ./global-launcher deploy

Expected Output: ✅ SUCCESS: Deployed <COUNT> binaries to /usr/local/bin

Note

Needs root: it writes symlinks into /usr/local/bin. Set GLOBAL_BIN_DIR to deploy somewhere else.

Step 2: Redeploy over names that already exist in the target directory

sudo ./global-launcher deploy --force

Expected Output: ✅ SUCCESS: Deployed <COUNT> binaries to /usr/local/bin

Note

Without --force, a name already taken by a real file (not a launcher symlink) is left alone and the deploy is reported as failed.

Step 3: Deploy without the post-deployment symlink check

sudo ./global-launcher deploy --no-verify

Expected Output: ✅ SUCCESS: Deployed <COUNT> binaries to /usr/local/bin

Note

Skips the check that each new symlink resolves and is executable. A broken link will then go unnoticed until you run './global-launcher verify' yourself.

Step 4: Deploy, write the hash report, and print the machine-readable result

sudo ./global-launcher deploy --save-hashes --json

Expected Output: JSON envelope with total_symlinks_created and failed_deployments, plus results/deployment-hashes.json on disk

Note

The report lands in the hooks directory under results/, not in the current working directory.

Scenario 2: Verification Operations

Check that the deployed symlinks still resolve to the current binaries.

Step 1: Check every deployed symlink

./global-launcher verify

Expected Output: ✅ SUCCESS: <COUNT> verified, 0 broken

Note

No root needed: this only reads. Exits 7 if any symlink is broken.

Step 2: List each symlink with its target path and source hash

./global-launcher verify --detailed

Expected Output: One '+ name -> /path/to/hooks/name (hash: ...)' line per verified symlink

Step 3: Verify, write results/verification-hashes.json, and print the JSON result

./global-launcher verify --save-hashes --json

Expected Output: JSON envelope with verified_symlinks[] (each carrying source_binary_hash and launcher_hash) and broken_symlinks[]

Scenario 3: Hash Reports and Integrity

The --save-hashes reports are written for transparency and audit. They are never read back to make a trust decision: all hash checking happens in memory. Compare two reports over time to spot a binary that changed underneath you.

Step 1: Read the report left by the last 'verify --save-hashes'

cat results/verification-hashes.json

Expected Output: JSON with a SHA256 for every source binary plus the launcher hash

Note

Path is relative to the hooks directory (or to KODACHI_BASE_DIR when set), which is where the launcher writes it.

Step 2: Read the report left by the last 'deploy --save-hashes'

cat results/deployment-hashes.json

Expected Output: Same shape as the verification report, captured at deploy time

Note

Each report overwrites the previous one; keep a copy yourself if you want history.

Step 3: Pull one binary's hashes straight out of the verification run

./global-launcher verify --save-hashes --json | jq '.data.verified_symlinks[0] | {name, source_binary_hash, launcher_hash}'

Expected Output: {"name": "ip-fetch", "source_binary_hash": "...", "launcher_hash": "..."}

Scenario 4: Execution Mode: Using the Global Binaries

After deploy, calling a binary by name from any directory goes through the launcher, which runs the real binary inside the hooks directory and forwards your arguments untouched. You do not type 'global-launcher' for this.

Step 1: Run a hook binary from any working directory

health-control internet-status

Expected Output: health-control's internet status output, exactly as if you had run it from the hooks directory

Note

Every argument is passed through as-is, so the target binary's own flags keep working.

Step 2: Run ip-fetch globally with JSON output

ip-fetch --json

Expected Output: ip-fetch's JSON envelope with the current IP information

Step 3: List DNS servers from anywhere

dns-switch list

Expected Output: dns-switch's server list with the current configuration

Step 4: Bound how long the launcher will wait for a slow binary

GLOBAL_LAUNCHER_TIMEOUT=60 health-control security-score

Expected Output: The target binary's normal output, or a timeout error after 60 seconds

Note

GLOBAL_LAUNCHER_TIMEOUT (default 900 seconds) is the only way to change this. --timeout is forwarded to the target binary instead, deliberately, so it does not collide with the target's own --timeout.

Scenario 5: Cleanup Operations

Remove the global symlinks. Only symlinks the launcher owns are touched; unrelated files in the target directory are left alone.

Step 1: Remove every deployed symlink

sudo ./global-launcher cleanup

Expected Output: ✅ SUCCESS: Removed <COUNT> symlinks

Note

Needs root, and runs immediately without asking. After this the binaries are only callable from the hooks directory again; the binaries themselves are not deleted.

Step 2: Remove the symlinks and print a machine-readable result

sudo ./global-launcher cleanup --json

Expected Output: JSON envelope with removed_count and a timestamp

Note

--yes is accepted but does nothing: cleanup never prompts, with or without it.

Scenario 6: Core Flags and Output Formats

Flags accepted by every management command.

Step 1: Show the full help: commands, flags, environment variables and exit codes

./global-launcher -h

Expected Output: The help screen. Add --json for the same content as structured data

Step 2: Print the version

./global-launcher -v

Expected Output: global-launcher version <VERSION>

Step 3: Print the program information block as JSON (features, security model, requirements)

./global-launcher -n --json

Expected Output: JSON envelope with the ProgramInfo fields

Step 4: Force JSON output and indent it for reading

./global-launcher verify -o json --json-pretty

Expected Output: Indented JSON verification result

Note

'-o json' is the same as --json. --json-human formats it further, jq-style.

Step 5: Suppress non-essential output and strip ANSI color, for logs and pipes

./global-launcher verify --quiet --no-color

Expected Output: Plain, uncolored output. NO_COLOR=1 in the environment does the same

Scenario 7: Troubleshooting a Broken Deployment

Both deploy and verify exit with code 7 when they fail, so a script can tell a real deployment from a silently degraded one. The standard recovery is to remove the launcher's symlinks and lay them down again.

Step 1: Repair the deployment whenever verification reports a broken symlink

./global-launcher verify || (sudo ./global-launcher cleanup && sudo ./global-launcher deploy)

Expected Output: Either '✅ SUCCESS: <COUNT> verified, 0 broken', or a cleanup followed by a fresh deploy

Note

verify exits 7 on broken symlinks and deploy exits 7 on a failed deploy, which is what makes this loop work in a script.

Step 2: Deploy into a user-writable directory instead of /usr/local/bin

GLOBAL_BIN_DIR="$HOME/.local/bin" ./global-launcher deploy

Expected Output: ✅ SUCCESS: Deployed <COUNT> binaries to /home/<user>/.local/bin

Note

No root needed for a directory you own. GLOBAL_BIN_DIR must also be set for the later verify and cleanup, otherwise they look in /usr/local/bin.

Environment Variables

Variable	Description	Default	Values
`GLOBAL_LAUNCHER_TIMEOUT`	Execution-mode timeout in seconds: how long the launcher waits for a target binary invoked through its symlink before giving up. This is the only way to change that timeout (--timeout does not do it)	900	positive integer (seconds)
`GLOBAL_BIN_DIR`	Directory the symlinks are created in and removed from. Overrides the built-in /usr/local/bin target for deploy, verify and cleanup	/usr/local/bin	absolute path to a directory on PATH
`KODACHI_BASE_DIR`	Override the hooks directory. Decides where results/deployment-hashes.json and results/verification-hashes.json are written, and is propagated to every binary the launcher runs	auto-detected from the launcher's own location	absolute path to the hooks directory
`NO_COLOR`	Disable colored output when set to any value	unset	any value disables color

Exit Codes

Code	Description
0	Success
1	General error
10	Security violation
2	Invalid arguments
3	Permission denied
4	Binary not found
5	Directory not found
6	Timeout
7	Deployment or verification failure (deploy could not create every symlink, or verify found broken symlinks). Recovery: sudo ./global-launcher cleanup && sudo ./global-launcher deploy
8	Execution error
9	Validation error