Binary reference

logs-hook

A robust, secure, and configurable logging system for Kodachi OS

Version10.0.3Size1.6MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	logs-hook
Version	10.0.3
Build Date	Not disclosed
Rust Version	1.88.0
File Size	1.6MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	A robust, secure, and configurable logging system for Kodachi OS
Git Commit	unknown
Metadata Generated	2026-09-29T22:00:22Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

03b01ef4ea66e01a794321e095668c649b39570d4ca43c670edf66067038df43

Features

#	Feature
1	Centralized logging system
2	Log rotation with configurable limits
3	Secure log wiping
4	Multiple log levels support
5	JSON output format
6	Embedded configuration system

Security Features

Feature	Description
Authentication	Not implemented in this crate (online-auth is a separate binary)
Encryption	Not implemented in this crate (log files are stored as plain text)
Input Validation	Sanitizes script names and messages
Rate Limiting	Not implemented in this crate (handled externally if required)

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo for system logs
Dependencies	tokio runtime, filesystem access

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
`--json-human`	Enhanced, colorized JSON output (jq-style); implies --json
`--log-level <LEVEL>`	Set CLI log level, error\|warn\|info\|debug (parsed globally; not applied by logs-hook, use the log --level flag instead)
`--json-filter <FIELDS>`	Filter JSON output fields (parsed globally; not applied by logs-hook)
`--verbose`	Enable verbose output (parsed globally; not applied by logs-hook)
`--quiet`	Suppress non-essential output (parsed globally; not applied by logs-hook)
`--no-color`	Disable colored output
`-t, --timeout <SECS>`	Set timeout (parsed globally; not applied by logs-hook)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`-o, --output-format <FORMAT>`	Force output format (default: text)
`--config <FILE>`	Configuration file path (parsed globally; logs-hook uses embedded config only)
`--fields <FIELD_LIST>`	Select specific fields to include in output (parsed globally; not applied by logs-hook)
`--limit <NUMBER>`	Limit number of results returned (parsed globally; not applied by logs-hook)
`--offset <NUMBER>`	Skip first N results for pagination (parsed globally; not applied by logs-hook)

Commands

Logging Commands

`log`

Log a message

Usage:

logs-hook log --script <SCRIPT> --level <LEVEL> <MESSAGE>

Options:

--script, -s <SCRIPT>: Script name for the log entry
--level, -l <LEVEL>: Log level (info, warn, error, debug, fatal)

Examples:

logs-hook log --script 'my-script' --level info 'Script started'

logs-hook log -s 'backup' -l warn 'Low disk space'

logs-hook log --script 'app' --level error 'Connection failed' --json

Maintenance Commands

`maintenance rotate`

Rotate a specific log file (--file is required)

Usage:

logs-hook maintenance rotate --file <FILE>

Options:

--file, -f <FILE>: Log file to rotate (required; rotate-all is not supported)

Examples:

logs-hook maintenance rotate --file /path/to/log.txt

logs-hook maintenance rotate --file /path/to/log.txt --json

`maintenance wipe`

Wipe log files (--all, --file, or --confirm is required)

Usage:

logs-hook maintenance wipe (--all | --file <FILE> | --confirm)

Options:

--all, -a: Wipe all logs
--file, -f <FILE>: Specific log file to wipe
--confirm: Explicitly confirm wipe using the default policy (required when neither --all nor --file is given)

Examples:

logs-hook maintenance wipe --all

logs-hook maintenance wipe --file /path/to/log.txt

logs-hook maintenance wipe --all --json

logs-hook maintenance wipe --confirm

Help Commands

`help`

Show targeted help for a command path (handled before clap parsing)

Usage:

logs-hook help [<COMMAND> [<SUBCOMMAND>]]

Examples:

logs-hook help

logs-hook help log

logs-hook help maintenance wipe

Operational Scenarios

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

Scenario 1: Basic Usage

Writing log entries. logs-hook does not require root: it appends to <base_dir>/logs/<script>-log.log, where <base_dir> is auto-detected (or set with --work-dir / KODACHI_BASE_DIR). Run it as the user that owns that directory.

Step 1: Log an info message from a script

logs-hook log --script 'my-script' --level info 'Script started'

Expected Output: Message logged successfully (appends '2026-07-13 09:14:02 UTC [INFO] | my-script: Script started' to <base_dir>/logs/my-script-log.log)

Step 2: Log a warning using the short flags

logs-hook log -s 'backup' -l warn 'Low disk space'

Expected Output: Message logged successfully (line appended to <base_dir>/logs/backup-log.log)

Step 3: Log an error

logs-hook log --script 'app' --level error 'Connection failed'

Expected Output: Message logged successfully

Note

--level accepts info, warn, error, debug or fatal. It defaults to info, and --script plus the message are both required.

Step 4: Log a debug message

logs-hook log --script 'app' --level debug 'Verbose trace'

Expected Output: Message logged successfully

Step 5: Log a fatal message

logs-hook log --script 'app' --level fatal 'Unrecoverable failure'

Expected Output: Message logged successfully

Note

Fatal is the highest severity; reserve it for unrecoverable conditions

Scenario 2: Maintenance Operations

Rotating and wiping log files. Wiping is IRREVERSIBLE: there are three distinct wipe paths (--all, --file and --confirm) and they do not target the same files.

Step 1: Force-rotate one log file to a numbered backup

logs-hook maintenance rotate --file <BASE_DIR>/logs/app-log.log

Expected Output: Log rotation completed for: "<BASE_DIR>/logs/app-log.log"

Note

--file is required and the file must exist; rotate-all is not supported. A bare 'maintenance rotate' exits 2.

Step 2: Wipe every log file in the log directory

logs-hook maintenance wipe --all

Expected Output: All logs wiped successfully

Note

DESTRUCTIVE and irreversible: this clears every log in <base_dir>/logs, not just the ones a policy selects. Rotate first if you need the history.

Step 3: Wipe one named log file

logs-hook maintenance wipe --file <BASE_DIR>/logs/app-log.log

Expected Output: Log wiped successfully: "<BASE_DIR>/logs/app-log.log"

Note

DESTRUCTIVE and irreversible for that file. The file must exist and be writable, otherwise the command exits 1 with FILE_NOT_FOUND.

Step 4: Wipe logs using the configured retention policy

logs-hook maintenance wipe --confirm

Expected Output: Logs wiped based on configuration

Note

DESTRUCTIVE and irreversible. Different from --all: it wipes only what the embedded log-hook-config policy targets (all logs, or just the ones past the retention condition). --confirm is required whenever neither --all nor --file is given; a bare 'maintenance wipe' is refused.

Scenario 3: Advanced Usage

Redirecting the log tree and running against a root-owned hooks directory.

Step 1: Write to a different base directory instead of the auto-detected one

logs-hook --work-dir /custom/path log --script 'debug' --level info 'Custom directory test'

Expected Output: Message logged successfully (line appended to /custom/path/logs/debug-log.log)

Note

--work-dir is created if missing and also sets KODACHI_BASE_DIR and LOGS_HOOK_WORK_DIR for this run. It must be a directory, not a file.

Step 2: Log into a root-owned base directory (for example the deployed /opt hooks tree)

sudo logs-hook log --script 'installer' --level info 'Deployed'

Expected Output: Message logged successfully

Note

This is the ONLY case that needs sudo: logs-hook itself does not require root, it only needs write access to <base_dir>/logs. Under sudo it restores the log file's ownership to the invoking user afterwards.

Step 3: Point logs-hook at a base directory through the environment instead of a flag

KODACHI_BASE_DIR=/opt/kodachi/dashboard/hooks logs-hook log -s 'cron' -l info 'Nightly job done'

Expected Output: Message logged successfully (line appended to /opt/kodachi/dashboard/hooks/logs/cron-log.log)

Scenario 4: JSON Output

Machine-readable output. Every command returns the standard result envelope (status, command, version, data, duration_ms).

Step 1: Log a message and get the result envelope back as compact JSON

logs-hook --json log --script 'app' --level error 'Connection failed'

Expected Output: {"status":"success","command":"log","data":{"success":true,"message":"Message logged successfully","script":"app","level":"Error","timestamp":"2026-07-13T09:14:02Z"}, ...}

Step 2: Same envelope, indented for reading

logs-hook --json-pretty log -s 'test' -l info 'Test'

Expected Output: Indented JSON envelope with the log result

Step 3: Colorized, jq-style JSON for reading at a terminal

logs-hook --json-human maintenance rotate --file <BASE_DIR>/logs/app-log.log

Expected Output: Highlighted JSON envelope with operation 'rotate' and the resolved absolute file path

Note

--json-human implies JSON mode; do not pipe it to a parser, use --json for that.

Step 4: Version as JSON

logs-hook -v --json

Expected Output: JSON envelope carrying name, version and build metadata

Step 5: Program info (features, security posture, requirements) as JSON

logs-hook -n --json

Expected Output: JSON envelope with the program info block

Step 6: Wipe every log and capture the outcome for a script

logs-hook maintenance wipe --all --json

Expected Output: {"status":"success","command":"maintenance wipe","data":{"operation":"wipe_all","message":"All logs wiped successfully"}, ...}

Note

DESTRUCTIVE and irreversible: --json only changes the reporting, not the effect.

Scenario 5: Troubleshooting

Discovering the exact flags of a subcommand and checking where output is going.

Step 1: Show the full help for one command path without running it

logs-hook help maintenance wipe

Expected Output: The clap long help for 'maintenance wipe', listing --all, --file and --confirm

Note

'logs-hook help [<COMMAND> [<SUBCOMMAND>]]' is handled before argument parsing, so it works for 'log', 'maintenance', 'maintenance rotate' and 'maintenance wipe'. Bare 'logs-hook help' prints the top-level help.

Step 2: Log without ANSI colour codes, for capture into a file or a CI log

logs-hook --no-color --json log --script 'debug' --level debug 'Debug info'

Expected Output: Plain JSON envelope with no escape sequences

Step 3: Confirm which directory a log actually landed in when the base directory is ambiguous

logs-hook --work-dir /custom/path --json log -s 'pathcheck' -l info 'where did this go'

Expected Output: Success envelope; the line is in /custom/path/logs/pathcheck-log.log

Note

logs-hook accepts --verbose, --quiet, --timeout, --fields, --limit and --offset because they are cli-core globals, but it does not act on them. Use --work-dir and the JSON envelope to diagnose path problems.

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)
`KODACHI_BASE_DIR`	Base directory for logs	auto-detected	/path/to/base/dir
`LOGS_HOOK_WORK_DIR`	Working directory for logging operations	current directory	/path/to/work/dir

Exit Codes

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