{ "report_info": { "version": "9.8.4", "generated_at": "2026-07-21T01:54:44Z", "target_directory": "/opt/kodachi/dashboard/hooks", "total_binaries": 26 }, "binaries": [ { "name": "online-info-switch", "path": "/opt/kodachi/dashboard/hooks/online-info-switch", "timestamp": "2026-07-21T01:54:11Z", "file_info": { "size": 6554816, "sha256": "dc80c8413a6e5ac26d687ccb3b72cc9b1a66679982c916126301a37d1f11d96f" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Online information hub for Kodachi OS - RSS feeds, paste services, freshness proofs, and connectivity status", "features": [ "Online/offline status checking via health-control", "RSS feed aggregation from security news sources", "Public paste service integration", "Proof of freshness with current news and blockchain data", "Crypto and precious metals prices, Bitcoin balance lookups", "Kodachi cloud, knet and Tor exit checks" ], "license": "Proprietary", "name": "online-info-switch", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:11.871219754Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "online-info-switch", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:11.981964142Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Connectivity", "commands": [ { "description": "Show current online/offline status", "examples": [ "online-info-switch status", "online-info-switch status --json", "online-info-switch status --json-pretty" ], "name": "status", "options": [ { "description": "Emit the status as compact JSON (global flag)", "flag": "--json", "required": false }, { "description": "Global request timeout", "flag": "-t, --timeout ", "required": false } ], "requires_sudo": false, "usage": "online-info-switch status" } ] }, { "category": "Kodachi Cloud", "commands": [ { "description": "Check Kodachi release information", "examples": [ "online-info-switch releases", "online-info-switch releases binary_pack", "online-info-switch releases desktop", "online-info-switch releases --json-pretty" ], "name": "releases", "options": [ { "description": "Edition to report on: binary_pack, terminal or desktop. Omit for all of them", "flag": "[EDITION]", "required": false } ], "requires_sudo": false, "usage": "online-info-switch releases [EDITION]" }, { "description": "Fetch Kodachi cloud infrastructure statistics", "examples": [ "online-info-switch cloud-stats", "online-info-switch cloud-stats --timeout 120", "online-info-switch cloud-stats --json-pretty" ], "name": "cloud-stats", "options": [ { "default": "60", "description": "Request timeout. The stats endpoint can be slow", "flag": "-t, --timeout ", "required": false }, { "description": "Emit the statistics as compact JSON (global flag)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "online-info-switch cloud-stats" }, { "description": "Check Kodachi network connection status", "examples": [ "online-info-switch knet-status", "online-info-switch knet-status --json", "online-info-switch knet-status --timeout 60" ], "name": "knet-status", "options": [ { "default": "30", "description": "Request timeout for the knet lookup", "flag": "-t, --timeout ", "required": false }, { "description": "Emit the knet state as compact JSON (global flag)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "online-info-switch knet-status" }, { "description": "Check VPS Tor exit IP through SOCKS5 proxy", "examples": [ "online-info-switch vps-tor-check", "online-info-switch vps-tor-check --socks-port 9150", "online-info-switch vps-tor-check --socks-host 192.168.1.100 --socks-port 9051", "online-info-switch vps-tor-check --json-pretty" ], "name": "vps-tor-check", "options": [ { "default": "127.0.0.1", "description": "SOCKS5 proxy host. Supplying it disables port auto-detection", "flag": "--socks-host ", "required": false }, { "default": "9050", "description": "SOCKS5 proxy port. When neither flag is given, ports 9050, 9150 and the Kodachi pool 10000 to 10019 are probed and the first listener wins", "flag": "--socks-port ", "required": false } ], "requires_sudo": false, "usage": "online-info-switch vps-tor-check [OPTIONS]" } ] }, { "category": "Markets", "commands": [ { "description": "Check cryptocurrency and precious metals prices", "examples": [ "online-info-switch price btc", "online-info-switch price xmr", "online-info-switch price gold", "online-info-switch price all", "online-info-switch price all --json" ], "name": "price", "options": [ { "description": "Symbol to price: btc, eth, xmr, azero, near, gold, silver, xau, xag, or all", "flag": "", "required": true } ], "requires_sudo": false, "usage": "online-info-switch price " }, { "description": "Check Bitcoin wallet balance", "examples": [ "online-info-switch balance 34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo", "online-info-switch balance bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2 --json" ], "name": "balance", "options": [ { "description": "Bitcoin address (legacy or bc1 Segwit). It is sent to public blockchain explorers, which see it and your exit IP", "flag": "
", "required": true } ], "requires_sudo": false, "usage": "online-info-switch balance
" } ] }, { "category": "News and Freshness", "commands": [ { "description": "Fetch RSS feeds from security news sources", "examples": [ "online-info-switch rss", "online-info-switch rss --max-items 5", "online-info-switch rss --random", "online-info-switch rss --sources \"darkreading,wired\"", "online-info-switch rss --json-pretty" ], "name": "rss", "options": [ { "description": "Comma separated list of RSS sources to fetch. Conflicts with --random", "flag": "-s, --sources ", "required": false }, { "default": "false", "description": "Fetch from a single randomly chosen source. Conflicts with --sources", "flag": "-r, --random", "required": false }, { "default": "10", "description": "Maximum number of items to display", "flag": "-m, --max-items ", "required": false } ], "requires_sudo": false, "usage": "online-info-switch rss [OPTIONS]" }, { "description": "Show proof of system freshness", "examples": [ "online-info-switch freshness", "online-info-switch freshness --json", "online-info-switch freshness --json-pretty" ], "name": "freshness", "options": [ { "description": "Emit the freshness proof as compact JSON (global flag)", "flag": "--json", "required": false }, { "description": "Global request timeout for the news and blockchain fetches", "flag": "-t, --timeout ", "required": false } ], "requires_sudo": false, "usage": "online-info-switch freshness" } ] }, { "category": "Sharing", "commands": [ { "description": "Upload content to public paste services", "examples": [ "echo \"Hello World\" | online-info-switch paste", "online-info-switch paste \"Sample content\"", "online-info-switch paste --file /path/to/file.txt", "online-info-switch paste \"test\" --services \"paste.rs\"", "online-info-switch paste \"test\" --services \"termbin.com\" --allow-termbin-plaintext", "online-info-switch paste \"test\" --json-pretty" ], "name": "paste", "options": [ { "description": "Content to paste. Read from stdin when omitted. Conflicts with --file", "flag": "[TEXT]", "required": false }, { "description": "Read the content from a file instead. Conflicts with TEXT", "flag": "-f, --file ", "required": false }, { "default": "all", "description": "Comma separated services: paste.rs, dpaste.com, catbox.moe, termbin.com", "flag": "-s, --services ", "required": false }, { "default": "7", "description": "Expiration in days. Accepted and parsed, but no backend service currently applies it", "flag": "--expire ", "required": false }, { "default": "false", "description": "Opt in to termbin.com. WARNING: plaintext TCP on port 9999, bypasses Tor and any proxy, exposes your real IP", "flag": "--allow-termbin-plaintext", "required": false } ], "requires_sudo": false, "usage": "online-info-switch paste [TEXT] [OPTIONS]" } ] } ], "description": "Online information hub for Kodachi OS - RSS feeds, paste services, freshness proofs, and connectivity status", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter " }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir " }, { "description": "Set custom port number (1024-65535)", "flag": "--port " }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout " } ], "name": "online-info-switch", "usage": "online-info-switch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 4, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:12.096580196Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "The four things this tool is reached for most. Every command needs network access, and none of them need root.", "examples": [ { "command": "online-info-switch status", "description": "Check whether the machine currently has working internet access", "expectedOutput": "šŸŒ System is online, followed by location and IP details when available", "notes": "Delegates the connectivity probe to health-control." }, { "command": "online-info-switch rss --max-items 5", "description": "Read the five most recent security headlines", "expectedOutput": "Five headlines, each with publication date, source and link" }, { "command": "online-info-switch freshness", "description": "Prove the system clock and its view of the world are current", "expectedOutput": "Current UTC time, the latest headlines and current blockchain data", "notes": "Useful after a suspend or a clock reset, and as evidence that a snapshot was taken today." }, { "command": "online-info-switch price btc --json", "description": "Read one market price as JSON, for scripting", "expectedOutput": "{\"success\":true,\"coin\":\"BTC\",\"symbol\":\"BTC\",\"price_usd\":64210.5,\"source\":\"...\",\"timestamp\":\"...\"}" } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "Every command takes the same global output flags. --json is the one to script against.", "examples": [ { "command": "online-info-switch status --json", "description": "Compact single line JSON, meant for pipes and workflow steps", "expectedOutput": "{\"is_online\":true,\"status\":\"online\",\"connectivity\":\"FullConnectivity\",\"degraded\":false,\"message\":\"System is online\",\"timestamp\":\"...\"}" }, { "command": "online-info-switch status --json-pretty", "description": "Indented JSON, for reading by eye", "expectedOutput": "The same object, indented over multiple lines" }, { "command": "online-info-switch status --json-human", "description": "Colorized, human oriented rendering of the JSON", "expectedOutput": "The same fields, colored and aligned", "notes": "Colors are dropped automatically when the output is not a terminal." }, { "command": "online-info-switch cloud-stats --timeout 120", "description": "Raise the global request timeout for a slow endpoint", "expectedOutput": "Cloud statistics, or a timeout error after 120 seconds", "notes": "--timeout (-t) is a global flag, in seconds. Without it, cloud-stats uses 60s and knet-status uses 30s." } ], "id": "1_output_formats", "title": "Output Formats" }, { "description": "Pull security headlines from the configured feeds. Feeds are fetched over the current routing, so they travel through Tor or the VPN when those are active.", "examples": [ { "command": "online-info-switch rss", "description": "Fetch the newest items from every configured source", "expectedOutput": "Up to 10 headlines, each with date, source and link", "notes": "A source that is unreachable is skipped rather than failing the whole command." }, { "command": "online-info-switch rss --random", "description": "Fetch from one randomly chosen source instead of all of them", "expectedOutput": "Headlines from a single feed", "notes": "--random and --sources are mutually exclusive." }, { "command": "online-info-switch rss --sources \"darkreading,wired\"", "description": "Fetch only from the named sources", "expectedOutput": "Headlines from darkreading and wired only", "notes": "Comma separated. Short form: -s." }, { "command": "online-info-switch rss --max-items 5", "description": "Cap how many items come back", "expectedOutput": "The 5 newest headlines", "notes": "Defaults to 10. Short form: -m." }, { "command": "online-info-switch rss --json-pretty", "description": "Get the feed items as structured JSON", "expectedOutput": "{\"items\":[{\"title\":\"...\",\"pub_date\":\"...\",\"source\":\"...\",\"link\":\"...\"}],\"total_items\":10}" } ], "id": "2_rss", "title": "RSS Feed Operations" }, { "description": "Upload text to public paste services (paste.rs, dpaste.com and catbox.moe, all over HTTPS). Anything pasted becomes PUBLIC at a URL anyone can open, so never paste keys, credentials, or logs containing your IP. This command requires an authenticated session.", "examples": [ { "command": "echo \"Hello World\" | online-info-switch paste", "description": "Paste from stdin to the default HTTPS services", "expectedOutput": "One URL per service: paste.rs, dpaste.com and catbox.moe", "notes": "Requires authentication: run `online-auth authenticate` first, otherwise the command returns \"Authentication required\" and exits non-zero." }, { "command": "online-info-switch paste \"Sample content\"", "description": "Paste a literal string", "expectedOutput": "Paste URLs from the default services", "notes": "The pasted content is public and unencrypted. Treat every paste as permanent." }, { "command": "online-info-switch paste --file /path/to/file.txt", "description": "Paste the contents of a file", "expectedOutput": "Paste URLs for the file contents", "notes": "Short form: -f. --file and the inline TEXT argument are mutually exclusive." }, { "command": "online-info-switch paste \"test\" --services \"paste.rs\"", "description": "Send to a single named service", "expectedOutput": "A single paste.rs URL", "notes": "Short form: -s, default \"all\". Known services: paste.rs, dpaste.com, catbox.moe and termbin.com." }, { "command": "online-info-switch paste \"test\" --services \"dpaste.com,catbox.moe,paste.rs\"", "description": "Send to several named services at once", "expectedOutput": "One URL per requested service" }, { "command": "online-info-switch paste \"test\" --services \"termbin.com\" --allow-termbin-plaintext", "description": "Send to termbin.com, which needs an explicit opt-in", "expectedOutput": "A termbin.com URL", "notes": "WARNING: termbin.com uses unencrypted TCP on port 9999, which bypasses Tor and any proxy and exposes your real IP address. Without --allow-termbin-plaintext the service is skipped. Only use it on a trusted network when anonymity does not matter." }, { "command": "online-info-switch paste \"test\" --json-pretty", "description": "Get the per-service results as JSON", "expectedOutput": "{\"results\":[{\"service\":\"paste.rs\",\"success\":true,\"url\":\"https://paste.rs/abc\"}],\"success\":true}", "notes": "When no service succeeds the result is success:false and the exit code is non-zero, so it can be tested in a workflow." } ], "id": "3_paste", "title": "Paste Service Operations" }, { "description": "Combine the current time, the latest headlines and current blockchain data into evidence that the system's view of the world is up to date.", "examples": [ { "command": "online-info-switch freshness", "description": "Print a human readable freshness proof", "expectedOutput": "Current UTC time, the newest headlines and current blockchain data", "notes": "Needs network access: it fetches live news and blockchain data, so it fails offline." }, { "command": "online-info-switch freshness --json", "description": "Get the freshness proof as compact JSON for archiving", "expectedOutput": "{\"utc_time\":\"...\",\"local_time\":\"...\",\"ip_address\":\"...\",\"country\":\"...\",\"country_flag\":\"...\",\"headlines\":[...],\"bitcoin_block_height\":123456,\"crypto_prices\":[...],\"generated_at\":\"...\"}" }, { "command": "online-info-switch freshness --json-pretty", "description": "Get the same proof, indented for reading", "expectedOutput": "The freshness object, indented" } ], "id": "4_freshness", "title": "Freshness Proof Operations" }, { "description": "Live prices for crypto and precious metals, plus Bitcoin balance lookups. Prices come from public APIs, so these commands need network access and can be rate limited.", "examples": [ { "command": "online-info-switch price btc", "description": "Check one cryptocurrency price", "expectedOutput": "BTC: 64,210.50 USD", "notes": "Accepted symbols: btc, eth, xmr, azero, near, gold, silver, xau, xag and all." }, { "command": "online-info-switch price xmr", "description": "Check the Monero price", "expectedOutput": "XMR: 154.20 USD" }, { "command": "online-info-switch price gold", "description": "Check a precious metal spot price", "expectedOutput": "XAU: 2,395.80 USD", "notes": "gold and silver are aliases for the xau and xag symbols; both spellings work." }, { "command": "online-info-switch price all", "description": "Fetch every supported crypto and metal in one call", "expectedOutput": "BTC, ETH, XMR, NEAR, AZERO, GOLD and SILVER prices", "notes": "Crypto and metals are fetched in parallel. A provider that fails is left out of the result rather than failing the command." }, { "command": "online-info-switch price all --json", "description": "Fetch every price as JSON, for a dashboard or a workflow step", "expectedOutput": "{\"success\":true,\"prices\":[{\"symbol\":\"BTC\",\"price_usd\":64210.5}],\"timestamp\":\"...\"}" }, { "command": "online-info-switch balance 34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo", "description": "Look up the balance of a legacy Bitcoin address", "expectedOutput": "The address balance in BTC", "notes": "The address is sent to public blockchain explorers, which see both it and your exit IP. Do not look up an address you want kept private over a clearnet route." }, { "command": "online-info-switch balance bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2 --json", "description": "Look up a Segwit (bc1) address balance as JSON", "expectedOutput": "{\"address\":\"bc1...\",\"balance_btc\":0.0123,\"success\":true}" } ], "id": "5_markets", "title": "Cryptocurrency and Metals" }, { "description": "Query the official Kodachi release API for the current version of each edition.", "examples": [ { "command": "online-info-switch releases", "description": "Show the release info for every edition", "expectedOutput": "Version, date and download info for binary_pack, terminal and desktop" }, { "command": "online-info-switch releases binary_pack", "description": "Show one edition only", "expectedOutput": "Binary Pack version, release date and installation info", "notes": "Editions: binary_pack, terminal, desktop." }, { "command": "online-info-switch releases desktop", "description": "Check the Desktop ISO release", "expectedOutput": "Desktop ISO version and release date" }, { "command": "online-info-switch releases --json-pretty", "description": "Get all release metadata as JSON, to compare against the installed version", "expectedOutput": "Indented JSON with one object per edition" } ], "id": "6_releases", "title": "Release Information" }, { "description": "Check the Kodachi cloud backend, the knet connection and the Tor exit IP. These reach the Kodachi servers, so they need network access.", "examples": [ { "command": "online-info-switch cloud-stats", "description": "Fetch Kodachi cloud infrastructure statistics", "expectedOutput": "User counts, challenge counts and infrastructure totals", "notes": "The stats endpoint can be slow, so the default timeout here is 60 seconds. Raise it with --timeout if it trips." }, { "command": "online-info-switch cloud-stats --timeout 120 --json-pretty", "description": "Fetch the stats as JSON with a longer timeout", "expectedOutput": "Indented JSON with the cloud statistics" }, { "command": "online-info-switch knet-status", "description": "Check whether this machine is on the Kodachi network", "expectedOutput": "knet: On, or knet: Off", "notes": "Default timeout is 30 seconds, overridable with --timeout." }, { "command": "online-info-switch knet-status --json", "description": "Get the knet state as JSON, for the dashboard or a workflow condition", "expectedOutput": "{\"success\":true,\"data\":{\"is_kodachi\":true,\"knet\":\"On\"},\"response_time_ms\":42,\"timestamp\":\"...\"}" }, { "command": "online-info-switch vps-tor-check", "description": "Check the exit IP through the local Tor SOCKS5 proxy", "expectedOutput": "Exit IP and the SOCKS5 proxy endpoint that was used; country is reported as unknown because the Tor check endpoint does not provide it", "notes": "With neither flag given, the SOCKS port is auto-detected: ports 9050, 9150 and the Kodachi multi-instance pool 10000 to 10019 are probed in parallel and the first listener wins. Requires a running Tor." }, { "command": "online-info-switch vps-tor-check --socks-host 192.168.1.100 --socks-port 9051", "description": "Check the Tor exit through a specific remote SOCKS5 proxy", "expectedOutput": "Tor exit IP as seen through that proxy", "notes": "Passing EITHER flag disables auto-detection: the supplied values are used verbatim, and the one you leave out falls back to 127.0.0.1 or 9050." }, { "command": "online-info-switch vps-tor-check --json-pretty", "description": "Get the exit check as JSON for a workflow", "expectedOutput": "{\"success\":true,\"data\":{\"exit_ip\":\"...\",\"country\":\"unknown\",\"socks_host\":\"127.0.0.1\",\"socks_port\":9050},\"response_time_ms\":42,\"timestamp\":\"...\"}" } ], "id": "7_cloud", "title": "Cloud Infrastructure and Tor Exit" } ], "description": "Usage examples for online-info-switch", "name": "online-info-switch", "quickReference": [ "online-info-switch --help", "online-info-switch --version", "online-info-switch --info --json", "online-info-switch --examples", "online-info-switch status", "online-info-switch rss --max-items 5", "online-info-switch freshness", "online-info-switch price btc" ] }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:12.324198043Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-admin", "path": "/opt/kodachi/dashboard/hooks/ai-admin", "timestamp": "2026-07-21T01:54:12Z", "file_info": { "size": 4119056, "sha256": "c7193dbf0df92123865cd117c933a24fc638caf0339c8f4f7167c64fdd8e2813" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:12.882326999Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-admin", "version": "9.8.4", "author": "Warith Al Maawali ", "description": "AI system administration and maintenance", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "SQLite database backup, restore, and integrity checking", "Schema migration to the current database version", "Diagnostics report: database, performance, disk usage, integrity", "Performance tuning: VACUUM/ANALYZE, index rebuild, old-record cleanup", "JSON output on every command for dashboard and automation use" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:13.038511223Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-admin", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:13.204026660Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-admin", "description": "AI system administration and maintenance", "usage": "ai-admin [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Commands", "commands": [ { "name": "db", "description": "Database management operations", "usage": "ai-admin db [OPTIONS]", "options": [ { "flag": "backup --output ", "description": "Copy the database to FILE, confined to the execution folder", "required": true }, { "flag": "restore --backup, -b ", "description": "Overwrite the live database with FILE (destructive; the current file is copied to .pre-restore first)", "required": true }, { "flag": "integrity-check", "description": "Run SQLite PRAGMA integrity_check, exits non-zero on failure" }, { "flag": "migrate", "description": "Apply any pending schema migrations" }, { "flag": "info", "description": "Show path, size, schema version, integrity and fragmentation" } ], "requires_sudo": false, "examples": [ "ai-admin db info", "ai-admin db info --json", "ai-admin db integrity-check", "ai-admin db migrate", "ai-admin db backup --output ai-db-backup.db", "ai-admin db backup --output backups/ai-db-2026-07.db --json", "ai-admin db restore --backup ai-db-backup.db", "ai-admin db restore -b ai-db-backup.db --json-pretty" ] }, { "name": "diagnostics", "description": "Run system diagnostics", "usage": "ai-admin diagnostics [--full] [--json]", "options": [ { "flag": "--full", "description": "Add the SQLite integrity check to the report (slower, exits non-zero when integrity fails)", "default": "false" } ], "requires_sudo": false, "examples": [ "ai-admin diagnostics", "ai-admin diagnostics --json", "ai-admin diagnostics --full", "ai-admin diagnostics --full --json-human" ] }, { "name": "tune", "description": "Performance tuning and optimization", "usage": "ai-admin tune [OPTIONS]", "options": [ { "flag": "optimize", "description": "Run SQLite VACUUM and ANALYZE to reclaim space and refresh stats" }, { "flag": "rebuild-index", "description": "Rebuild the database indexes" }, { "flag": "cleanup --days ", "description": "Delete records older than DAYS (destructive and irreversible)", "default": "30" } ], "requires_sudo": false, "examples": [ "ai-admin tune optimize", "ai-admin tune optimize --json", "ai-admin tune rebuild-index", "ai-admin tune cleanup", "ai-admin tune cleanup --days 7 --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format ", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter ", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields ", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit ", "description": "Limit number of results returned" }, { "flag": "--offset ", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir ", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port ", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level ", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "2": "Invalid arguments", "0": "Success", "1": "General error", "3": "Permission denied", "4": "Network error", "5": "File not found" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:13.526641945Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-admin", "description": "Usage examples for ai-admin", "categories": [ { "id": "0_quick_start", "title": "Quick Start", "description": "The four things you reach for most. ai-admin never needs root, but db and tune require a prior online-auth session (diagnostics does not).", "examples": [ { "command": "ai-admin diagnostics", "description": "See whether the AI database is healthy right now", "expectedOutput": "Text report with Database (status, size, fragmentation), Performance (connection and query time), and Disk Usage (database, temp, total)" }, { "command": "ai-admin db info", "description": "Show the database path, size, schema version and integrity", "expectedOutput": "Path, Size in MB, schema Version, Integrity OK or FAILED, Fragmentation %", "notes": "Requires authentication: run online-auth first, or the command exits with 'Authentication failed'." }, { "command": "ai-admin db backup --output ai-db-backup.db", "description": "Take a copy of the AI database before doing anything risky", "expectedOutput": "Backup created, with the resolved path, size in MB and a SHA-256 checksum", "notes": "--output is required and is confined to the ai-admin execution folder." }, { "command": "ai-admin tune optimize", "description": "Reclaim space and refresh query planner statistics", "expectedOutput": "Optimization result with the space reclaimed" } ] }, { "id": "1_database", "title": "Database Inspection and Migration", "description": "Inspect the SQLite database behind the AI subsystem, verify it is not corrupt, and bring its schema up to the version this build expects. All db subcommands require a prior online-auth session.", "examples": [ { "command": "ai-admin db info", "description": "Show database path, size, schema version and integrity", "expectedOutput": "Path, Size in MB, schema Version, Integrity OK or FAILED, Fragmentation %" }, { "command": "ai-admin db info --json", "description": "Same information as machine-readable JSON", "expectedOutput": "JSON with exists, path, size_bytes, size_mb, version, integrity_ok, fragmentation_percent", "notes": "If the database file does not exist yet, ai-admin initializes the schema before reporting it. A successful response therefore reports exists: true with the full information fields." }, { "command": "ai-admin db integrity-check", "description": "Run SQLite PRAGMA integrity_check on the AI database", "expectedOutput": "Status OK plus size, page count and fragmentation, or a FAILED status listing each corruption issue found", "notes": "Exits non-zero when integrity fails, so it can gate a script." }, { "command": "ai-admin db migrate", "description": "Apply any pending schema migrations", "expectedOutput": "Previous version, Current version, and the number of migrations applied", "notes": "Safe to re-run: it initializes the schema first and applies only what is missing. Take a backup first if the database holds training feedback you cannot regenerate." } ] }, { "id": "2_backup_restore", "title": "Backup and Restore", "description": "Copy the AI database out before a risky change, and put it back after. Backup paths are confined to the ai-admin execution folder.", "examples": [ { "command": "ai-admin db backup --output ai-db-backup.db", "description": "Create a verified copy of the AI database", "expectedOutput": "Backup created, with the resolved path, size in MB and a SHA-256 checksum", "notes": "--output is required. A relative path is resolved against the ai-admin execution folder, NOT against your current shell directory, so the file does not land where you typed it if you are standing elsewhere. Paths containing '..' and absolute paths outside that folder are rejected." }, { "command": "ai-admin db backup --output backups/ai-db-2026-07.db --json", "description": "Back up into a subfolder and capture the result for a script", "expectedOutput": "JSON with backup_path, size_bytes, size_mb, created_at, checksum", "notes": "The subfolder is created if missing, still inside the execution folder." }, { "command": "ai-admin db restore --backup ai-db-backup.db", "description": "Replace the live AI database with a backup", "expectedOutput": "Restored, showing the source backup and the target database", "notes": "DESTRUCTIVE: this overwrites the live database. The current file is first copied to .pre-restore, and the backup is rejected if it fails its integrity or schema check." }, { "command": "ai-admin db restore -b ai-db-backup.db --json-pretty", "description": "Restore using the short flag, with indented JSON output", "expectedOutput": "Indented JSON with status 'restored', backup_path and database_path", "notes": "DESTRUCTIVE: overwrites the live database. -b is the short form of --backup." } ] }, { "id": "3_diagnostics", "title": "System Diagnostics", "description": "One report covering four sections: database, performance, disk usage, and (with --full) integrity. diagnostics is the only command here that does not require authentication.", "examples": [ { "command": "ai-admin diagnostics", "description": "Run the standard three-section health report", "expectedOutput": "Database (status, size, fragmentation), Performance (connection and query time), Disk Usage (database, temp files, total)" }, { "command": "ai-admin diagnostics --full", "description": "Add the SQLite integrity check to the report", "expectedOutput": "The three standard sections plus an Integrity Check section, PASSED or FAILED with the issues listed", "notes": "Exits non-zero if the integrity check fails. Slower than the plain run because it reads every database page." }, { "command": "ai-admin diagnostics --json", "description": "Machine-readable report for the dashboard or a monitor", "expectedOutput": "JSON with database, performance and disk_usage objects (integrity is omitted unless --full is passed)" }, { "command": "ai-admin diagnostics --full --json-human", "description": "Full report as readable, formatted JSON", "expectedOutput": "Formatted JSON with database, performance, disk_usage and integrity {passed, issues}" } ] }, { "id": "4_performance", "title": "Performance Tuning", "description": "Keep the AI database fast: reclaim space, rebuild indexes, and drop records older than a retention window. All tune subcommands require a prior online-auth session.", "examples": [ { "command": "ai-admin tune optimize", "description": "Reclaim free pages and refresh query planner statistics", "expectedOutput": "Optimization result with the space reclaimed", "notes": "Runs SQLite VACUUM and ANALYZE. VACUUM rewrites the whole file, so it needs free disk roughly equal to the current database size." }, { "command": "ai-admin tune rebuild-index", "description": "Rebuild the database indexes after heavy churn", "expectedOutput": "Confirmation that the indexes were rebuilt" }, { "command": "ai-admin tune cleanup", "description": "Remove records older than the default retention window", "expectedOutput": "Cleanup result with the number of records removed", "notes": "DESTRUCTIVE: deleted records are gone. --days defaults to 30. Back up first with 'ai-admin db backup' if the history matters." }, { "command": "ai-admin tune cleanup --days 7 --json", "description": "Aggressive cleanup, keeping only the last week, output as JSON", "expectedOutput": "JSON with the cleanup statistics and records removed", "notes": "DESTRUCTIVE and irreversible. A short window discards recent AI feedback and learning history." }, { "command": "ai-admin tune optimize --json", "description": "Optimize and capture the result in a maintenance script", "expectedOutput": "JSON with the optimization statistics" } ] } ], "quickReference": [ "ai-admin --help", "ai-admin --version", "ai-admin --info --json", "ai-admin --examples", "ai-admin diagnostics", "ai-admin db info --json", "ai-admin db backup --output ai-db-backup.db", "ai-admin tune optimize" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "kodachi-session-helper", "path": "/opt/kodachi/dashboard/hooks/kodachi-session-helper", "timestamp": "2026-07-21T01:54:14Z", "file_info": { "size": 2458368, "sha256": "5492e7eea1fecdcb56b2a0da7e0fa45b660dd433b933ac0c063b79636c197ce5" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Global emergency keyboard shortcut daemon for Kodachi OS", "features": [ "X11 key grab registration with collision detection", "Raw /dev/input hardware corroboration (anti-XTEST)", "Hold-to-trigger with auto-repeat rejection (1500ms default)", "Local session token authentication (no network required)", "Delayed lockdown with cancel capability", "Unix socket for dashboard status queries", "Atomic config reload via SIGHUP", "LUKS device wipe + dashboard nuke combined actions", "X11 disconnect detection with auto-reconnect", "Memory protection via mlock and PR_SET_DUMPABLE" ], "license": "Proprietary", "name": "kodachi-session-helper", "securityFeatures": { "authentication": "Local 256-bit session token (no network dependency)", "encryption": "SHA-256 token digest; memory locked and zeroized on exit", "inputValidation": "All configuration validated; key grabs verified against collisions", "rateLimiting": "Hold-to-trigger with cooldown prevents accidental re-trigger" }, "systemRequirements": { "dependencies": [ "X11 display server", "health-control binary", "/dev/input access (input group)" ], "os": "Linux (Kodachi OS / Debian-based with X11)", "privileges": "User session (non-root); 'input' group for evdev" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:14.140775165Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "kodachi-session-helper", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:14.285460008Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Daemon Control", "commands": [ { "description": "Start the emergency shortcut daemon (foreground, runs until signalled)", "examples": [ "kodachi-session-helper daemon", "kodachi-session-helper daemon --json" ], "name": "daemon", "options": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" } ], "requires_sudo": false, "usage": "kodachi-session-helper daemon [OPTIONS]" }, { "description": "Query the running daemon over its Unix socket", "examples": [ "kodachi-session-helper status", "kodachi-session-helper status --json" ], "name": "status", "options": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" } ], "requires_sudo": false, "usage": "kodachi-session-helper status [OPTIONS]" }, { "description": "Send SIGHUP to the running daemon to reload its configuration", "examples": [ "kodachi-session-helper reload", "kodachi-session-helper reload --json" ], "name": "reload", "options": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" } ], "requires_sudo": false, "usage": "kodachi-session-helper reload [OPTIONS]" } ] } ], "description": "Global emergency keyboard shortcut daemon for Kodachi OS", "environmentVariables": [ { "default": ":0", "description": "X11 display to connect to", "name": "DISPLAY", "values": ":0, :1, etc." }, { "default": "/run/user/", "description": "Runtime directory for the status socket, the config file and the session-token digest. Falls back to /tmp when it is unset or not writable", "name": "XDG_RUNTIME_DIR", "values": "Directory path" } ], "exitCodes": { "0": "Success", "1": "General error (includes: daemon not running for status/reload)", "2": "Invalid arguments", "3": "Permission denied (running as root)", "4": "X11 not available", "5": "Wayland session (unsupported)" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" } ], "name": "kodachi-session-helper", "usage": "kodachi-session-helper [OPTIONS] [COMMAND]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:14.418778670Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Start the emergency shortcut daemon in your desktop session, then confirm the shortcuts armed.", "examples": [ { "command": "kodachi-session-helper daemon", "description": "Start the emergency shortcut daemon in the foreground", "expectedOutput": "Preflight checks pass, the X11 key grabs register, the status socket opens, and the daemon enters its event loop", "notes": "Run it as your desktop user, NOT as root (root exits with code 3). It needs an X11 session (a Wayland session exits with code 5) and membership of the 'input' group for raw /dev/input corroboration." }, { "command": "kodachi-session-helper status", "description": "Confirm the daemon is up and see which shortcuts are armed", "expectedOutput": "Running state, PID, armed shortcut list, evdev state and any lockdown countdown", "notes": "Exits non-zero when no daemon is running, so a script can use it as a liveness probe." }, { "command": "kodachi-session-helper status --json", "description": "The same check, machine readable (this is what the dashboard calls)", "expectedOutput": "JSON envelope with the running flag, the armed shortcuts and the daemon capabilities" } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "What the daemon needs from the session, what it opens, and how it behaves when one is already running.", "examples": [ { "command": "kodachi-session-helper daemon --json", "description": "Start the daemon with machine-readable output", "expectedOutput": "JSON envelope. If a daemon is already running it reports already_running with that daemon's PID and socket path instead of starting a second one", "notes": "The daemon is single-instance: it detects a live socket and refuses to duplicate itself." }, { "command": "DISPLAY=:0 kodachi-session-helper daemon", "description": "Start the daemon from an autostart script or user unit that does not inherit DISPLAY", "expectedOutput": "Daemon connects to the named X11 display and registers its grabs there", "notes": "DISPLAY defaults to :0. XDG_RUNTIME_DIR decides where the socket, the config file and the session-token digest are written; when it is unset or not writable the daemon falls back to /tmp." } ], "id": "1_running_the_daemon", "title": "Running the Daemon" }, { "description": "Status is served over a Unix domain socket at $XDG_RUNTIME_DIR/kodachi-session-helper.sock (fallback: /tmp/kodachi-session-helper.sock). No network is involved.", "examples": [ { "command": "kodachi-session-helper status --json --json-pretty", "description": "Indented status JSON, easier to read by eye than the compact form", "expectedOutput": "Pretty-printed status envelope with one field per line" }, { "command": "kodachi-session-helper status || echo 'session helper is DOWN'", "description": "Use the exit code to alert when the emergency shortcuts are not armed", "expectedOutput": "Either the status report, or the fallback message when the daemon is not running", "notes": "status exits 1 when the socket is absent, which is the state in which the panic shortcuts do nothing." } ], "id": "2_status_and_socket", "title": "Status and Socket" }, { "description": "There is no 'stop' subcommand: the daemon's lifecycle is driven by signals. SIGHUP reloads the configuration, SIGTERM shuts it down cleanly.", "examples": [ { "command": "kodachi-session-helper reload", "description": "Re-read the configuration and re-register the key grabs without restarting", "expectedOutput": "SIGHUP sent to daemon (PID )", "notes": "Exits 1 when the daemon is not running. The configuration file lives at $XDG_RUNTIME_DIR/kodachi-session-helper.json." }, { "command": "kodachi-session-helper reload --json", "description": "The same reload, machine readable, for the dashboard", "expectedOutput": "JSON envelope carrying success:true and the message \"SIGHUP sent to daemon (PID )\"" }, { "command": "kill -HUP $(pgrep -x kodachi-session-helper)", "description": "Reload by signalling the process directly, when the helper is not on PATH", "expectedOutput": "Daemon re-reads its configuration and re-registers the key grabs", "notes": "Same effect as 'reload'. Prefer 'reload': it takes the daemon PID from the session-token digest file rather than matching on the process name." }, { "command": "kill -TERM $(pgrep -x kodachi-session-helper)", "description": "Stop the daemon cleanly", "expectedOutput": "Daemon releases its X11 key grabs, zeroizes the session token in memory and exits", "notes": "This DISARMS the emergency shortcuts. Until the daemon is started again, the panic key combinations do nothing." } ], "id": "3_signals_and_lifecycle", "title": "Signals and Lifecycle" }, { "description": "The standard Kodachi meta-flags. Each of them also works after a subcommand.", "examples": [ { "command": "kodachi-session-helper -n", "description": "List the daemon's features, security properties and system requirements", "expectedOutput": "Feature list (key grabs, evdev corroboration, hold-to-trigger, session token, lockdown), plus the X11 and input-group requirements" }, { "command": "kodachi-session-helper --version --json", "description": "Version as JSON for a build or health check", "expectedOutput": "JSON version envelope with the version, build date and git commit" }, { "command": "kodachi-session-helper daemon -h", "description": "Help for one subcommand, including the SIGHUP and SIGTERM contract", "expectedOutput": "Help for the daemon subcommand only, not the top-level listing", "notes": "Per-subcommand -h and -e work for daemon, status and reload." } ], "id": "4_program_information", "title": "Program Information" } ], "description": "Usage examples for kodachi-session-helper", "name": "kodachi-session-helper", "quickReference": [ "kodachi-session-helper daemon", "kodachi-session-helper status", "kodachi-session-helper status --json", "kodachi-session-helper reload", "kodachi-session-helper --help", "kodachi-session-helper --info --json", "kodachi-session-helper --examples --json" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:14.693687207Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-cmd", "path": "/opt/kodachi/dashboard/hooks/ai-cmd", "timestamp": "2026-07-21T01:54:15Z", "file_info": { "size": 70143588, "sha256": "c35c0614abcd3d07f0d9fb23cc2e5e511ade87e4c06bcf4dcbc1e4bb36090b3d" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:15.910531323Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-cmd", "version": "9.8.4", "author": "Warith Al Maawali", "description": "AI-powered command-line interface for natural language command execution", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Natural language to Kodachi command, with a confidence threshold you control", "Multiple engine tiers: TF-IDF, ONNX, local GGUF LLM, Mistral.rs, GenAI, Claude", "Every live execution is validated through the ai-gateway policy sandbox", "Workflow profiles: multi-step operations matched from one sentence", "Interactive REPL, voice input, and a feedback loop that trains the matcher" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:16.385435103Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-cmd", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:16.792195552Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-cmd", "description": "AI-powered command-line interface for natural language command execution", "usage": "ai-cmd [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Commands", "commands": [ { "name": "query", "description": "Process a natural language query and execute the matching command", "usage": "ai-cmd query \"\"", "options": [ { "flag": "--threshold", "description": "Confidence threshold for execution, from 0.0 to 1.0" }, { "flag": "--dry-run", "description": "Preview without execution" }, { "flag": "--auto-execute", "description": "Auto-execute an eligible read-only match bound to --expected-intent-id" }, { "flag": "--expected-intent-id", "description": "Stable intent ID from a fresh preview; required with --auto-execute" }, { "flag": "--alternatives", "description": "Number of ranked matches to return, from 1 to 10", "default": "1" }, { "flag": "--engine", "description": "AI engine tier: auto, tfidf, onnx, onnx-classifier, llm, mistral, genai, claude", "default": "auto" }, { "flag": "--model-path", "description": "Relative path to an existing Mistral GGUF model inside the execution directory; auto selects Mistral" }, { "flag": "--temperature", "description": "GenAI sampling temperature 0.0-2.0 (default: 0.7)", "default": "0.7" }, { "flag": "--model", "description": "Model name for GenAI tier (supports local, OpenAI/Codex, Claude, Gemini, OpenRouter routing)" }, { "flag": "--tor-proxy", "description": "Route cloud providers through Tor proxy" }, { "flag": "--use", "description": "Use a specific GGUF model file from models/ directory" }, { "flag": "--no-gateway, --skip-gateway", "description": "Bypass gateway validation (dry-run only; rejected for live execution)" } ], "requires_sudo": false, "examples": [ "ai-cmd query \"check network connectivity\"", "ai-cmd query \"start tor service\" --dry-run", "ai-cmd query \"get my ip address\" --json", "ai-cmd query \"check network connectivity\" --alternatives 5 --json", "ai-cmd query \"block internet\" --threshold 0.8", "ai-cmd query \"check tor\" --engine onnx", "ai-cmd query \"check tor\" --engine mistral", "ai-cmd query \"check tor\" --engine mistral --json", "ai-cmd query \"check tor status\" --no-gateway --dry-run", "ai-cmd query \"check tor status\" --skip-gateway --dry-run", "ai-cmd query \"check tor status\" --engine genai --model gpt-4o-mini --dry-run", "ai-cmd query \"check tor status\" --engine genai --model claude-sonnet-4-5 --tor-proxy --dry-run" ] }, { "name": "interactive", "description": "Start interactive REPL mode for continuous queries", "usage": "ai-cmd interactive", "options": [ { "flag": "--threshold", "description": "Confidence threshold for execution, from 0.0 to 1.0" }, { "flag": "--engine", "description": "AI engine tier: auto, tfidf, onnx, onnx-classifier, llm, mistral, genai, claude", "default": "auto" }, { "flag": "--model-path", "description": "Relative path to an existing Mistral GGUF model inside the execution directory; auto selects Mistral" } ], "requires_sudo": false, "examples": [ "ai-cmd interactive", "ai-cmd interactive --threshold 0.8", "ai-cmd interactive --engine onnx", "ai-cmd interactive --engine claude --threshold 0.7", "ai-cmd interactive --engine mistral --model-path ./models/phi.gguf", "ai-cmd interactive --engine genai" ] }, { "name": "feedback", "description": "Submit feedback to improve intent classification", "usage": "ai-cmd feedback \"\" [OPTIONS]", "options": [ { "flag": "--correct-intent", "description": "Specify the correct intent ID" }, { "flag": "--correct-command", "description": "Specify the correct command" }, { "flag": "--comment", "description": "Add a comment" } ], "requires_sudo": false, "examples": [ "ai-cmd feedback \"check network\" --correct-intent network_check", "ai-cmd feedback \"test internet\" --correct-command \"health-control net-check\"", "ai-cmd feedback \"my ip\" --comment \"Should show IP address\"" ] }, { "name": "preview", "description": "Preview intent classification without execution", "usage": "ai-cmd preview \"\"", "options": [ { "flag": "--alternatives", "description": "Number of ranked matches to show, from 1 to 10", "default": "3" } ], "requires_sudo": false, "examples": [ "ai-cmd preview \"check network\"", "ai-cmd preview \"stop tor\" --alternatives 5", "ai-cmd preview \"block internet\" --json" ] }, { "name": "voice", "description": "Voice input mode for natural language queries", "usage": "ai-cmd voice [OPTIONS]", "options": [ { "flag": "--continuous", "description": "Enable continuous listening mode" }, { "flag": "--timeout", "description": "Timeout for voice input in seconds", "default": "30" }, { "flag": "--provider", "description": "STT provider: auto (detect best available), whisper-cpp, vosk, placeholder", "default": "auto" }, { "flag": "--voice", "description": "TTS voice name", "default": "en" }, { "flag": "--speed", "description": "Speech speed (words per minute)", "default": "175" }, { "flag": "--list-devices", "description": "List available audio devices" }, { "flag": "--check-deps", "description": "Check voice engine dependencies" } ], "requires_sudo": false, "examples": [ "ai-cmd voice", "ai-cmd voice --continuous", "ai-cmd voice --timeout 60", "ai-cmd voice --provider whisper-cpp", "ai-cmd voice --voice en-us --speed 200", "ai-cmd voice --list-devices", "ai-cmd voice --check-deps" ] }, { "name": "suggest", "description": "Get proactive command suggestions based on usage patterns", "usage": "ai-cmd suggest [OPTIONS]", "options": [ { "flag": "--limit", "description": "Number of suggestions to show", "default": "5" }, { "flag": "--proactive", "description": "Show proactive suggestions" } ], "requires_sudo": false, "examples": [ "ai-cmd suggest", "ai-cmd suggest --limit 10", "ai-cmd suggest --proactive" ] }, { "name": "workflow", "description": "Execute workflow profiles via natural language queries", "usage": "ai-cmd workflow [\"\"] [--list] [--preview] [--dry-run] [--param KEY=VALUE] [--threshold <0.0-1.0>] [--category ] [--stats]", "options": [ { "flag": "--list, -l", "description": "List all available workflow profiles, grouped by category" }, { "flag": "--preview, -p", "description": "Show the matched profile, its steps and the services it touches, without executing anything" }, { "flag": "--dry-run", "description": "Walk the workflow and print the commands it would run, without running them" }, { "flag": "--param ", "description": "Set a profile parameter. Repeat the flag for several parameters." }, { "flag": "--threshold ", "description": "Minimum confidence (0.0 to 1.0) before a query is accepted as a profile match", "default": "0.6" }, { "flag": "--category, -c ", "description": "Restrict to one category: privacy, emergency, network, security, system, setup, maintenance, recovery, custom" }, { "flag": "--stats", "description": "Show registry statistics: profile counts, categories, service usage" } ], "requires_sudo": false, "examples": [ "ai-cmd workflow --list", "ai-cmd workflow --list --category privacy", "ai-cmd workflow --stats", "ai-cmd workflow \"maximum privacy setup\" --preview", "ai-cmd workflow \"emergency recovery\" --preview", "ai-cmd workflow \"setup network\" --dry-run", "ai-cmd workflow \"tor setup\" --threshold 0.7 --preview", "ai-cmd workflow \"complete anonymity\" --param country=us --preview" ] }, { "name": "tiers", "description": "List all AI engine tiers and their availability status", "usage": "ai-cmd tiers [--json]", "options": [], "requires_sudo": false, "examples": [ "ai-cmd tiers", "ai-cmd tiers --json" ] }, { "name": "tools", "description": "List all callable AI tools with parameter schemas", "usage": "ai-cmd tools [--json]", "options": [], "requires_sudo": false, "examples": [ "ai-cmd tools", "ai-cmd tools --json" ] }, { "name": "providers", "description": "List available GenAI providers and model configuration", "usage": "ai-cmd providers [--json]", "options": [], "requires_sudo": false, "examples": [ "ai-cmd providers", "ai-cmd providers --json" ] }, { "name": "model-info", "description": "Show loaded AI model details and configuration", "usage": "ai-cmd model-info [--json]", "options": [], "requires_sudo": false, "examples": [ "ai-cmd model-info", "ai-cmd model-info --json" ] }, { "name": "policy", "description": "Show current AI policy (intent thresholds, tool allowlist, risk mode)", "usage": "ai-cmd policy [--json]", "options": [], "requires_sudo": false, "examples": [ "ai-cmd policy", "ai-cmd policy --json" ] }, { "name": "export-intents", "description": "Export all intents as JSON catalog for shared libraries", "usage": "ai-cmd export-intents [--output FILE] [--json]", "options": [ { "flag": "--output ", "description": "Write the intent catalog to a relative path inside the execution directory", "default": "stdout" } ], "requires_sudo": false, "examples": [ "ai-cmd export-intents", "ai-cmd export-intents --output intent-catalog.json", "ai-cmd export-intents --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format ", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter ", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields ", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--offset ", "description": "Skip first N results (for pagination)" }, { "flag": "--port ", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level ", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "5": "File not found", "1": "General error", "3": "Permission denied", "0": "Success", "2": "Invalid arguments", "4": "Network error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:17.619243447Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-cmd", "description": "Usage examples for ai-cmd", "categories": [ { "id": "0_authentication", "title": "Authentication: Read This First", "description": "ai-cmd splits into two halves. AUTH-GATED (query, interactive, feedback, voice, workflow): these need a valid online-auth session, and the gate applies even with --dry-run, so on a fresh shell they exit with \"Authentication required\". NOT GATED (preview, suggest, tiers, tools, providers, model-info, policy, export-intents): these work immediately. ai-cmd never needs root.", "examples": [ { "command": "ai-cmd tiers", "description": "Works without authentication: see which engine tiers are ready", "expectedOutput": "The tier list with an availability marker against each engine" }, { "command": "ai-cmd preview \"block internet\" --alternatives 5", "description": "Works without authentication: see what a sentence would match, and what else it nearly matched", "expectedOutput": "The winning intent with its confidence, plus 5 alternative matches", "notes": "preview is the unauthenticated twin of query: it matches but can never execute. Reach for it when you only want to know what ai-cmd thinks you meant." }, { "command": "ai-cmd query \"check network connectivity\" --dry-run", "description": "Needs authentication, even though --dry-run runs nothing", "expectedOutput": "The matched command and its confidence, with nothing executed. On an unauthenticated shell: \"Authentication required. Please authenticate using online-auth first\".", "notes": "Authenticate with online-auth first. This is the most common reason an example here appears to be broken." } ] }, { "id": "1_basic", "title": "Basic Usage", "description": "Ask for what you want in plain English and preview the command it maps to. query is auth-gated (see the Authentication category); every example here is a safe preview.", "examples": [ { "command": "ai-cmd query \"check network connectivity\" --dry-run", "description": "Match a sentence to a Kodachi command without running it", "expectedOutput": "The matched command, its confidence score, and the note that nothing ran" }, { "command": "ai-cmd query \"what is my ip address\" --dry-run --json", "description": "Same preview as JSON, for a script or the dashboard", "expectedOutput": "JSON with the detected intent, the resolved command and the confidence" }, { "command": "ai-cmd query \"check tor status\"", "description": "Match and run: without --dry-run the matched command executes", "expectedOutput": "The live output of the command ai-cmd matched, run through the gateway sandbox", "notes": "This EXECUTES. The match must clear --threshold (default 0.6) and pass the gateway policy. Preview it with --dry-run first if you are not sure what the sentence resolves to." } ] }, { "id": "2_advanced", "title": "Advanced Query Control", "description": "Tighten or loosen the confidence gate, inspect alternatives, and hand execution over to the matcher. query is auth-gated.", "examples": [ { "command": "ai-cmd query \"test dns leak\" --threshold 0.8 --dry-run", "description": "Demand a stronger match before the command is accepted", "expectedOutput": "The preview if confidence is at least 0.8, otherwise a refusal saying the match was too weak" }, { "command": "ai-cmd preview \"block internet\" --alternatives 5", "description": "See the runners-up, to understand why a sentence matched badly", "expectedOutput": "The best intent plus 5 alternatives, each with a score", "notes": "preview never executes, and needs no authentication." }, { "command": "ai-cmd query \"check tor status\" --auto-execute --threshold 0.9", "description": "Run the match through the recovery engine, with no confirmation step and automatic retries", "expectedOutput": "The command runs (retried up to 3 times on failure) if confidence is at least 0.9. If the matched intent is one that requires confirmation, ai-cmd refuses instead and tells you to use 'ai-cmd interactive'.", "notes": "This EXECUTES, unprompted. --auto-execute (-a) is the most consequential flag here: it skips the confirmation-aware execution path in favour of the retrying recovery engine. Always pair it with a high --threshold and a precise sentence, because whatever the matcher picks is what runs. --dry-run overrides it, so -a with --dry-run still only previews." }, { "command": "ai-cmd interactive --threshold 0.8", "description": "Open the REPL and keep asking, without re-typing the flags", "expectedOutput": "An interactive prompt that matches each line you type against the intent catalog", "notes": "Auth-gated. Exit with Ctrl-D." } ] }, { "id": "3_feedback", "title": "Feedback System", "description": "Correct a bad match so the matcher learns from it. Each of these writes a feedback record, and feedback is auth-gated.", "examples": [ { "command": "ai-cmd feedback \"check network\" --correct-intent network_check", "description": "Tell ai-cmd which intent that sentence should have matched", "expectedOutput": "Confirmation that the intent correction was recorded" }, { "command": "ai-cmd feedback \"test internet\" --correct-command \"health-control net-check\"", "description": "Tell ai-cmd which command that sentence should have produced", "expectedOutput": "Confirmation that the command correction was recorded" }, { "command": "ai-cmd feedback \"my ip\" --comment \"Should show IP address\"", "description": "Leave a free-text note when the right answer is not obvious", "expectedOutput": "Confirmation that the comment was recorded", "notes": "Feedback feeds ai-learner and ai-trainer, so corrections show up in later matching, not in the current run." } ] }, { "id": "4_voice", "title": "Voice Input", "description": "Speak a command instead of typing it. voice is auth-gated, and needs a working microphone plus an installed speech-to-text provider.", "examples": [ { "command": "ai-cmd voice --check-deps", "description": "Check whether voice can work on this machine at all", "expectedOutput": "A dependency report for the speech-to-text and text-to-speech providers", "notes": "Start here. With no provider installed, ai-cmd falls back to a placeholder engine that recognizes nothing." }, { "command": "ai-cmd voice --list-devices", "description": "List the audio input devices ai-cmd can see", "expectedOutput": "The available audio capture devices" }, { "command": "ai-cmd voice", "description": "Listen once, match what was said, and act on it", "expectedOutput": "The transcribed sentence and the command it matched", "notes": "A recognized command EXECUTES. Provider defaults to auto, which picks whisper-cpp, then vosk, then the placeholder." }, { "command": "ai-cmd voice --provider whisper-cpp --timeout 60", "description": "Pin a specific speech-to-text engine and wait longer for speech", "expectedOutput": "The transcription from whisper-cpp, with up to 60 seconds of listening", "notes": "--provider accepts auto, whisper-cpp, vosk or placeholder. --timeout is in seconds and defaults to 30." }, { "command": "ai-cmd voice --continuous", "description": "Keep listening and keep acting, until you stop it", "expectedOutput": "A listening loop that matches each utterance in turn", "notes": "Continuous mode executes each recognized command without asking. Do not leave it running unattended." } ] }, { "id": "5_suggestions", "title": "AI Suggestions", "description": "Get command suggestions based on usage patterns", "examples": [ { "command": "ai-cmd suggest", "description": "Get recent command suggestions", "expectedOutput": "List of suggested commands" }, { "command": "ai-cmd suggest --proactive", "description": "Get proactive suggestions", "expectedOutput": "Popular or proactive suggestions" }, { "command": "ai-cmd suggest --limit 5", "description": "Limit number of suggestions", "expectedOutput": "Top 5 suggestions" } ] }, { "id": "6_interactive", "title": "Interactive Mode", "description": "Interactive REPL usage and configuration options", "examples": [ { "command": "ai-cmd interactive", "description": "Open the REPL and ask for things one line at a time", "expectedOutput": "A prompt that matches each line you type, shows the command it resolved to, and asks before running anything risky", "notes": "Auth-gated: authenticate with online-auth first. Exit with Ctrl-D." }, { "command": "ai-cmd interactive --threshold 0.8", "description": "Demand a stronger match for every line in the session", "expectedOutput": "The same REPL, but lines that match below 0.8 confidence are refused" }, { "command": "ai-cmd interactive --engine onnx", "description": "Pin the session to the ONNX semantic matcher", "expectedOutput": "A REPL that resolves every line through the ONNX tier" }, { "command": "ai-cmd interactive --engine mistral --model-path ./models/phi.gguf", "description": "Run the session against a specific local Mistral GGUF model", "expectedOutput": "A REPL backed by the selected Mistral GGUF model", "notes": "--model-path must be a relative path to an existing GGUF file inside the execution directory. Invalid or missing paths are rejected before the session starts. Check installed models with 'ai-cmd model-info'." }, { "command": "ai-cmd interactive --engine claude --threshold 0.7", "description": "Use the cloud Claude tier for the session", "expectedOutput": "A REPL that resolves each line through the Claude tier", "notes": "Cloud tiers need an API key and network access, and they send your query text off the machine. Use --tor-proxy on 'query' if the traffic must go through Tor." } ] }, { "id": "7_engine_tiers", "title": "AI Engine Tiers", "description": "--engine picks which matcher resolves your sentence. Valid values: auto (default), tfidf, onnx, onnx-classifier, llm, mistral, genai, claude. The local tiers (tfidf, onnx, onnx-classifier) work offline; llm and mistral need a GGUF model on disk; genai and claude are cloud tiers that send your query text off the machine. Run 'ai-cmd tiers' to see which are actually usable on this install.", "examples": [ { "command": "ai-cmd tiers", "description": "See which tiers are ready before you pin one", "expectedOutput": "The tier list with an availability marker, and a setup hint against each tier that is not ready", "notes": "Needs no authentication." }, { "command": "ai-cmd query \"check tor\" --engine auto --dry-run", "description": "Let ai-cmd pick the best tier that is actually available", "expectedOutput": "The preview, plus the tier it settled on" }, { "command": "ai-cmd query \"check tor\" --engine tfidf --dry-run", "description": "Force the offline keyword matcher: fastest, needs no model", "expectedOutput": "The preview, resolved by TF-IDF keyword scoring" }, { "command": "ai-cmd query \"check tor status\" --engine onnx --dry-run", "description": "Force the offline semantic matcher (sentence embeddings)", "expectedOutput": "The preview, resolved by embedding similarity", "notes": "Needs the embedding model downloaded. If it is missing, 'ai-cmd tiers' marks onnx unavailable and the query falls back." }, { "command": "ai-cmd query \"check tor status\" --engine onnx-classifier --dry-run", "description": "Force the ONNX intent classifier instead of the embedding matcher", "expectedOutput": "The preview, resolved by direct intent classification", "notes": "onnx and onnx-classifier are different tiers: one compares embeddings, the other classifies the sentence directly. Both need their model downloaded." }, { "command": "ai-cmd query \"is my system secure?\" --engine genai --model llama3:8b --temperature 0.3 --dry-run", "description": "Use a local GenAI provider with less creative sampling", "expectedOutput": "The preview, resolved through the GenAI provider", "notes": "--temperature (0.0 to 2.0, default 0.7) configures the GenAI tier. This example uses a local Ollama model, so the query stays on the machine." }, { "command": "ai-cmd query \"check tor\" --engine mistral --model-path ./models/phi.gguf --dry-run", "description": "Point the local Mistral tier at a specific GGUF file", "expectedOutput": "The preview, resolved by the Mistral model at that path", "notes": "The relative path must stay inside the execution directory and name an existing GGUF file. Use 'ai-cmd model-info' to see which models are on disk." }, { "command": "ai-cmd query \"security audit\" --engine genai --model llama3:8b --dry-run", "description": "Use the GenAI tier against a local Ollama model", "expectedOutput": "The preview, resolved through the GenAI provider routing", "notes": "--model names the backing model. Local Ollama models stay on the machine; a hosted model name (for example gpt-4o-mini or claude-sonnet-4-5) sends the query to that provider instead. Run 'ai-cmd providers' to see what is configured." }, { "command": "ai-cmd query \"detailed analysis\" --engine genai --model gpt-4o-mini --tor-proxy --dry-run", "description": "Send a cloud query through Tor rather than direct", "expectedOutput": "The preview, with the provider call routed over the Tor SOCKS proxy", "notes": "PRIVACY: cloud tiers transmit your query text to a third party. --tor-proxy hides your IP from that provider, it does not hide the text. Needs Tor running. Prefer a local tier for anything sensitive." }, { "command": "ai-cmd query \"check tor status\" --engine claude --dry-run", "description": "Use the Claude cloud tier", "expectedOutput": "The preview, resolved by the Claude tier", "notes": "Needs an API key and network access, and sends the query text off the machine." } ] }, { "id": "7d_tool_calling", "title": "Tool Calling", "description": "Tool-calling queries and tool catalog inspection", "examples": [ { "command": "ai-cmd query \"what's my tor status and dns config?\" --dry-run", "description": "Tool-calling query in safe dry-run mode", "expectedOutput": "Dry-run preview for multi-tool query" }, { "command": "ai-cmd tools --json", "description": "List all callable tools with JSON metadata", "expectedOutput": "JSON tool definitions" }, { "command": "ai-cmd tools", "description": "Show tools grouped by domain", "expectedOutput": "Human-readable tool catalog" }, { "command": "ai-cmd export-intents", "description": "Print the whole intent catalog to stdout", "expectedOutput": "The full intent catalog as JSON on stdout, ready to pipe elsewhere", "notes": "Add --output to write it to a file instead, or --json for an envelope summary rather than the raw catalog. Needs no authentication." } ] }, { "id": "7e_security_routing", "title": "Security-First Routing", "description": "A short, well-known request resolves locally and instantly. A long, open question falls through to a generative tier. Anything that would change your machine's configuration is worth previewing first.", "examples": [ { "command": "ai-cmd query \"check tor status\" --dry-run", "description": "A crisp request: resolves on the local fast path", "expectedOutput": "The matched command with a high confidence score, resolved without any model call" }, { "command": "ai-cmd query \"explain tor routing in detail\" --engine mistral --dry-run", "description": "An open question: needs a generative tier, not a matcher", "expectedOutput": "A generated explanation from the local model rather than a single matched command", "notes": "The generative tiers are slower and need a model on disk. Check with 'ai-cmd tiers' before relying on this in a script." }, { "command": "ai-cmd query \"change dns to cloudflare\" --dry-run", "description": "A configuration change: always preview before you commit", "expectedOutput": "The dns-switch command that would run, with nothing applied", "notes": "Dropping --dry-run really does change your resolver. A DNS change can deanonymize you if it points at a provider you did not intend." } ] }, { "id": "7f_ai_policy", "title": "AI Policy", "description": "View and manage AI policy configuration including intent thresholds, tool allowlists, and risk mode.", "examples": [ { "command": "ai-cmd policy", "description": "Show current AI policy (thresholds, tools, risk mode)", "expectedOutput": "Policy details with intent thresholds and tool list" }, { "command": "ai-cmd policy --json", "description": "AI policy as JSON for programmatic use", "expectedOutput": "JSON with version, thresholds, allowlist, signature status" } ] }, { "id": "8_linux_commands", "title": "Linux System Commands", "description": "General-purpose Linux system commands via natural language", "examples": [ { "command": "ai-cmd query \"how much disk space\" --dry-run", "description": "Disk usage request preview", "expectedOutput": "Dry-run preview for disk space command" }, { "command": "ai-cmd query \"list running processes\" --dry-run", "description": "Process listing request preview", "expectedOutput": "Dry-run preview for process listing command" }, { "command": "ai-cmd query \"check if port 80 is open\" --dry-run", "description": "Network port check request preview", "expectedOutput": "Dry-run preview for port inspection command" }, { "command": "ai-cmd query \"update system packages\" --dry-run", "description": "Safe preview of package update flow", "expectedOutput": "Dry-run preview of package update", "notes": "Remove --dry-run to execute after authentication" }, { "command": "ai-cmd query \"ping example.com\" --dry-run", "description": "Network diagnostic request preview", "expectedOutput": "Dry-run preview for ping diagnostic" }, { "command": "ai-cmd query \"show system logs\" --engine tfidf --dry-run", "description": "Log viewing with explicit TF-IDF engine", "expectedOutput": "Dry-run preview using tfidf tier" }, { "command": "ai-cmd query \"restart nginx service\" --threshold 0.9 --dry-run", "description": "Service management query with strict confidence threshold", "expectedOutput": "Dry-run preview gated by 0.9 threshold" }, { "command": "ai-cmd query \"check firewall rules\" --dry-run", "description": "Firewall inspection query preview", "expectedOutput": "Dry-run preview for firewall status command" } ] }, { "id": "9_threshold_ref", "title": "Confidence Threshold Reference", "description": "The --threshold flag controls minimum confidence required for a match. Range: 0.3 to 1.0. Default: 0.6.", "examples": [ { "command": "ai-cmd query \"check tor\" --threshold 0.3 --dry-run", "description": "Minimum threshold for broad matching", "expectedOutput": "Dry-run preview with loose confidence gating" }, { "command": "ai-cmd query \"check tor\" --threshold 0.6 --dry-run", "description": "Default threshold balance", "expectedOutput": "Dry-run preview with default confidence gating" }, { "command": "ai-cmd query \"block internet\" --threshold 0.8 --dry-run", "description": "Higher threshold for sensitive operations", "expectedOutput": "Dry-run preview with strict confidence gating" }, { "command": "ai-cmd query \"check tor\" --threshold 0.95 --dry-run", "description": "Very strict threshold for near-exact matching", "expectedOutput": "Dry-run preview requiring near-exact match" } ] }, { "id": "10_workflows", "title": "Workflow Profiles", "description": "One sentence, several commands: a workflow profile runs a whole multi-step operation. workflow is auth-gated, and without --preview or --dry-run it EXECUTES every step in the profile.", "examples": [ { "command": "ai-cmd workflow --list", "description": "List all available workflow profiles", "expectedOutput": "Profiles grouped by category (privacy, emergency, network, etc.)" }, { "command": "ai-cmd workflow --list --category emergency", "description": "List only the profiles in one category", "expectedOutput": "The emergency profiles and what each one does", "notes": "--category (-c) accepts exactly: privacy, emergency, network, security, system, setup, maintenance, recovery, custom. Any other value is rejected." }, { "command": "ai-cmd workflow \"maximum privacy setup\" --preview", "description": "Preview privacy workflow profile", "expectedOutput": "Workflow details, steps, and services used", "notes": "Use without --preview to execute after review" }, { "command": "ai-cmd workflow \"emergency recovery\" --preview", "description": "Preview emergency recovery workflow", "expectedOutput": "Workflow details, steps, and services used" }, { "command": "ai-cmd workflow \"setup network\" --dry-run", "description": "Dry-run workflow execution", "expectedOutput": "Shows what would be executed without running commands" }, { "command": "ai-cmd workflow \"tor setup\" --threshold 0.7 --preview", "description": "Preview with custom confidence threshold", "expectedOutput": "Workflow preview if confidence >= 0.7" }, { "command": "ai-cmd workflow --stats", "description": "Show workflow registry statistics", "expectedOutput": "Profile counts, categories, and service usage" }, { "command": "ai-cmd workflow \"complete anonymity\" --param country=us --preview", "description": "Preview workflow with custom parameters", "expectedOutput": "Workflow with custom parameter values", "notes": "Pass key=value pairs for profile parameters" } ] }, { "id": "11_models_and_providers", "title": "Models, Tiers and Providers", "description": "Find out what this install can actually run: which engine tiers are ready, which GGUF models are on disk, and which cloud providers are configured. None of these commands needs authentication, and none of them changes anything. Models are downloaded by ai-trainer, not here.", "examples": [ { "command": "ai-cmd tiers", "description": "List the engine tiers and whether each one is usable", "expectedOutput": "Each tier with an available or unavailable marker, and a setup hint for the ones that are not ready" }, { "command": "ai-cmd tiers --json", "description": "Same readiness check, as JSON for a health probe", "expectedOutput": "JSON with each tier, its availability and its setup hint" }, { "command": "ai-cmd model-info", "description": "Show which models are on disk and which tier each one serves", "expectedOutput": "The model inventory: paths and availability for the embedding and LLM backends", "notes": "Run this before a query that pins --engine llm or --engine mistral, so you know the model is really there." }, { "command": "ai-cmd query \"check tor\" --use Qwen3-1.7B-Q4_K_M.gguf --dry-run", "description": "Run one query against a specific GGUF file from the models folder", "expectedOutput": "The preview, resolved by that model", "notes": "--use names a file inside the models directory. The file must already exist: 'ai-cmd model-info' lists what is there, and ai-trainer downloads new ones." }, { "command": "ai-cmd providers", "description": "List the provider backends and whether they are configured", "expectedOutput": "Each provider with its status" }, { "command": "ai-cmd providers --json", "description": "Provider status as JSON, for an automated check", "expectedOutput": "JSON with each provider and the fields a health check needs" } ] }, { "id": "12_gateway_core", "title": "Gateway Core Integration", "description": "ai-cmd and ai-gateway share one registry, policy engine and executor, so a command behaves identically whichever door you come in by. The gateway sandbox is MANDATORY for live execution: --no-gateway (alias --skip-gateway) only affects the dry-run preview path, and ai-cmd refuses it outright without --dry-run (\"--no-gateway cannot be used without --dry-run\").", "examples": [ { "command": "ai-cmd query \"check tor status\" --dry-run --json", "description": "The normal path: the query is validated through the shared gateway core", "expectedOutput": "The preview together with the policy decision the gateway reached" }, { "command": "ai-cmd query \"check tor status\" --no-gateway --dry-run", "description": "Preview WITHOUT the gateway validation step, to see the raw match", "expectedOutput": "The matched command with no gateway policy decision attached, and nothing executed", "notes": "--no-gateway is a preview-only debugging aid. It does NOT let you execute outside the sandbox: used without --dry-run, ai-cmd rejects the command with \"--no-gateway cannot be used without --dry-run. The gateway sandbox is mandatory for live command execution.\"" }, { "command": "ai-cmd query \"test dns leak\" --skip-gateway --dry-run", "description": "The same preview-only bypass, spelled with the alias flag", "expectedOutput": "The raw match for a slow command, with nothing executed", "notes": "--skip-gateway is an alias of --no-gateway and carries the same dry-run-only restriction." }, { "command": "ai-cmd policy --json", "description": "Read the policy guard that gates every live execution", "expectedOutput": "JSON with the policy version, the intent thresholds, the tool allowlist and the signature status", "notes": "This is the command to run when an execution was denied and you want to know why. Needs no authentication." }, { "command": "ai-cmd export-intents --output intent-catalog.json", "description": "Export the whole intent catalog for another tool to consume", "expectedOutput": "The catalog written to intent-catalog.json, with the total intent count", "notes": "The output path is relative to the current directory. Absolute paths and '..' are rejected. Omit --output to print to stdout." } ] } ], "quickReference": [ "ai-cmd --help", "ai-cmd --version", "ai-cmd --info --json", "ai-cmd --examples", "ai-cmd query \"check network connectivity\" --dry-run", "ai-cmd preview \"block internet\" --alternatives 5", "ai-cmd suggest", "ai-cmd tiers", "ai-cmd workflow --list" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "permission-guard", "path": "/opt/kodachi/dashboard/hooks/permission-guard", "timestamp": "2026-07-21T01:54:18Z", "file_info": { "size": 2041152, "sha256": "1937fd33120b9e9f7f7d89995b13c7128994e85fa3d289faf69ed05c428f1a51" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "A robust permission management service for Kodachi OS that monitors and corrects file ownership to prevent root-owned files in user directories", "features": [ "Real-time file permission monitoring", "Automatic permission correction", "Configurable watch directories", "Pattern-based exclusions", "Daemon mode for background operation", "JSON and text output formats", "Field filtering and pagination", "Comprehensive error handling" ], "license": "Proprietary", "name": "permission-guard", "securityFeatures": { "authentication": "Integrates with system user permissions", "encryption": "Secure configuration storage", "inputValidation": "All paths and inputs are sanitized and validated", "rateLimiting": "Configurable scan intervals prevent resource exhaustion" }, "systemRequirements": { "dependencies": [ "systemd", "inotify support" ], "os": "Linux (Debian-based)", "privileges": "root/sudo" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:18.493221018Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "permission-guard", "rustVersion": "unknown", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:18.603932975Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Monitoring Commands", "commands": [ { "description": "Start continuous monitoring with auto-fix (runs until interrupted)", "examples": [ "sudo permission-guard watch", "sudo permission-guard watch /opt/kodachi/dashboard/hooks --scan-interval 60", "permission-guard watch --no-auto-fix --json", "sudo permission-guard --daemon watch" ], "name": "watch", "options": [ { "default": "execution folder", "description": "Directories to monitor. Defaults to the binary's own execution folder. Rejected: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (only /opt/kodachi is allowed) and any path containing '..'", "flag": "[DIRECTORIES]..." }, { "default": "true", "description": "Enable automatic fixing", "flag": "--auto-fix" }, { "description": "Disable automatic fixing", "flag": "--no-auto-fix" }, { "default": "30", "description": "Re-scan interval in seconds for recently active paths. Falls back to the global --timeout value when omitted", "flag": "--scan-interval " }, { "default": "true", "description": "Enable recursive monitoring", "flag": "--recursive" }, { "description": "Disable recursive monitoring", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard watch [OPTIONS] [DIRECTORIES]..." }, { "description": "Perform a one-time scan (report-only unless --fix is passed)", "examples": [ "permission-guard scan --dry-run", "sudo permission-guard scan --fix", "sudo permission-guard scan /opt/kodachi/dashboard/hooks --fix --json", "permission-guard scan \"$HOME/kodachi\" --no-recursive" ], "name": "scan", "options": [ { "default": "execution folder", "description": "Directories to scan. Defaults to the binary's own execution folder. Rejected: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (only /opt/kodachi is allowed) and any path containing '..'", "flag": "[DIRECTORIES]..." }, { "description": "Correct ownership and modes (needs root; ignored when --dry-run is also passed)", "flag": "--fix" }, { "description": "Preview changes without applying", "flag": "--dry-run" }, { "default": "true", "description": "Enable recursive scanning", "flag": "--recursive" }, { "description": "Disable recursive scanning", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard scan [OPTIONS] [DIRECTORIES]..." } ] }, { "category": "Management Commands", "commands": [ { "description": "Show current status and configuration", "examples": [ "permission-guard status", "permission-guard status --detailed", "permission-guard status --json", "permission-guard status --detailed --json" ], "name": "status", "options": [ { "description": "Show detailed information", "flag": "--detailed" } ], "requires_sudo": false, "usage": "permission-guard status [OPTIONS]" }, { "description": "Manage configuration", "examples": [ "permission-guard config show", "permission-guard config show --json" ], "name": "config", "options": [ { "description": "Display current embedded configuration", "flag": "show" } ], "requires_sudo": false, "usage": "permission-guard config " } ] } ], "description": "A robust permission management service for Kodachi OS", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "HTTP proxy for network requests", "name": "HTTP_PROXY", "values": "http://proxy:port" }, { "default": "unset", "description": "HTTPS proxy for secure requests", "name": "HTTPS_PROXY", "values": "https://proxy:port" }, { "default": "~/.config/permission-guard/config.json", "description": "Path to configuration file", "name": "PERMISSION_GUARD_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "0": "Success", "1": "General error", "10": "Command error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Timeout", "7": "Authentication error", "8": "Internal error", "9": "Validation error" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (default: text)", "flag": "-o, --output-format " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set operation timeout in seconds", "flag": "--timeout " }, { "description": "Return only specified fields in JSON output", "flag": "--json-filter " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced human-friendly JSON output", "flag": "--json-human" }, { "description": "Select specific fields to include in output", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Override target user (username or UID)", "flag": "--user-override " }, { "description": "Run as daemon (background process)", "flag": "-d, --daemon" }, { "description": "Custom PID file location", "flag": "--pid-file " }, { "description": "Stop running daemon", "flag": "--stop-daemon" }, { "description": "Show daemon status", "flag": "--daemon-status" } ], "name": "permission-guard", "usage": "permission-guard [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:18.726481803Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "The first three commands on a fresh box. With no directory argument, scan and watch target the binary's own execution folder (on an installed system that is /opt/kodachi/dashboard/hooks).", "examples": [ { "command": "permission-guard scan --dry-run", "description": "Report what is wrong in the hooks tree, change nothing", "expectedOutput": "Performing dry-run scan (no changes will be made) / Files scanned: N / Files needing correction: N" }, { "command": "sudo permission-guard scan --fix", "description": "Correct the ownership and modes that the dry run reported", "expectedOutput": "Scan completed: Files corrected: N, Files failed to correct: 0", "notes": "Needs root: correcting ownership calls chown." }, { "command": "permission-guard status", "description": "Check whether the guard daemon is running and which directories it covers", "expectedOutput": "Daemon state, target user, watched directories and scan intervals currently in effect" }, { "command": "permission-guard config show", "description": "Print the compiled-in configuration defaults and security constraints", "expectedOutput": "Embedded defaults: watch directories, exclude patterns, scan intervals, permission modes", "notes": "These are the embedded defaults, not the live values. Use 'status --detailed' for what is actually running." } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "Which paths permission-guard accepts. Every directory you pass is checked against a denylist before any work starts, so most system paths are refused outright.", "examples": [ { "command": "sudo permission-guard scan /opt/kodachi/dashboard/hooks --fix", "description": "Scan and fix the installed Kodachi hooks tree by explicit path", "expectedOutput": "Scan completed with per-directory counts for the hooks tree", "notes": "/opt/kodachi is the ONLY subtree under /opt the validator accepts; every other /opt path is refused. Needs root." }, { "command": "permission-guard scan \"$HOME/kodachi\" --dry-run", "description": "Preview a scan of a Kodachi checkout in your home directory", "expectedOutput": "Dry-run counts for the given directory, nothing modified", "notes": "Home paths are outside the denylist, and reporting on files you already own needs no root." }, { "command": "sudo permission-guard scan /opt/kodachi/dashboard/hooks \"$HOME/kodachi\" --fix", "description": "Scan several directories in one run", "expectedOutput": "Combined counts across both directories", "notes": "Every directory in the list must pass the denylist; one bad path aborts the whole run." }, { "command": "permission-guard scan /etc", "description": "What a refused path looks like, so you recognise it", "expectedOutput": "Error: Directory path is not in a safe location: /etc (exit code 2)", "notes": "Refused roots: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (except /opt/kodachi) and bare /. Any path containing '..' is refused as well." } ], "id": "1_choosing_directories", "title": "Choosing Directories" }, { "description": "Single-pass scans. Without --fix nothing is changed; --dry-run wins if both are passed.", "examples": [ { "command": "permission-guard scan", "description": "Report-only scan: count problems, change nothing, print the hint to use --fix", "expectedOutput": "Performing scan without fixes (use --fix to enable corrections), then the file counts" }, { "command": "permission-guard scan --dry-run --verbose", "description": "Preview every correction the guard would make, with per-file detail", "expectedOutput": "Verbose per-file listing plus the summary counts, nothing written" }, { "command": "sudo permission-guard scan --fix --no-recursive", "description": "Fix only the top level of the directory, do not descend into subdirectories", "expectedOutput": "Scan completed covering the directory itself only", "notes": "--no-recursive conflicts with --recursive; pass only one. Needs root." }, { "command": "sudo permission-guard --user-override \"$USER\" scan --fix", "description": "Hand ownership to a specific user rather than the auto-detected one", "expectedOutput": "Scan completed with files chowned to the named user", "notes": "--user-override must come BEFORE the subcommand (it is not a global flag). UID 0 and numeric UIDs below 1000 are refused; pass a real username for a system account." }, { "command": "sudo permission-guard --user-override 1001 scan --fix", "description": "Same, using a numeric UID when the username is not known", "expectedOutput": "Scan completed with files chowned to UID 1001", "notes": "Numeric UIDs must be 1000 or above. Unknown users fail with \"User not found\"." } ], "id": "2_one_off_scans", "title": "One-off Scans" }, { "description": "Keep the guard running and re-check permissions as files change. watch runs in the foreground until you interrupt it, unless you add --daemon.", "examples": [ { "command": "sudo permission-guard watch", "description": "Monitor the hooks tree with auto-fix and recursion on (the defaults)", "expectedOutput": "Watcher starts and prints correction events as they happen; runs until Ctrl-C", "notes": "Needs root: auto-fix is on by default and chowns files. Blocks the terminal; use --daemon to background it." }, { "command": "sudo permission-guard watch /opt/kodachi/dashboard/hooks --scan-interval 60", "description": "Re-check recently active paths every 60 seconds instead of the 30 second default", "expectedOutput": "Watcher running with a 60 second rescan interval", "notes": "If --scan-interval is omitted, watch falls back to the global --timeout value. --timeout has no effect on any other command." }, { "command": "permission-guard watch --no-auto-fix --scan-interval 120", "description": "Report-only monitoring: log what is wrong, never change it", "expectedOutput": "Watcher logs permission violations without correcting them", "notes": "--no-auto-fix conflicts with --auto-fix; pass only one. Report-only monitoring needs no root." }, { "command": "sudo permission-guard watch \"$HOME/kodachi\" --no-recursive", "description": "Watch one directory level only", "expectedOutput": "Watcher covering the named directory, ignoring its subdirectories" }, { "command": "permission-guard watch --no-auto-fix --json", "description": "Stream watch events as JSON so a log processor can consume them", "expectedOutput": "JSON event objects on stdout instead of human text", "notes": "Good for piping. Drop --no-auto-fix and add sudo if you also want corrections applied." } ], "id": "3_continuous_monitoring", "title": "Continuous Monitoring" }, { "description": "Inspect the live configuration and the compiled-in defaults. Neither command changes anything, and neither needs root.", "examples": [ { "command": "permission-guard status --detailed", "description": "Full runtime view: target user, watched and excluded directories, every interval", "expectedOutput": "Expanded text report of the active runtime configuration and daemon state" }, { "command": "permission-guard status --detailed --json", "description": "The same detailed view as a single JSON object for a script", "expectedOutput": "JSON envelope whose data block holds the runtime status and active configuration" }, { "command": "permission-guard config show --json", "description": "Read the embedded configuration template as JSON", "expectedOutput": "JSON with the embedded defaults and the security constraints they must satisfy", "notes": "Embedded defaults only. 'status --detailed --json' is the one that reflects the running configuration." } ], "id": "4_status_and_config", "title": "Status and Configuration" }, { "description": "Run the guard detached. --daemon, --pid-file, --stop-daemon and --daemon-status are root-level flags: they must appear BEFORE the subcommand. The default PID file is /tmp/permission-guard.pid.", "examples": [ { "command": "sudo permission-guard --daemon watch", "description": "Start monitoring the hooks tree in the background and return to the shell", "expectedOutput": "Daemon started with PID , then the terminal is free", "notes": "Needs root (auto-fix chowns files). Check it afterwards with --daemon-status." }, { "command": "permission-guard --daemon-status", "description": "Ask whether a guard daemon is running and under which PID", "expectedOutput": "Running with PID , or a message that no daemon is running" }, { "command": "permission-guard --daemon-status --json", "description": "Same check, machine readable, for a monitoring script", "expectedOutput": "JSON with the running flag, the PID and the PID file path" }, { "command": "sudo permission-guard --stop-daemon", "description": "Stop the daemon recorded in the default PID file", "expectedOutput": "Confirmation that the daemon was signalled and stopped", "notes": "Stopping the guard means permissions stop being corrected until you start it again." }, { "command": "sudo permission-guard --daemon --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid watch /opt/kodachi/dashboard/hooks", "description": "Run a second, independently addressable daemon instance", "expectedOutput": "Daemon started with its own PID file and lock file", "notes": "The PID path goes through the SAME denylist as directories: /var/run and /run are refused with \"PID file path is not in a safe location\". Keep instance PID files under /opt/kodachi or in your home directory." }, { "command": "permission-guard --daemon-status --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid", "description": "Check that one named instance specifically", "expectedOutput": "Running state and PID for the daemon recorded in that PID file" }, { "command": "sudo permission-guard --stop-daemon --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid", "description": "Stop that one named instance and leave the others running", "expectedOutput": "Confirmation that the named instance was stopped" }, { "command": "sudo permission-guard --daemon scan --fix", "description": "Run a one-time fix in the background", "expectedOutput": "Scan runs, then the process prints a heartbeat every 60 seconds", "notes": "The daemon deliberately STAYS ALIVE after the scan finishes; end it with --stop-daemon." } ], "id": "5_daemon", "title": "Background Daemon" }, { "description": "Machine-readable output. Field paths are resolved against the JSON envelope, so a bare name such as scan_results is looked up inside the data block automatically. --limit and --offset only reshape list-shaped payloads and have no useful effect on permission-guard, whose scan and status payloads are single objects.", "examples": [ { "command": "permission-guard --json status", "description": "Runtime status as a compact JSON envelope", "expectedOutput": "{\"status\":\"success\",\"command\":\"status\",\"data\":{...}}", "notes": "--json is global: 'status --json' parses identically. This corpus puts it before the subcommand throughout." }, { "command": "permission-guard --json scan --dry-run", "description": "Dry-run results as JSON for a pre-flight check in a script", "expectedOutput": "JSON with scan_results (files_scanned, files_needing_correction, success_rate) and the configuration used" }, { "command": "sudo permission-guard --json scan --fix", "description": "Apply fixes and capture the outcome as JSON", "expectedOutput": "JSON with files_corrected, files_failed and any per-file errors", "notes": "Needs root." }, { "command": "permission-guard --json-pretty --fields scan_results,configuration scan --dry-run", "description": "Indented JSON reduced to just the scan results and the configuration used", "expectedOutput": "Pretty-printed JSON containing only the scan_results and configuration blocks", "notes": "Bare field names are resolved inside the data block. Use dotted paths for anything deeper." }, { "command": "sudo permission-guard --json-filter scan_results.files_corrected,scan_results.files_failed scan --fix", "description": "Cut the JSON down to the two counters a deployment script cares about", "expectedOutput": "{\"scan_results\":{\"files_corrected\":N,\"files_failed\":0}}", "notes": "Nested values need the dotted path. A bare 'files_corrected' does NOT resolve, because it lives under scan_results." }, { "command": "permission-guard --quiet --json status", "description": "JSON only, with warnings and progress chatter suppressed", "expectedOutput": "The JSON envelope on stdout and nothing else" }, { "command": "permission-guard --output-format json config show", "description": "Select JSON with the explicit format flag instead of --json", "expectedOutput": "The same output as 'permission-guard --json config show'" } ], "id": "6_json_automation", "title": "JSON for Automation" }, { "description": "What to run when the guard is not doing what you expect, and what its refusals look like.", "examples": [ { "command": "permission-guard --verbose scan --dry-run", "description": "See exactly which files the guard considers wrong, before touching anything", "expectedOutput": "Per-file expected versus actual owner and mode, plus the summary" }, { "command": "permission-guard --verbose --no-color scan --dry-run", "description": "The same detail as plain text, safe to redirect into a log file", "expectedOutput": "Verbose scan output with no ANSI escape codes" }, { "command": "permission-guard --user-override nonexistent scan", "description": "What an unknown target user looks like", "expectedOutput": "Error: User 'nonexistent' not found (exit code 2)" }, { "command": "permission-guard --pid-file /var/run/pg.pid --daemon-status", "description": "What a refused PID path looks like, so you do not lose time on it", "expectedOutput": "Error: PID file path is not in a safe location (exit code 2)", "notes": "/var and /run are on the denylist. Put instance PID files under /opt/kodachi or in your home directory." } ], "id": "7_troubleshooting", "title": "Troubleshooting" } ], "description": "Usage examples for permission-guard", "name": "permission-guard", "quickReference": [ "permission-guard --help", "permission-guard --version", "permission-guard --info --json", "permission-guard --examples --json", "permission-guard scan --dry-run", "sudo permission-guard scan --fix", "sudo permission-guard watch", "permission-guard status --detailed", "permission-guard config show", "sudo permission-guard --daemon watch", "permission-guard --daemon-status", "sudo permission-guard --stop-daemon" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:18.910847155Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "dns-switch", "path": "/opt/kodachi/dashboard/hooks/dns-switch", "timestamp": "2026-07-21T01:54:19Z", "file_info": { "size": 6873952, "sha256": "1a239e6d3c1b171b65c28852a152e52159b85fe3794bd61835357efc90492f2d" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Production-ready DNS management with security and portability. A self-contained, portable DNS management tool with comprehensive security, health checking, and remote discovery capabilities.", "features": [ "Embedded DNS server lists (no external config dependencies)", "Dynamic path detection (works in any directory)", "Comprehensive input validation and sanitization", "JSON output support for automation", "Health monitoring and performance testing", "Remote DNS server discovery and testing", "Security-focused design with privilege checking", "DNSCrypt proxy integration", "Pi-hole DNS filter integration", "Automatic backup and restore capabilities" ], "license": "Proprietary", "name": "dns-switch", "securityFeatures": { "authentication": "Integrated with Kodachi authentication system", "encryption": "Supports DNSCrypt for encrypted DNS queries", "inputValidation": "All inputs sanitized and validated before use", "rateLimiting": "Built-in rate limiting for remote operations" }, "systemRequirements": { "dependencies": [ "systemd-resolved or resolvconf", "DNSCrypt proxy (optional)", "Pi-hole (optional)" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system changes" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 9, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:19.369364939Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "dns-switch", "rustVersion": "", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:19.498233636Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "DNS Management", "commands": [ { "description": "Switch DNS to a specific category or provider", "examples": [ "sudo dns-switch switch --category reputable", "sudo dns-switch switch --names cloudflare adguard", "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "sudo dns-switch switch --category reputable --verify", "dns-switch switch --names cloudflare --no-action" ], "name": "switch", "options": [ { "description": "DNS category: reputable, normal, fallback or remotely_fetched. The parser recognizes 'encrypted' and 'all', but switch rejects them before changing DNS; use 'dnscrypt-set' for encrypted DNS, or --names dnscrypt for the supported alias path", "flag": "--category ", "required": false }, { "description": "Switch DNS by server names (e.g., cloudflare, adguard)", "flag": "--names ", "required": false }, { "description": "Switch DNS by server IP addresses", "flag": "--servers ", "required": false }, { "default": "off", "description": "Health-check each server and apply only the ones that answer", "flag": "--verify", "required": false }, { "default": "off", "description": "Dry run: print the servers that would be applied and change nothing (also drops the root requirement)", "flag": "--no-action", "required": false }, { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch switch [OPTIONS]" }, { "description": "Switch to random DNS servers with advanced selection", "examples": [ "sudo dns-switch random", "sudo dns-switch random --type reputable --verify", "sudo dns-switch random --type all", "sudo dns-switch random --type reputable,normal --count 6", "dns-switch random --type normal --count 5 --no-action" ], "name": "random", "options": [ { "default": "reputable", "description": "Type of DNS servers: reputable, normal, remotely_fetched, all, or a comma-separated mix of the first three. NOTE: 'encrypted', 'fallback', 'failed' and 'both' are NOT usable here: encrypted servers are configured with dnscrypt-set, fallback uses the embedded pool via 'dns-switch fallback', failed servers are excluded by design", "flag": "--type ", "required": false }, { "default": "3", "description": "Number of random DNS servers to select. Ignored when --type all is used (that always takes 3 per category, up to 9)", "flag": "--count ", "required": false }, { "default": "off", "description": "Health-check the picked servers and apply only the ones that answer", "flag": "--verify", "required": false }, { "default": "off", "description": "Dry run: print the servers that would be applied and change nothing (also drops the root requirement)", "flag": "--no-action", "required": false } ], "requires_sudo": true, "usage": "dns-switch random [OPTIONS]" }, { "description": "Switch to the embedded emergency fallback DNS servers. Applies immediately: this command has NO dry run (--no-action is ignored)", "examples": [ "sudo dns-switch fallback", "sudo dns-switch fallback --json" ], "name": "fallback", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch fallback" }, { "description": "Show current DNS configuration", "examples": [ "dns-switch status", "dns-switch status --json" ], "name": "status", "options": [ { "default": "text", "description": "Machine-readable output (add --json-pretty or --json-human to format it)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch status" } ] }, { "category": "DNS Mode Management", "commands": [ { "description": "Show current DNS management mode (modern vs legacy)", "examples": [ "dns-switch get-mode", "dns-switch get-mode --json" ], "name": "get-mode", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch get-mode" }, { "description": "Set DNS management mode (modern=systemd-resolved, legacy=/etc/resolv.conf)", "examples": [ "sudo dns-switch set-mode --mode modern # Switch to systemd-resolved", "sudo dns-switch set-mode --mode legacy # Switch to legacy /etc/resolv.conf" ], "name": "set-mode", "options": [ { "description": "DNS mode: 'modern' (systemd-resolved) or 'legacy' (/etc/resolv.conf)", "flag": "--mode ", "required": true } ], "requires_sudo": true, "usage": "dns-switch set-mode --mode " }, { "description": "Auto-detect recommended DNS mode for this system", "examples": [ "dns-switch detect-mode", "dns-switch detect-mode --json" ], "name": "detect-mode", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch detect-mode" }, { "description": "Repair broken DNS configuration: mode mismatches, broken symlinks, corrupted files, then applies fallback DNS servers to restore connectivity. Also accepts the legacy alias 'dns-fix'", "examples": [ "sudo dns-switch fix-dns", "sudo dns-switch fix-dns --force", "sudo dns-switch dns-fix" ], "name": "fix-dns", "options": [ { "description": "Run all repair stages even if DNS appears healthy", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "dns-switch fix-dns" }, { "description": "Show which method systemd-resolved uses (global / per-interface / networkmanager / auto)", "examples": [ "dns-switch get-modern-method", "dns-switch get-modern-method --json" ], "name": "get-modern-method", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch get-modern-method" }, { "description": "Set systemd-resolved DNS application method (only relevant in modern mode)", "examples": [ "sudo dns-switch set-modern-method --method global", "sudo dns-switch set-modern-method --method auto" ], "name": "set-modern-method", "options": [ { "default": "auto", "description": "global (resolved.conf, safest), per-interface (resolvectl), networkmanager (nmcli), or auto", "flag": "--method ", "required": true } ], "requires_sudo": true, "usage": "dns-switch set-modern-method --method " }, { "description": "Hand DNS management to a third-party VPN GUI (Mullvad, ProtonVPN, etc.) or take it back. Kodachi normally locks /etc/resolv.conf immutable for DNS-leak protection, which stops those clients from setting their tunnel DNS, so they fail with 'internet blocked' / 'failed to set system DNS'. Turn this ON before connecting such a client, OFF to restore Kodachi-managed DNS. WARNING: while ON, Kodachi's immutable DNS-leak lock is paused and your VPN client must enforce its own leak protection (Mullvad and ProtonVPN do). Clients that strictly require systemd-resolved may still not work; switch to modern mode with 'set-mode --mode modern' for those", "examples": [ "sudo dns-switch external-dns --state on", "sudo dns-switch external-dns --state off", "dns-switch external-dns --state status" ], "name": "external-dns", "options": [ { "default": "status", "description": "on = unlock resolv.conf + pause Kodachi DNS protection so a VPN GUI can manage DNS; off = re-lock and return DNS to Kodachi; status = show current mode (read-only, no sudo)", "flag": "--state ", "required": false } ], "requires_sudo": true, "usage": "dns-switch external-dns --state " } ] }, { "category": "Health & Discovery", "commands": [ { "description": "Check health of DNS servers with detailed analysis (read-only by default)", "examples": [ "dns-switch health", "dns-switch health --type reputable", "dns-switch health --type all", "dns-switch health --type reputable --save", "dns-switch health --full --save", "dns-switch health --fresh --save --json" ], "name": "health", "options": [ { "default": "reputable", "description": "Test a specific category: reputable, normal, encrypted, fallback, remotely_fetched, failed, or all ('both' is deprecated and rejected)", "flag": "--type ", "required": false }, { "description": "Perform comprehensive health check", "flag": "--full", "required": false }, { "description": "Force fresh health check, bypassing cache", "flag": "--fresh", "required": false }, { "description": "Save health check results to database (default: read-only, no database changes)", "flag": "--save", "required": false }, { "description": "BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY (requires --save). Use for urgent cleanup or known-bad servers", "flag": "--force-move", "required": false } ], "requires_sudo": false, "usage": "dns-switch health [OPTIONS]" }, { "description": "Fetch and test remote DNS servers with advanced options", "examples": [ "dns-switch fetch", "dns-switch fetch --count 100", "dns-switch fetch --all", "dns-switch fetch --fresh --json" ], "name": "fetch", "options": [ { "description": "Fetch all available DNS servers (instead of default 25)", "flag": "--all", "required": false }, { "default": "25", "description": "Specify number of DNS servers to fetch", "flag": "--count ", "required": false }, { "description": "Force fresh data retrieval, bypassing all caches", "flag": "--fresh", "required": false }, { "description": "Show fetch history", "flag": "--history", "required": false }, { "description": "Load cached results", "flag": "--load ", "required": false } ], "requires_sudo": false, "usage": "dns-switch fetch [OPTIONS]" }, { "description": "Fetch a specific number of DNS servers from remote sources. This command reads --fetch-count ONLY: a --count passed here is silently ignored and you get the default 25", "examples": [ "dns-switch fetch-count", "dns-switch fetch-count --fetch-count 50", "dns-switch fetch-count --fetch-count 100 --fresh", "dns-switch fetch-count --fetch-count 35 --json" ], "name": "fetch-count", "options": [ { "default": "25", "description": "Number of DNS servers to fetch (this command does NOT read --count)", "flag": "--fetch-count ", "required": false }, { "description": "Force fresh data retrieval, bypassing caches", "flag": "--fresh", "required": false }, { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch fetch-count --fetch-count " }, { "description": "Pull DNSCrypt and Tor DNS servers from your authenticated Kodachi card into the local DB (encrypted category). Requires a valid online-auth session: run 'online-auth authenticate' first", "examples": [ "dns-switch fetch-dns-from-card", "dns-switch fetch-dns-from-card --json" ], "name": "fetch-dns-from-card", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch fetch-dns-from-card" } ] }, { "category": "DNSCrypt Management", "commands": [ { "description": "Show DNSCrypt status (read-only: it changes nothing, so --no-action does nothing here)", "examples": [ "dns-switch dnscrypt", "dns-switch dnscrypt --json" ], "name": "dnscrypt", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch dnscrypt" }, { "description": "Enable DNSCrypt with specific resolver", "examples": [ "sudo dns-switch dnscrypt-set --resolver cloudflare", "dns-switch dnscrypt-set --resolver cloudflare --no-action" ], "name": "dnscrypt-set", "options": [ { "description": "DNSCrypt resolver name", "flag": "--resolver ", "required": true }, { "default": "off", "description": "Dry run: show the DNSCrypt configuration that would be written and change nothing", "flag": "--no-action", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnscrypt-set --resolver " }, { "description": "Restart DNSCrypt proxy", "examples": [ "sudo dns-switch dnscrypt-restart" ], "name": "dnscrypt-restart", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnscrypt-restart" }, { "description": "Remove DNSCrypt configuration", "examples": [ "sudo dns-switch dnscrypt-remove" ], "name": "dnscrypt-remove", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnscrypt-remove" }, { "description": "Show whether the DNSCrypt auto-recovery monitor timer is active", "examples": [ "dns-switch dnscrypt-monitor-status" ], "name": "dnscrypt-monitor-status", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch dnscrypt-monitor-status" }, { "description": "Run a single monitor check now (used by the timer; safe to invoke manually)", "examples": [ "sudo dns-switch dnscrypt-monitor-check" ], "name": "dnscrypt-monitor-check", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnscrypt-monitor-check" }, { "description": "Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure", "examples": [ "sudo dns-switch enable-dnscrypt-monitor" ], "name": "enable-dnscrypt-monitor", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch enable-dnscrypt-monitor" }, { "description": "Disable and remove the DNSCrypt auto-recovery timer", "examples": [ "sudo dns-switch disable-dnscrypt-monitor" ], "name": "disable-dnscrypt-monitor", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch disable-dnscrypt-monitor" }, { "description": "Enable DNSSEC signature validation (require_dnssec=true) in dnscrypt-proxy.toml and restart dnscrypt-proxy. Earns +0.1 dns_privacy score", "examples": [ "sudo dns-switch dnssec-on" ], "name": "dnssec-on", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnssec-on" }, { "description": "Disable DNSSEC validation (require_dnssec=false, default state) in dnscrypt-proxy.toml and restart dnscrypt-proxy", "examples": [ "sudo dns-switch dnssec-off" ], "name": "dnssec-off", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dnssec-off" }, { "description": "Enable DNS-over-HTTPS (doh_servers=true) in dnscrypt-proxy.toml and restart dnscrypt-proxy. The legacy command name says 'dot', but this configures DoH, not DNS-over-TLS. Earns +0.2 dns_privacy score", "examples": [ "sudo dns-switch dot-on" ], "name": "dot-on", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dot-on" }, { "description": "Disable DoH (doh_servers=false) in dnscrypt-proxy.toml; dnscrypt-proxy reverts to DNSCrypt-only protocol and restarts", "examples": [ "sudo dns-switch dot-off" ], "name": "dot-off", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch dot-off" } ] }, { "category": "Boot & Leak Protection", "commands": [ { "description": "One-shot DNS health probe (used at boot to detect and repair empty or broken nameservers). Read-only while DNS is healthy, but it rewrites /etc/resolv.conf with fallback servers when it finds none, so run it with sudo", "examples": [ "sudo dns-switch boot-check", "sudo dns-switch boot-check --json" ], "name": "boot-check", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch boot-check" }, { "description": "Install the systemd service that runs boot-check on every boot (requires auth)", "examples": [ "sudo dns-switch enable-boot-check" ], "name": "enable-boot-check", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch enable-boot-check" }, { "description": "Remove the boot-time DNS validation systemd service (requires auth)", "examples": [ "sudo dns-switch disable-boot-check" ], "name": "disable-boot-check", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch disable-boot-check" }, { "description": "Report any interface with DNS servers different from the expected system DNS (per-interface leak detection)", "examples": [ "dns-switch verify-no-leaks", "dns-switch verify-no-leaks --json" ], "name": "verify-no-leaks", "options": [ { "default": "text", "description": "Machine-readable output with the leaking interfaces listed", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch verify-no-leaks" } ] }, { "category": "Pi-hole Integration", "commands": [ { "description": "Show Pi-hole status", "examples": [ "dns-switch pihole", "dns-switch pihole --json" ], "name": "pihole", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch pihole" }, { "description": "Enable Pi-hole DNS filtering", "examples": [ "sudo dns-switch pihole-enable" ], "name": "pihole-enable", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch pihole-enable" }, { "description": "Disable Pi-hole DNS filtering", "examples": [ "sudo dns-switch pihole-disable" ], "name": "pihole-disable", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch pihole-disable" }, { "description": "Set Pi-hole web interface password. The TOML file is unprotected and re-protected automatically; to change it by hand instead, run 'sudo chattr -i /etc/pihole/pihole.toml' first", "examples": [ "sudo dns-switch pihole-password --password MyNewPassword" ], "name": "pihole-password", "options": [ { "description": "New password for Pi-hole web interface (TOML file auto-unprotected)", "flag": "--password ", "required": true } ], "requires_sudo": true, "usage": "dns-switch pihole-password --password " }, { "description": "Reset Pi-hole configuration", "examples": [ "sudo dns-switch pihole-reset" ], "name": "pihole-reset", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch pihole-reset" } ] }, { "category": "Information & Utilities", "commands": [ { "description": "List available DNS servers", "examples": [ "dns-switch list --category reputable", "dns-switch list --category encrypted", "dns-switch list --category all --json", "dns-switch list --type privacy" ], "name": "list", "options": [ { "default": "all", "description": "Category to list: reputable, normal, encrypted, fallback or all. NOTE: 'remotely_fetched' is NOT a valid value here and is rejected", "flag": "--category ", "required": false }, { "description": "Alias for --category with two extra aliases: privacy (means encrypted) and security (means reputable)", "flag": "--type ", "required": false } ], "requires_sudo": false, "usage": "dns-switch list --category " }, { "description": "Print this help (the positional form of --help). Use ' --help' for a single action", "examples": [ "dns-switch help", "dns-switch switch --help", "dns-switch --help --json" ], "name": "help", "options": [ { "default": "text", "description": "Machine-readable help, used by the dashboard and the docs catalog", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch help" }, { "description": "Count DNS servers by category", "examples": [ "dns-switch count", "dns-switch count --json" ], "name": "count", "options": [ { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch count" } ] }, { "category": "Maintenance & Recovery", "commands": [ { "description": "Clean temporary files and cache", "examples": [ "dns-switch clean", "dns-switch clean --no-action" ], "name": "clean", "options": [ { "default": "off", "description": "Dry run: list the temporary files that would be removed", "flag": "--no-action", "required": false }, { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch clean" }, { "description": "Remove duplicate DNS entries from the local database. Applies immediately: --no-action is ignored by this command", "examples": [ "dns-switch clean-duplicates", "dns-switch clean-duplicates --json" ], "name": "clean-duplicates", "options": [ { "default": "text", "description": "Machine-readable output with the removed-duplicate count", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch clean-duplicates" }, { "description": "Flush systemd-resolved and nscd DNS caches to clear stale entries. Runs as your own user: resolvectl needs no root and the nscd step uses a non-interactive 'sudo -n' that is skipped when it is not available", "examples": [ "dns-switch flush-cache", "dns-switch flush-cache --json" ], "name": "flush-cache", "options": [ { "default": "text", "description": "Machine-readable output listing which caches were flushed", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch flush-cache" }, { "description": "Create a timestamped backup of the dns-switch server database (not /etc/resolv.conf)", "examples": [ "dns-switch backup", "dns-switch backup --json" ], "name": "backup", "options": [ { "default": "text", "description": "Machine-readable output with the backup file path", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "dns-switch backup" }, { "description": "Reset the DNS server database to factory defaults and apply the default DNS. DESTRUCTIVE: custom entries and health history in the database are discarded", "examples": [ "dns-switch restore-default --no-action", "sudo dns-switch restore-default" ], "name": "restore-default", "options": [ { "default": "off", "description": "Dry run: show what would be restored and change nothing", "flag": "--no-action", "required": false }, { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch restore-default" }, { "description": "Restore the DNS server database from a backup (defaults to the most recent one). DESTRUCTIVE and immediate: it overwrites the current database and has NO dry run (--no-action is ignored)", "examples": [ "sudo dns-switch restore-backup", "sudo dns-switch restore-backup --file backup.json" ], "name": "restore-backup", "options": [ { "default": "most recent backup", "description": "Backup file to restore (path may not contain '..')", "flag": "--file ", "required": false }, { "default": "text", "description": "Machine-readable output", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "dns-switch restore-backup [--file ]" } ] } ], "description": "Production-ready DNS management with security and portability", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "~/.config/dns-switch/config.json", "description": "Path to configuration file", "name": "DNS_SWITCH_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Operation timeout", "7": "Authentication error" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Select specific fields to include", "flag": "--fields " }, { "description": "Limit number of results", "flag": "--limit " }, { "description": "Skip first N results", "flag": "--offset " }, { "description": "Specify working directory", "flag": "--work-dir " }, { "description": "Dry run mode", "flag": "--no-action" }, { "description": "Set logging verbosity (error|warn|info|debug|trace)", "flag": "--log-level " } ], "name": "dns-switch", "usage": "dns-switch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:19.611752001Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "The handful of commands that cover a normal day: see what DNS you are on, switch it, prove it did not leak.", "examples": [ { "command": "dns-switch status", "description": "See which DNS servers the system is using right now", "expectedOutput": "Active nameservers with their IPs and where the configuration came from" }, { "command": "sudo dns-switch switch --category reputable", "description": "Move the system onto trusted DNS servers", "expectedOutput": "3 random reputable servers written to the system DNS configuration", "notes": "Needs root because it rewrites the system resolver configuration." }, { "command": "dns-switch verify-no-leaks", "description": "Confirm no interface is quietly using different DNS servers", "expectedOutput": "Either 'no leaks detected' or a list of the interfaces that disagree with the system DNS" }, { "command": "sudo dns-switch fix-dns", "description": "Repair DNS when name resolution is broken", "expectedOutput": "Repairs mode mismatches and broken symlinks, then applies fallback DNS so resolution works again", "notes": "Emergency recovery command. 'dns-fix' is the legacy alias for the same action." } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "Check current DNS configuration and available servers", "examples": [ { "command": "dns-switch status", "description": "Display current system DNS servers with detailed information", "expectedOutput": "Shows active DNS servers, their IPs, and configuration source" }, { "command": "dns-switch status --json", "description": "Get DNS status in machine-readable JSON format", "expectedOutput": "JSON with DNS servers, timestamps, and configuration metadata", "notes": "Useful for scripting and automation" }, { "command": "dns-switch count", "description": "Count available DNS servers by category (reputable, normal, encrypted, etc.)", "expectedOutput": "Summary showing total servers in each category" }, { "command": "dns-switch list --category reputable", "description": "List all reputable DNS servers with details", "expectedOutput": "Table of reputable DNS providers with names, IPs, and locations" } ], "id": "1_dns_status_checking", "title": "DNS Status & Information" }, { "description": "Switch DNS servers by category, by provider name or by IP. Categories accepted by 'switch' are reputable, normal, fallback and remotely_fetched. 'encrypted' and 'all' are recognized but rejected before DNS changes: use 'dnscrypt-set' for encrypted DNS, or the supported '--names dnscrypt' alias path.", "examples": [ { "command": "sudo dns-switch switch --category reputable", "description": "Switch to 3 random reputable DNS servers from the database", "expectedOutput": "System DNS changed to trusted providers like Cloudflare, Quad9, or AdGuard", "notes": "Category switching always picks 3 servers at random from that category." }, { "command": "sudo dns-switch switch --category remotely_fetched", "description": "Switch to servers discovered earlier by the 'fetch' command", "expectedOutput": "System DNS changed to 3 random servers from the remotely_fetched category", "notes": "Run 'dns-switch fetch' first; a normal fetch persists its results, while --no-action previews without database changes." }, { "command": "sudo dns-switch switch --names cloudflare adguard", "description": "Switch to specific DNS providers by name", "expectedOutput": "DNS set to Cloudflare (1.1.1.1) and AdGuard (94.140.14.14)" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "description": "Switch to specific DNS servers by IP address", "expectedOutput": "DNS set to specified IP addresses directly", "notes": "Useful when you know exact server IPs" }, { "command": "sudo dns-switch fallback", "description": "Switch to the embedded fallback DNS servers for emergencies", "expectedOutput": "DNS set to fallback servers from the embedded recovery pool (for example 9.9.9.9, 1.1.1.1, 94.140.14.14)", "notes": "Use when the database is corrupted or unavailable. This command applies immediately and has NO dry run: --no-action is ignored here." } ], "id": "2_basic_dns_switching", "title": "Basic DNS Switching" }, { "description": "Pick DNS servers at random. --type accepts reputable, normal, remotely_fetched, all, or a comma-separated mix of the first three. 'encrypted', 'fallback', 'failed' and 'both' are rejected here.", "examples": [ { "command": "sudo dns-switch random", "description": "Select 3 random DNS servers from reputable category (default behavior)", "expectedOutput": "DNS set to 3 randomly selected reputable servers" }, { "command": "sudo dns-switch random --verify", "description": "Select 3 random reputable DNS servers and verify they work before applying", "expectedOutput": "DNS changed to verified working servers only", "notes": "Only applies servers that pass health check" }, { "command": "sudo dns-switch random --type reputable --verify", "description": "Select 3 random reputable DNS servers and verify each works before applying", "expectedOutput": "DNS changed to verified working reputable servers", "notes": "Health checks each selected server; only uses working ones" }, { "command": "sudo dns-switch random --type normal --count 5", "description": "Select 5 random servers from normal category", "expectedOutput": "DNS set to 5 randomly selected normal servers" }, { "command": "sudo dns-switch random --type normal --count 6 --verify", "description": "Select 6 random normal DNS servers and verify they work before applying", "expectedOutput": "DNS changed to up to 6 verified working servers", "notes": "If some servers fail health check, only working ones are used" }, { "command": "sudo dns-switch random --type reputable,normal --count 6", "description": "Select 6 servers: 3 from reputable + 3 from normal categories", "expectedOutput": "DNS set to 6 servers evenly distributed between categories", "notes": "Count is distributed evenly across specified types" }, { "command": "sudo dns-switch random --type reputable,normal --count 7", "description": "Select 7 servers distributed: 4 reputable + 3 normal", "expectedOutput": "DNS changed to 7 random servers", "notes": "Uneven distribution favors first type" }, { "command": "sudo dns-switch random --type all", "description": "Select 3 servers each from reputable, normal and remotely_fetched (9 total)", "expectedOutput": "DNS set to 9 servers: 3 from each of the 3 categories", "notes": "'all' excludes the encrypted, fallback and failed categories. --count is IGNORED with --type all: you always get up to 3 per category." }, { "command": "sudo dns-switch random --type reputable,normal,remotely_fetched --count 6", "description": "Select 6 servers, 2 from each of the 3 named categories", "expectedOutput": "6 servers evenly distributed across the 3 categories" }, { "command": "sudo dns-switch random --type reputable,normal,remotely_fetched --count 10", "description": "Select 10 servers, distributed 4+3+3 across the 3 categories", "expectedOutput": "10 servers with the remainder given to the first categories", "notes": "The count flag is --count. There is no --count-random flag." }, { "command": "dns-switch random --type reputable --count 5 --no-action", "description": "Preview a random selection without touching the system DNS", "expectedOutput": "The 5 servers that would be applied, with no probes sent and no changes made", "notes": "--no-action also drops the root requirement, so no sudo is needed for a preview." } ], "id": "3_random_dns_selection", "title": "Random DNS Selection" }, { "description": "Test DNS servers for availability and performance. Health checks are read-only by default: use --save to persist results to the database. Valid --type values are reputable, normal, encrypted, fallback, remotely_fetched, failed and all. IMPORTANT: Failed servers are moved to 'failed' category only after 3 CONSECUTIVE failures (3-strike rule) to prevent false positives from temporary network issues. Run health checks 3 times to trigger category changes.", "examples": [ { "command": "dns-switch health", "description": "Test reputable DNS servers (default) for availability and response times (read-only)", "expectedOutput": "Health status for reputable servers with response times", "notes": "Read-only: does not modify the database" }, { "command": "dns-switch health --type reputable", "description": "Test reputable DNS servers only (read-only)", "expectedOutput": "Health status for reputable servers", "notes": "Tests curated high-quality DNS providers. Read-only: does not modify database" }, { "command": "dns-switch health --type reputable --save", "description": "Test reputable servers and save results to database", "expectedOutput": "Health status saved to dns-database.json", "notes": "--save updates: status, response times, geolocation, consecutive_failures counter. Servers move to 'failed' category ONLY after 3 consecutive failures (run 3 times)" }, { "command": "dns-switch health --type normal", "description": "Test normal DNS servers only (read-only)", "expectedOutput": "Health status for normal servers", "notes": "Tests standard reliable DNS providers. Read-only mode" }, { "command": "dns-switch health --type encrypted", "description": "Test encrypted DNS servers (DNSCrypt, DoH, DoT) only", "expectedOutput": "Health status for encrypted servers", "notes": "Tests DNSCrypt and secure DNS providers. Read-only mode" }, { "command": "dns-switch health --type remotely_fetched", "description": "Check health of remotely fetched DNS servers (read-only)", "expectedOutput": "Health status for remotely fetched servers", "notes": "Tests servers previously discovered via 'fetch' command" }, { "command": "dns-switch health --type remotely_fetched --save", "description": "Test remotely fetched servers and save results to database", "expectedOutput": "Health status for remotely fetched servers saved to database", "notes": "3-STRIKE RULE: Servers move to 'failed' category only after 3 consecutive failures. Run this command 3 times to trigger category moves" }, { "command": "dns-switch health --type all", "description": "Test ALL working server categories (excludes failed servers)", "expectedOutput": "Complete report of all working DNS servers across all categories", "notes": "Tests: fallback + reputable + normal + encrypted + remotely_fetched. Excludes failed servers for efficiency. May take several minutes" }, { "command": "dns-switch health --type all --save", "description": "Test all working categories and save results to database", "expectedOutput": "Complete health report saved to database", "notes": "Updates: status, response times, geolocation, consecutive_failures counter. 3-STRIKE RULE: Run 3 times to move failed servers to 'failed' category (prevents false positives)" }, { "command": "dns-switch health --type all --save && dns-switch health --type all --save && dns-switch health --type all --save", "description": "Run health check 3 times to trigger 3-strike rule and move failed servers", "expectedOutput": "After 3rd run: servers with 3 consecutive failures moved to 'failed' category. Check with 'count' command", "notes": "WORKFLOW EXAMPLE: The 3-strike rule requires 3 consecutive failures before moving servers. Run 'count' after 3rd run to see category changes" }, { "command": "dns-switch health --type failed --save", "description": "Test ONLY failed servers and update their status if recovered", "expectedOutput": "Failed servers health check completed - recovered servers moved IMMEDIATELY back to original categories (no 3-strike rule for recovery)", "notes": "Recovery is instant (1 success = move back). Tests servers from dns-database-failed.json. --save required to persist recovery" }, { "command": "dns-switch health --type all --save --force-move", "description": "BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY", "expectedOutput": "Failed servers moved to 'failed' category on FIRST failure (no waiting for 3 strikes). Check with 'count' command", "notes": "āš ļø CAUTION: Bypasses protection against transient network issues. Use for urgent cleanup or when you're CERTAIN servers are permanently down. --save required" }, { "command": "dns-switch health --type remotely_fetched --save --force-move", "description": "Test remotely fetched servers and force-move failures immediately", "expectedOutput": "Remotely fetched servers tested - failures moved to 'failed' category instantly", "notes": "Useful for quickly cleaning up newly discovered servers that are non-responsive. Skips 3-strike protection" }, { "command": "dns-switch health --full --save", "description": "Full health check with geolocation, save results", "expectedOutput": "Comprehensive health data saved to database", "notes": "Full check includes geolocation lookup for all working servers" }, { "command": "dns-switch health --json", "description": "Health check with JSON output (read-only)", "expectedOutput": "JSON formatted health data", "notes": "Default tests reputable servers. Use --type to specify category" }, { "command": "dns-switch health --type encrypted --json", "description": "Test encrypted DNS servers with JSON output for parsing", "expectedOutput": "JSON object with detailed health metrics per server", "notes": "Structured JSON output for automation and integration" }, { "command": "dns-switch health --fresh --save --json", "description": "Fresh health check, save results, JSON output", "expectedOutput": "Real-time health check saved to database in JSON", "notes": "Bypasses cache for current data, persists to database" } ], "id": "4_dns_health_checking", "title": "DNS Health Checking" }, { "description": "Automation-friendly JSON responses", "examples": [ { "command": "dns-switch status --json", "description": "Get status in JSON format", "expectedOutput": "JSON object with current DNS configuration" }, { "command": "dns-switch count --json --json-pretty", "description": "Pretty-printed DNS server counts", "expectedOutput": "Formatted JSON with server statistics" }, { "command": "dns-switch status --json-human", "description": "Human-readable JSON with enhanced formatting", "expectedOutput": "JSON object with improved readability and structure" } ], "id": "5_json_output", "title": "JSON Output" }, { "description": "Switch DNS servers using provider names", "examples": [ { "command": "sudo dns-switch switch --names cloudflare", "description": "Switch to Cloudflare DNS (1.1.1.1)", "expectedOutput": "DNS changed to Cloudflare servers" }, { "command": "sudo dns-switch switch --names cloudflare --verify", "description": "Switch to Cloudflare DNS after verifying it's working", "expectedOutput": "DNS changed to Cloudflare servers (verified working)", "notes": "Health check performed before applying DNS change" }, { "command": "sudo dns-switch switch --names cloudflare QuadServer1", "description": "Switch to Cloudflare and Quad9 DNS servers (space-separated)", "expectedOutput": "DNS changed to multiple providers", "notes": "Multiple names separated by spaces" }, { "command": "sudo dns-switch switch --names cloudflare,QuadServer1,adguard", "description": "Switch to multiple DNS providers (comma-separated)", "expectedOutput": "DNS changed to Cloudflare, Quad9, and AdGuard servers", "notes": "Alternative syntax using commas to separate names" }, { "command": "sudo dns-switch switch --names cloudflare QuadServer1 adguard --verify", "description": "Switch to multiple DNS providers after verifying each works", "expectedOutput": "DNS changed to only verified working servers", "notes": "Only working servers will be applied to resolv.conf" }, { "command": "sudo dns-switch switch --names adguard", "description": "Switch to AdGuard DNS (94.140.14.14, 94.140.15.15) - Privacy-respecting", "expectedOutput": "DNS changed to AdGuard servers", "notes": "Blocks ads and trackers" }, { "command": "sudo dns-switch switch --names opendns", "description": "Switch to OpenDNS (208.67.222.222, 208.67.220.220)", "expectedOutput": "DNS changed to OpenDNS servers" }, { "command": "sudo dns-switch switch --names nextdns", "description": "Switch to NextDNS (45.90.28.167, 45.90.30.167)", "expectedOutput": "DNS changed to NextDNS servers" }, { "command": "sudo dns-switch switch --names cleanbrowsing", "description": "Switch to CleanBrowsing DNS (185.228.168.9, 185.228.169.9)", "expectedOutput": "DNS changed to CleanBrowsing servers", "notes": "Family-friendly content filtering" } ], "id": "6_dns_switching_by_names", "title": "DNS Switching by Names" }, { "description": "Switch DNS servers using IP addresses", "examples": [ { "command": "sudo dns-switch switch --servers 1.1.1.1", "description": "Switch to specific DNS server IP", "expectedOutput": "DNS changed to specified IP" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 --verify", "description": "Switch to specific DNS server IP after verifying it works", "expectedOutput": "DNS changed to specified IP (verified working)", "notes": "Health check ensures DNS server is responsive before applying" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "description": "Switch to multiple specific DNS server IPs", "expectedOutput": "DNS changed to multiple IPs" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9 208.67.222.222 --verify", "description": "Switch to multiple DNS IPs after verifying each works", "expectedOutput": "DNS changed to only verified working IPs", "notes": "Failed servers are excluded from final configuration" }, { "command": "sudo dns-switch switch --servers 94.140.14.14 94.140.15.15", "description": "Switch to AdGuard DNS by IP", "expectedOutput": "DNS changed to AdGuard IPs" } ], "id": "7_dns_switching_by_ip", "title": "DNS Switching by IP" }, { "description": "Discover and fetch new DNS servers from remote sources. None of these need root: they only write the local dns-switch database.", "examples": [ { "command": "dns-switch fetch", "description": "Fetch 25 DNS servers from remote sources, test them, and save to database", "expectedOutput": "Lists fetched servers with country, response time, and success/failure status", "notes": "Default fetches 25 servers" }, { "command": "dns-switch fetch --count 50", "description": "Fetch exactly 50 DNS servers from remote sources", "expectedOutput": "Shows all 50 servers with test results and performance metrics", "notes": "Shows all results when count < 100" }, { "command": "dns-switch fetch --count 100", "description": "Fetch exactly 100 DNS servers from remote sources", "expectedOutput": "100 DNS servers fetched and tested", "notes": "May take longer to complete" }, { "command": "dns-switch fetch-count --fetch-count 35", "description": "Alternative syntax to fetch 35 servers (same result as fetch --count 35)", "expectedOutput": "Lists all 35 fetched servers with detailed information", "notes": "fetch-count reads --fetch-count ONLY. Passing --count to it is silently ignored and you get the default 25." }, { "command": "dns-switch fetch --all", "description": "Fetch ALL available DNS servers from remote sources", "expectedOutput": "Fetches hundreds of servers, shows truncated list with summary", "notes": "Note: Use kitty terminal to see country flags. Total servers > 60,000 so this will take very long to test all servers" }, { "command": "dns-switch fetch --count 35 --fresh", "description": "Force a fresh fetch, bypassing every cache (API cache, result cache)", "expectedOutput": "Real-time fetch with no cached data used", "notes": "--fresh ensures completely new data from remote sources" }, { "command": "dns-switch fetch --json", "description": "Fetch 25 servers with JSON output", "expectedOutput": "JSON response with fetched server details" }, { "command": "dns-switch fetch --count 35 --fresh --json", "description": "Fresh fetch of 35 servers with JSON output", "expectedOutput": "JSON response with fresh server data" }, { "command": "dns-switch fetch --count 10 --no-action", "description": "Preview a fetch without writing anything to the database", "expectedOutput": "The servers that would be fetched and tested, with no database change" }, { "command": "dns-switch fetch --history", "description": "List previous fetch runs and their cache IDs", "expectedOutput": "One line per past fetch with its cache ID, timestamp and server count", "notes": "Take a cache ID from here and hand it to 'fetch --load'." }, { "command": "dns-switch fetch --load ", "description": "Re-open the results of an earlier fetch instead of hitting the network", "expectedOutput": "The stored server list from that fetch run", "notes": "Replace with an ID printed by 'dns-switch fetch --history'." }, { "command": "dns-switch fetch-dns-from-card", "description": "Pull the DNSCrypt and Tor DNS servers of your Kodachi card into the encrypted category", "expectedOutput": "Reports how many DNSCrypt and Tor DNS servers were added to the database", "notes": "Requires an active online-auth session: run 'online-auth authenticate' first, otherwise it fails with an authentication error." } ], "id": "8_remote_dns_fetching", "title": "Remote DNS Discovery & Fetching" }, { "description": "Encrypted DNS and ad-blocking integration", "examples": [ { "command": "sudo dns-switch switch --names dnscrypt", "description": "Switch DNS to use local DNSCrypt (127.0.0.1)", "expectedOutput": "DNS set to use DNSCrypt proxy, service started if needed", "notes": "Automatically starts dnscrypt-proxy service if not running. Aliases: dnscrypt | dnscrypt-server | dnscryptproxy | encrypted" }, { "command": "dns-switch dnscrypt", "description": "Check DNSCrypt proxy service status (read-only)", "expectedOutput": "Shows if DNSCrypt is running, configured resolver, and port" }, { "command": "sudo dns-switch dnscrypt-set --resolver cloudflare", "description": "Configure DNSCrypt to use Cloudflare's encrypted resolver", "expectedOutput": "DNSCrypt configured and started with the Cloudflare resolver", "notes": "Requires the dnscrypt-proxy package. Add --no-action to preview the configuration without writing it." }, { "command": "sudo dns-switch dnscrypt-restart", "description": "Restart DNSCrypt proxy service", "expectedOutput": "DNSCrypt proxy service restarted successfully" }, { "command": "sudo dns-switch enable-dnscrypt-monitor", "description": "Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure", "expectedOutput": "DNSCrypt auto-recovery monitor timer installed and started", "notes": "Runs periodic health checks; on failure restarts DNSCrypt or falls back to safe DNS" }, { "command": "dns-switch dnscrypt-monitor-status", "description": "Show whether the DNSCrypt auto-recovery monitor timer is active", "expectedOutput": "Reports the timer as active or inactive plus the last check state" }, { "command": "sudo dns-switch dnscrypt-monitor-check", "description": "Run a single DNSCrypt monitor check now (the same check the timer performs)", "expectedOutput": "Reports 'check passed', or triggers recovery/fallback on failure", "notes": "Safe to invoke manually; used internally by the auto-recovery timer" }, { "command": "sudo dns-switch disable-dnscrypt-monitor", "description": "Disable and remove the DNSCrypt auto-recovery timer", "expectedOutput": "DNSCrypt auto-recovery monitor timer stopped and removed" }, { "command": "sudo dns-switch dnscrypt-remove", "description": "Stop DNSCrypt and switch to reputable DNS servers", "expectedOutput": "DNSCrypt stopped and DNS switched to regular servers", "notes": "Automatically switches to reputable DNS to avoid DNS being offline" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4", "description": "Switch to remote DNSCrypt IPv4 server from authentication card", "expectedOutput": "DNS switched to remote DNSCrypt IPv4 server from VPS", "notes": "Requires running 'fetch-dns-from-card' first to add remote servers" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv6", "description": "Switch to remote DNSCrypt IPv6 server from authentication card", "expectedOutput": "DNS switched to remote DNSCrypt IPv6 server from VPS", "notes": "Requires running 'fetch-dns-from-card' first to add remote servers" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4,RemoteDNSCryptIPv6", "description": "Switch to both remote DNSCrypt servers (comma-separated)", "expectedOutput": "DNS switched to use both remote DNSCrypt servers for dual-stack support", "notes": "Comma-separated format - both IPv4 and IPv6 from your VPS" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4 RemoteDNSCryptIPv6", "description": "Switch to both remote DNSCrypt servers (space-separated)", "expectedOutput": "DNS switched to use both remote DNSCrypt servers for dual-stack support", "notes": "Space-separated format - alternative syntax for multiple servers" }, { "command": "dns-switch pihole", "description": "Check Pi-hole service status with systemctl info (read-only)", "expectedOutput": "Shows if Pi-hole is running, blocking status, and systemctl_status", "notes": "Use 'systemctl status pihole-FTL.service' to verify service state directly" }, { "command": "sudo dns-switch pihole-enable", "description": "Enable Pi-hole ad blocking DNS with automatic DNSCrypt integration", "expectedOutput": "DNS redirected through Pi-hole for ad/tracker blocking\n ā†’ Pi-hole automatically uses DNSCrypt (127.0.0.1#5353) as upstream\n ā†’ You get encrypted DNS + ad blocking = maximum protection\n ā†’ Secure yet transparent - see what's blocked in Pi-hole web interface", "notes": "Pi-hole must be installed. DNSCrypt integration is automatic - no manual config needed!" }, { "command": "sudo dns-switch pihole-disable", "description": "Disable Pi-hole DNS filtering and stop the service", "expectedOutput": "Pi-hole service stopped and disabled from boot", "notes": "DNSCrypt continues independently if running. Use 'sudo dns-switch pihole-enable' to re-enable." }, { "command": "sudo dns-switch pihole-password --password NewSecurePassword123", "description": "Set Pi-hole web interface password (automatically unprotects TOML file)", "expectedOutput": "Pi-hole admin password updated. Protection restored on service restart.", "notes": "Note: To manually change password, run 'sudo chattr -i /etc/pihole/pihole.toml' first" }, { "command": "sudo dns-switch pihole-reset", "description": "Reset Pi-hole configuration to a clean state", "expectedOutput": "Pi-hole configuration reset", "notes": "Pi-hole must be installed. Use 'pihole-enable' afterwards to re-apply Kodachi's DNSCrypt-upstream integration." } ], "id": "9_dnscrypt_and_pihole", "title": "DNSCrypt & Pi-hole Integration" }, { "description": "Manage the DNS server database, its backups and its cleanup. Only the two restore commands touch system DNS, and only they need root.", "examples": [ { "command": "dns-switch clean", "description": "Remove the temporary and cache files the tool leaves behind", "expectedOutput": "Reports which temporary files were removed", "notes": "Add --no-action to list them without deleting anything." }, { "command": "dns-switch clean-duplicates", "description": "Remove duplicate DNS entries from the database", "expectedOutput": "Reports how many duplicate entries were removed", "notes": "Applies immediately: this command ignores --no-action." }, { "command": "dns-switch flush-cache", "description": "Flush systemd-resolved and nscd DNS caches to clear stale entries", "expectedOutput": "Reports which resolver caches were flushed", "notes": "Clears cached lookups so the next query reaches the configured DNS servers fresh. resolvectl needs no root; the nscd step is skipped when passwordless sudo is unavailable." }, { "command": "dns-switch backup", "description": "Create a timestamped backup of the DNS server database", "expectedOutput": "Path of the new timestamped backup file", "notes": "Backs up the dns-switch database only, NOT /etc/resolv.conf." }, { "command": "dns-switch backup --json", "description": "Create the backup and report the result as JSON", "expectedOutput": "JSON confirmation carrying the backup file path" }, { "command": "dns-switch restore-default --no-action", "description": "Preview a factory reset of the database before committing to it", "expectedOutput": "Shows what would be restored, changes nothing", "notes": "--no-action drops the root requirement, so the preview needs no sudo." }, { "command": "sudo dns-switch restore-default", "description": "Reset the DNS database to factory defaults and apply the default DNS", "expectedOutput": "Database restored to its original state and system DNS updated", "notes": "DESTRUCTIVE: your custom entries and the collected health history are discarded. Take a 'dns-switch backup' first." }, { "command": "sudo dns-switch restore-backup", "description": "Restore the DNS database from the most recent backup", "expectedOutput": "Database restored from the latest backup file", "notes": "DESTRUCTIVE and immediate: it overwrites the current database and has NO dry run (--no-action is ignored). Run 'switch' afterwards to apply servers to the system." }, { "command": "sudo dns-switch restore-backup --file ", "description": "Restore the database from one specific backup file", "expectedOutput": "Database restored from the named backup", "notes": "Replace with a file produced by 'dns-switch backup'. Paths containing '..' are rejected." } ], "id": "10_database_maintenance", "title": "Database Maintenance" }, { "description": "Preview a change before you make it, and get machine-readable output. Only switch, random, fetch, dnscrypt-set, clean and restore-default honour --no-action; on every other command the flag is accepted and ignored, so do NOT trust it as a safety net (fallback, restore-backup and clean-duplicates apply for real regardless). --no-action also drops the root requirement, so previews need no sudo.", "examples": [ { "command": "dns-switch switch --names cloudflare --no-action", "description": "Preview a switch without touching the system DNS", "expectedOutput": "The DNS servers that would be written, with nothing changed" }, { "command": "dns-switch random --type reputable --count 5 --no-action", "description": "Preview a random selection without applying it", "expectedOutput": "The 5 servers that would be selected, with no live probes sent" }, { "command": "dns-switch dnscrypt-set --resolver cloudflare --no-action", "description": "Preview a DNSCrypt resolver change without writing the config", "expectedOutput": "The DNSCrypt configuration that would be applied" }, { "command": "dns-switch clean --no-action", "description": "Preview the temporary-file cleanup without deleting anything", "expectedOutput": "The temporary files that would be removed" }, { "command": "dns-switch status --json --json-pretty", "description": "Get the current DNS status as indented JSON", "expectedOutput": "Pretty-printed JSON with the active nameservers" }, { "command": "dns-switch health --type reputable --json-human", "description": "Get health-check results in the enhanced, colorized JSON format", "expectedOutput": "JSON with jq-style formatting and the per-server metrics" }, { "command": "dns-switch count --json-human", "description": "Get the per-category server counts in enhanced JSON", "expectedOutput": "JSON with the count for each DNS category" } ], "id": "11_dry_run_and_json", "title": "Dry Run & JSON Output" }, { "description": "Manage DNS configuration modes: modern (systemd-resolved) vs legacy (/etc/resolv.conf)", "examples": [ { "command": "dns-switch get-mode", "description": "Check current DNS management mode", "expectedOutput": "Shows: modern (systemd-resolved) or legacy (/etc/resolv.conf)", "notes": "Displays mode health status and any configuration issues" }, { "command": "dns-switch get-mode --json", "description": "Get DNS mode in JSON format", "expectedOutput": "JSON with mode, systemd-resolved status, and health checks", "notes": "Includes resolv.conf symlink status and detected issues" }, { "command": "dns-switch detect-mode", "description": "Auto-detect recommended DNS mode for this system", "expectedOutput": "Recommends modern if systemd-resolved active, legacy otherwise", "notes": "Checks systemd-resolved installation and activity status" }, { "command": "dns-switch detect-mode --json", "description": "Get mode detection results in JSON", "expectedOutput": "JSON with detected mode, current mode, and recommendation" }, { "command": "sudo dns-switch set-mode --mode modern", "description": "Switch to modern mode (systemd-resolved)", "expectedOutput": "Enables systemd-resolved and configures /etc/resolv.conf as symlink", "notes": "Backs up existing resolv.conf, starts systemd-resolved if needed" }, { "command": "sudo dns-switch set-mode --mode legacy", "description": "Switch to legacy mode (/etc/resolv.conf)", "expectedOutput": "Converts /etc/resolv.conf to regular file, preserves current DNS", "notes": "Extracts current DNS from systemd-resolved before switching" }, { "command": "sudo dns-switch fix-dns", "description": "Auto-repair broken DNS configuration", "expectedOutput": "Fixes mode mismatches, broken symlinks, applies fallback DNS", "notes": "Emergency repair command for connectivity issues" }, { "command": "sudo dns-switch fix-dns --force", "description": "Run complete DNS repair sequence regardless of initial health", "expectedOutput": "Executes all repair stages, then validates DNS status", "notes": "Use after unstable DNS incidents or repeated resolver failures" }, { "command": "dns-switch get-modern-method", "description": "Check current systemd-resolved configuration method", "expectedOutput": "Shows: global, per-interface, networkmanager, or auto", "notes": "Only applies when in modern mode (systemd-resolved)" }, { "command": "dns-switch get-modern-method --json", "description": "Get systemd-resolved method in JSON", "expectedOutput": "JSON with method and description" }, { "command": "sudo dns-switch set-modern-method --method global", "description": "Set to global config method (RECOMMENDED)", "expectedOutput": "Configures /etc/systemd/resolved.conf - covers ALL interfaces", "notes": "Safest method - prevents DNS leaks on all network interfaces" }, { "command": "sudo dns-switch set-modern-method --method per-interface", "description": "Set to per-interface method", "expectedOutput": "Uses resolvectl dns - applies per network interface", "notes": "May miss virtual/VPN interfaces - use global method instead" }, { "command": "sudo dns-switch set-modern-method --method networkmanager", "description": "Set to NetworkManager method", "expectedOutput": "Uses nmcli for DNS configuration", "notes": "Only for NetworkManager-managed systems" }, { "command": "sudo dns-switch set-modern-method --method auto", "description": "Set to auto with smart fallback chain", "expectedOutput": "Tries global ā†’ per-interface ā†’ networkmanager automatically", "notes": "Automatically selects best available method" }, { "command": "dns-switch verify-no-leaks", "description": "Check for DNS leaks across all network interfaces", "expectedOutput": "Reports any interfaces with unexpected DNS servers", "notes": "Essential for privacy - detects DNS configuration bypasses" }, { "command": "dns-switch verify-no-leaks --json", "description": "Get DNS leak detection results in JSON", "expectedOutput": "JSON with leaked interfaces list and expected DNS servers", "notes": "Use after switching DNS to verify no leaks occurred" } ], "id": "12_dns_mode_management", "title": "DNS Mode Management (Modern vs Legacy)" }, { "description": "Manage automatic DNS checking and fixing on system boot", "examples": [ { "command": "sudo dns-switch boot-check", "description": "Run the boot-time DNS check by hand: report status and repair empty or invalid nameservers", "expectedOutput": "Reports the DNS status, and writes fallback nameservers when it finds none", "notes": "Read-only while DNS is healthy, but it rewrites /etc/resolv.conf when it has to repair, which is why it needs sudo. Fallback servers come from the configuration, never from hardcoded values." }, { "command": "sudo dns-switch enable-boot-check", "description": "Enable automatic DNS checking on system boot", "expectedOutput": "Creates and enables systemd service for boot-time DNS validation", "notes": "Ensures DNS is always configured correctly after system restart" }, { "command": "sudo dns-switch disable-boot-check", "description": "Disable automatic DNS checking on system boot", "expectedOutput": "Removes systemd service for boot-time DNS validation", "notes": "DNS configuration will not be automatically checked on boot" }, { "command": "systemctl status dns-boot-check.service", "description": "Check status of the boot-check systemd service", "expectedOutput": "Shows if boot-check service is enabled and its last run status", "notes": "Useful for verifying boot-check is working correctly" } ], "id": "13_boot_check_management", "title": "Boot-Time DNS Check Management" }, { "description": "Enable DNSSEC signature validation and DNS-over-HTTPS in dnscrypt-proxy. All four commands are authentication- and root-gated because they edit /etc/dnscrypt-proxy/dnscrypt-proxy.toml and restart the service. The legacy dot-on and dot-off names configure DoH, not DNS-over-TLS.", "examples": [ { "command": "sudo dns-switch dnssec-on", "description": "Enable DNSSEC validation in dnscrypt-proxy.toml; restart dnscrypt-proxy. Earns +0.1 dns_privacy score.", "expectedOutput": "require_dnssec=true; service restarted", "notes": "DNSCrypt-proxy must be installed. Falls back to plain DNS if upstream doesn't sign." }, { "command": "sudo dns-switch dnssec-off", "description": "Disable DNSSEC validation (default state).", "expectedOutput": "require_dnssec=false; service restarted" }, { "command": "sudo dns-switch dot-on", "description": "Enable DNS-over-HTTPS in dnscrypt-proxy.toml; restart service. Earns +0.2 dns_privacy score.", "expectedOutput": "doh_servers=true; service restarted", "notes": "Despite the legacy command name, this selects DoH over HTTPS; it does not configure DNS-over-TLS. On Kodachi the encryption layer is dnscrypt-proxy, not systemd-resolved." }, { "command": "sudo dns-switch dot-off", "description": "Disable DoH; dnscrypt-proxy reverts to DNSCrypt-only protocol.", "expectedOutput": "doh_servers=false; service restarted" } ], "id": "14_dnssec_and_dot", "title": "DNSSEC validation and DNS-over-HTTPS" }, { "description": "Let a third-party VPN GUI manage DNS. Kodachi locks /etc/resolv.conf immutable for DNS-leak protection, which prevents such clients from setting their tunnel DNS: they fail with \"internet blocked\" or \"failed to set system DNS\". Hand DNS to the client before connecting, then take it back when done.", "examples": [ { "command": "sudo dns-switch external-dns --state on", "description": "Unlock /etc/resolv.conf and pause Kodachi DNS protection (immutable lock + boot-check) so the VPN GUI can set its tunnel DNS. Run BEFORE connecting Mullvad/ProtonVPN.", "expectedOutput": "External-DNS mode ENABLED: /etc/resolv.conf unlocked and Kodachi DNS protection paused.", "notes": "While ON, Kodachi's immutable DNS-leak lock is paused, so your VPN client must enforce its own leak protection (Mullvad and ProtonVPN do). Pi-hole cannot be enabled while this is ON." }, { "command": "sudo dns-switch external-dns --state off", "description": "Remove the handover marker and re-apply Kodachi-managed, locked DNS. Disconnect the VPN client first.", "expectedOutput": "External-DNS mode DISABLED: DNS management returned to Kodachi." }, { "command": "dns-switch external-dns --state status", "description": "Show whether a third-party VPN currently owns DNS (read-only; no sudo).", "expectedOutput": "External-DNS mode: ON or OFF, plus which side currently owns DNS" } ], "id": "15_external_vpn_dns", "title": "External VPN DNS handover (Mullvad, ProtonVPN, etc.)" }, { "description": "Version, capabilities, examples, and the per-action help pages.", "examples": [ { "command": "dns-switch --help", "description": "Show every action, grouped by topic, with the global flags", "expectedOutput": "The full command list with usage, options and exit codes" }, { "command": "dns-switch switch --help", "description": "Show the help page for a single action", "expectedOutput": "Usage, options, examples and the sudo requirement for 'switch'", "notes": "Works for any action: ' --help', ' -h' or ' help'." }, { "command": "dns-switch help", "description": "Same as --help, as a positional action", "expectedOutput": "The full command list" }, { "command": "dns-switch --version", "description": "Show the version number", "expectedOutput": "dns-switch " }, { "command": "dns-switch --info --json", "description": "Machine-readable capability record for tooling", "expectedOutput": "JSON with the feature list, security features and system requirements" }, { "command": "dns-switch --examples --json", "description": "All examples as JSON, for docs and automation", "expectedOutput": "JSON with the example categories and the quick reference" } ], "id": "16_program_information", "title": "Program Information & Per-Command Help" } ], "description": "Comprehensive usage examples for dns-switch DNS management", "name": "dns-switch", "quickReference": [ "dns-switch status", "dns-switch verify-no-leaks", "dns-switch health", "dns-switch list --category all --json", "sudo dns-switch switch --category reputable", "sudo dns-switch switch --names cloudflare", "sudo dns-switch random --type reputable --verify", "sudo dns-switch fix-dns", "dns-switch --help", "dns-switch --examples --json" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:19.871548735Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-monitor", "path": "/opt/kodachi/dashboard/hooks/ai-monitor", "timestamp": "2026-07-21T01:54:20Z", "file_info": { "size": 4205584, "sha256": "89d6c242af57bbbf89c73c17f30037146123a7b6ae2cd989d9de6e77232e8f78" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:20.529179317Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-monitor", "version": "9.8.4", "author": "Warith Al Maawali", "description": "Proactive system monitoring daemon with anomaly detection and suggestions", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:20.762566404Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-monitor", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:20.942076359Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-monitor", "description": "Proactive system monitoring daemon with anomaly detection and suggestions", "usage": "ai-monitor [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Monitoring", "commands": [ { "name": "start", "description": "Start the system monitoring daemon", "usage": "ai-monitor start [OPTIONS]", "options": [ { "flag": "-i, --interval ", "description": "How often the monitor re-checks the system, in seconds", "default": "30" }, { "flag": "-s, --threshold ", "description": "Security score (1 to 100) below which the monitor raises an alert", "default": "70" }, { "flag": "-d, --daemon", "description": "Install the systemd unit if missing and run under systemd instead of in this shell. Requires root" }, { "flag": "--json", "description": "Emit the start result as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-monitor start", "ai-monitor start --interval 60", "ai-monitor start --interval 60 --threshold 80", "sudo ai-monitor start --daemon" ] }, { "name": "status", "description": "Show current monitor status and statistics", "usage": "ai-monitor status [--verbose] [--json]", "options": [ { "flag": "--verbose", "description": "Also report database statistics and which monitors (VPN, Tor, DNS, security) are enabled" }, { "flag": "--json", "description": "Emit status, message, is_running, active_suggestions, last_check and config as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-monitor status", "ai-monitor status --verbose", "ai-monitor status --json" ] } ] }, { "category": "Service Management", "commands": [ { "name": "service", "description": "Manage the ai-monitor systemd service lifecycle", "usage": "ai-monitor service ", "options": [ { "flag": "", "description": "install (write the unit file), uninstall (stop, disable and remove it), enable (start at boot), disable (do not start at boot), status (read-only). Everything except status requires root", "required": true }, { "flag": "--force", "description": "With 'install': overwrite a unit file that is not recognized as ai-monitor's own output (e.g. an administrator-customized unit). Ignored by other actions", "default": "false" }, { "flag": "--json", "description": "Emit the action result as a JSON envelope" } ], "requires_sudo": false, "examples": [ "sudo ai-monitor service install", "sudo ai-monitor service install --force", "sudo ai-monitor service enable", "ai-monitor service status", "sudo ai-monitor service disable", "sudo ai-monitor service uninstall" ] } ] }, { "category": "Suggestions", "commands": [ { "name": "suggestions", "description": "List and manage proactive suggestions", "usage": "ai-monitor suggestions [OPTIONS]", "options": [ { "flag": "-c, --category ", "description": "Show only one category: security, network, recovery or optimization", "default": "all categories" }, { "flag": "-r, --resolve ", "description": "Mark the suggestion with this ID as resolved. Write operation, needs a prior online-auth login" }, { "flag": "-d, --dismiss ", "description": "Mark the suggestion with this ID as dismissed. Write operation, needs a prior online-auth login" }, { "flag": "--cleanup", "description": "Delete old inactive suggestions from the database. Write operation, needs a prior online-auth login" }, { "flag": "--json", "description": "Emit the suggestion list or the write result as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-monitor suggestions", "ai-monitor suggestions --json", "ai-monitor suggestions --category security", "ai-monitor suggestions --resolve 1", "ai-monitor suggestions --dismiss 2", "ai-monitor suggestions --cleanup" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format ", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter ", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields ", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit ", "description": "Limit number of results returned" }, { "flag": "--offset ", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir ", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port ", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level ", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "2": "Invalid arguments", "1": "General error", "3": "Permission denied", "0": "Success", "5": "File not found", "4": "Network error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:21.328242510Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-monitor", "description": "Usage examples for ai-monitor", "categories": [ { "id": "1_basic", "title": "Basic Usage", "description": "Look at what the monitor currently knows: is it running, and what has it suggested.", "examples": [ { "command": "ai-monitor status", "description": "Show whether the monitor is running and how many suggestions are open", "expectedOutput": "'Monitor Status: running' or 'stopped', then active suggestions, last check, check interval and security threshold" }, { "command": "ai-monitor status --json", "description": "Same status as a JSON envelope for the dashboard or a script", "expectedOutput": "Envelope with status, message, is_running, active_suggestions, last_check and config{check_interval_seconds, security_threshold}" }, { "command": "ai-monitor status --verbose", "description": "Add the SQLite database stats and which monitors are enabled", "expectedOutput": "The plain status block plus a Database section (total size, pages) and a Monitoring section (VPN, Tor, DNS, Security enabled or disabled)", "notes": "--verbose adds database{page_count, page_size, freelist_count, total_size_bytes, unused_bytes} and monitoring{vpn_enabled, tor_enabled, dns_enabled, security_enabled} to the JSON form." }, { "command": "ai-monitor suggestions", "description": "List every open proactive suggestion", "expectedOutput": "One line per active suggestion with its ID, category and message, or a note that there are none" }, { "command": "ai-monitor suggestions --json", "description": "List open suggestions as JSON", "expectedOutput": "Envelope with the suggestion array and its metadata" }, { "command": "ai-monitor start", "description": "Run the monitoring loop in this terminal (not as a service)", "expectedOutput": "The monitor starts with a 30 second interval and a security threshold of 70, then keeps checking until you stop it", "notes": "Foreground run. Use `service` or `start --daemon` if you want it to survive the shell." } ] }, { "id": "2_advanced", "title": "Tuning the Monitor", "description": "Change how often the monitor checks the system and how low the security score has to drop before it raises an alert.", "examples": [ { "command": "ai-monitor start --interval 60 --threshold 80", "description": "Check every 60 seconds and alert below a security score of 80", "expectedOutput": "The monitor starts and reports the interval and threshold it is using", "notes": "--interval is in seconds (default 30). --threshold is a security score of 1 to 100 (default 70). Short forms are -i and -s." }, { "command": "ai-monitor start --interval 60 --threshold 80 --json", "description": "Start a tuned foreground monitor and capture the config as JSON", "expectedOutput": "Envelope echoing the interval and security threshold actually applied" }, { "command": "ai-monitor suggestions --category security", "description": "Only look at security suggestions", "expectedOutput": "The active suggestions whose category is security", "notes": "--category accepts exactly: security, network, recovery, optimization. Anything else is rejected by clap." }, { "command": "ai-monitor suggestions --category network", "description": "Only look at network suggestions", "expectedOutput": "The active suggestions whose category is network" }, { "command": "ai-monitor suggestions --category security --json", "description": "Filtered suggestions as JSON for automation", "expectedOutput": "Envelope with only the security-category suggestions" } ] }, { "id": "3_service", "title": "Service Management", "description": "Run the monitor as a systemd unit so it survives logout and reboot. The unit file is generated at install time with the real binary path.", "examples": [ { "command": "sudo ai-monitor start --daemon", "description": "Install the unit if needed and start the monitor under systemd", "expectedOutput": "The service is installed (first run only), started, and confirmed active", "notes": "Needs root: it writes the unit file and calls systemctl. Without sudo it fails with 'This operation requires root privileges.'" }, { "command": "sudo ai-monitor service install", "description": "Only write the systemd unit file, do not start it", "expectedOutput": "Service installed successfully", "notes": "Needs root." }, { "command": "sudo ai-monitor service enable", "description": "Start the monitor automatically on every boot", "expectedOutput": "Service enabled successfully", "notes": "Needs root. Install the service first, enable only creates the boot link." }, { "command": "sudo ai-monitor service disable", "description": "Stop the monitor from starting at boot, leave it installed", "expectedOutput": "Service disabled successfully", "notes": "Needs root. A currently running instance keeps running until it is stopped." }, { "command": "ai-monitor service status", "description": "Check whether the service is installed, active and enabled", "expectedOutput": "installed true or false, plus the systemd active and enabled state and MainPID, ActiveEnterTimestamp, MemoryCurrent", "notes": "The only service action that does not need root." }, { "command": "ai-monitor service status --json", "description": "Service state as JSON for the dashboard", "expectedOutput": "Envelope with installed, active, enabled and a properties map" }, { "command": "sudo ai-monitor service uninstall", "description": "Stop, disable and delete the systemd unit", "expectedOutput": "Service uninstalled successfully", "notes": "Needs root. Destructive: the unit file is removed and the monitor stops running at boot. Collected suggestions in the database are not touched." } ] }, { "id": "4_maintenance", "title": "Suggestion Maintenance", "description": "Act on suggestions: resolve one you have fixed, dismiss one you do not care about, or prune the old inactive ones.", "examples": [ { "command": "ai-monitor suggestions --resolve 1", "description": "Mark suggestion 1 as resolved because you acted on it", "expectedOutput": "Suggestion 1 is marked resolved and drops out of the active list", "notes": "Write operation: requires a prior `online-auth` login, otherwise it exits with 'Authentication required. Please authenticate using online-auth first'. The ID comes from `ai-monitor suggestions`." }, { "command": "ai-monitor suggestions --dismiss 2", "description": "Dismiss suggestion 2 without claiming you fixed anything", "expectedOutput": "Suggestion 2 is marked dismissed and drops out of the active list", "notes": "Write operation: requires a prior `online-auth` login." }, { "command": "ai-monitor suggestions --cleanup", "description": "Delete old inactive suggestions from the database", "expectedOutput": "The number of cleaned up suggestions", "notes": "Write operation: requires a prior `online-auth` login. Irreversible: the pruned rows are deleted from the local database." }, { "command": "ai-monitor suggestions --category optimization", "description": "Review the optimization suggestions before acting on them", "expectedOutput": "The active suggestions whose category is optimization" }, { "command": "ai-monitor suggestions --category recovery", "description": "Review the recovery suggestions", "expectedOutput": "The active suggestions whose category is recovery" } ] } ], "quickReference": [ "ai-monitor --help", "ai-monitor --version", "ai-monitor --info --json", "ai-monitor --examples", "ai-monitor status", "ai-monitor suggestions", "ai-monitor service status", "sudo ai-monitor start --daemon" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "health-control", "path": "/opt/kodachi/dashboard/hooks/health-control", "timestamp": "2026-07-21T01:54:21Z", "file_info": { "size": 15974784, "sha256": "e426f4e53b4d14bdc78bf300dc21c1fac20804d3f63d1c0483b97a3f4a863b8f" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi", "description": "Health control system for Kodachi that includes network connectivity checks and system health monitoring", "features": [ "Network connectivity monitoring", "Internet traffic control", "Security hardening", "System integrity checking", "Offline system management" ], "license": "Proprietary", "name": "health-control", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 25, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:21.987989233Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "health-control", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 23, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:22.115215458Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Data Destruction", "commands": [ { "description": "Securely wipe a file with multiple passes", "examples": [ "sudo health-control wipe-file --file /path/to/file.txt", "sudo health-control wipe-file --file /path/to/file.txt --passes 7 --json" ], "name": "wipe-file", "options": [ { "description": "Path to file to wipe", "flag": "--file ", "required": true }, { "default": "3", "description": "Number of wipe passes", "flag": "--passes " } ], "requires_sudo": true, "usage": "health-control wipe-file [OPTIONS]" }, { "description": "Securely wipe an entire directory and its contents", "examples": [ "sudo health-control wipe-directory --path /tmp/sensitive_dir", "sudo health-control wipe-directory --path /path/to/directory --passes 7 --json" ], "name": "wipe-directory", "options": [ { "description": "Directory path to wipe", "flag": "--path ", "required": true }, { "default": "3", "description": "Number of wipe passes", "flag": "--passes " } ], "requires_sudo": true, "usage": "health-control wipe-directory [OPTIONS]" }, { "description": "Securely wipe a common user directory (downloads, desktop, documents)", "examples": [ "sudo health-control wipe-user-dir --target downloads", "sudo health-control wipe-user-dir --target desktop", "sudo health-control wipe-user-dir --target documents --json" ], "name": "wipe-user-dir", "options": [ { "description": "Directory target to wipe", "flag": "--target ", "required": true } ], "requires_sudo": true, "usage": "health-control wipe-user-dir [OPTIONS]" }, { "description": "Securely wipe system logs (journal, syslog, auth.log, kern.log), user history (bash, zsh, python), and application cache logs", "examples": [ "sudo health-control wipe-logs # Wipe all logs (system + user)", "sudo health-control wipe-logs --type system # Wipe only system logs (/var/log/*, journal)", "sudo health-control wipe-logs --type user # Wipe only user logs (history, cache)", "sudo health-control wipe-logs --type all --json # Show detailed JSON output" ], "name": "wipe-logs", "options": [ { "default": "all", "description": "Log type: system, user, all", "flag": "--type " } ], "requires_sudo": true, "usage": "health-control wipe-logs [OPTIONS]" }, { "description": "Batch wipe multiple files", "examples": [ "sudo # Multiple file paths as arguments:", "sudo health-control wipe-batch file1.png file2.png --passes 7", "sudo health-control wipe-batch /tmp/sensitive.doc /home/user/data.txt", "sudo ", "sudo # Alternative comma-separated format:", "sudo health-control wipe-batch --paths \"file1.png,file2.png\" --passes 7", "sudo health-control wipe-batch --paths \"/tmp/file1,/tmp/file2\" --json", "sudo ", "sudo āš  Security Note: Using actual paths may expose system directory structure" ], "name": "wipe-batch", "options": [ { "description": "Comma-separated paths to wipe (alternative to positional arguments)", "flag": "--paths " }, { "description": "Files to wipe (can specify multiple)", "flag": "" }, { "default": "3", "description": "Number of wipe passes", "flag": "-p, --passes " } ], "requires_sudo": true, "usage": "health-control wipe-batch [OPTIONS]" }, { "description": "Wipe browser data and history", "examples": [ "sudo health-control wipe-browser-data # Wipe all browsers", "sudo health-control wipe-browser-data --browser firefox # Firefox only", "sudo health-control wipe-browser-data --browser brave # Brave only", "sudo health-control wipe-browser-data --browser tor # Tor Browser only", "sudo health-control wipe-browser-data --browser all --json" ], "name": "wipe-browser-data", "options": [ { "default": "all", "description": "Browser: firefox, chrome, chromium, brave, edge, opera, vivaldi, tor, librewolf, waterfox, falkon, epiphany, konqueror, midori, palemoon, seamonkey, qutebrowser, min, nyxt, or 'all' (default)", "flag": "--browser " } ], "requires_sudo": true, "usage": "health-control wipe-browser-data [OPTIONS]" }, { "description": "Securely wipe free space on a mounted filesystem (use mount points like '/', '/home' or device paths)", "examples": [ "sudo health-control wipe-free-space --device /", "sudo health-control wipe-free-space --device /home", "sudo health-control wipe-free-space --device /dev/DEVICE --json", "sudo health-control wipe-free-space --device /tmp" ], "name": "wipe-free-space", "options": [ { "description": "Mount point (e.g., '/', '/home', '/tmp') or device (e.g., '/dev/DEVICE')", "flag": "--device ", "required": true } ], "requires_sudo": true, "usage": "health-control wipe-free-space [OPTIONS]" }, { "description": "Wipe files matching pattern (use --pattern flag or positional argument)", "examples": [ "sudo health-control wipe-pattern --pattern '*.tmp'", "sudo health-control wipe-pattern '*.tmp'", "sudo health-control wipe-pattern --pattern '*.log' --directory /var/log", "sudo health-control wipe-pattern '*.log' --directory /var/log", "sudo health-control wipe-pattern --pattern 'backup*' --json", "sudo health-control wipe-pattern 'backup*' --json", "sudo health-control wipe-pattern --pattern '*.cache' --directory ~/.cache", "sudo health-control wipe-pattern '*.cache' --directory ~/.cache" ], "name": "wipe-pattern", "options": [ { "description": "File pattern to match (e.g., '*.tmp', '*.log') - use quotes for shell patterns", "flag": "" }, { "description": "File pattern to match (e.g., '*.tmp', '*.log') - use quotes for shell patterns", "flag": "--pattern " }, { "default": ".", "description": "Directory to search in", "flag": "--directory " } ], "requires_sudo": true, "usage": "health-control wipe-pattern [OPTIONS]" }, { "description": "Schedule automatic data wiping", "examples": [ "sudo health-control wipe-schedule temp --frequency daily", "sudo health-control wipe-schedule logs --frequency weekly", "sudo health-control wipe-schedule browser --json" ], "name": "wipe-schedule", "options": [ { "description": "Target: temp, logs, cache, browser", "flag": "", "required": true }, { "default": "weekly", "description": "Frequency: daily, weekly, monthly", "flag": "--frequency " } ], "requires_sudo": true, "usage": "health-control wipe-schedule [OPTIONS]" }, { "description": "Verify that a file was wiped properly", "examples": [ "sudo health-control wipe-verify --path /tmp/sensitive.txt", "sudo health-control wipe-verify --path /home/user/data.bin --json" ], "name": "wipe-verify", "options": [ { "description": "Path to verify", "flag": "--path ", "required": true } ], "requires_sudo": true, "usage": "health-control wipe-verify [OPTIONS]" } ] }, { "category": "Display & Power", "commands": [ { "description": "Start Conky widget", "examples": [ "health-control conky-enable", "health-control conky-enable --json" ], "name": "conky-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-enable [OPTIONS]" }, { "description": "Stop Conky widget", "examples": [ "health-control conky-disable", "health-control conky-disable --json" ], "name": "conky-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-disable [OPTIONS]" }, { "description": "Check Conky running/installed/boot state", "examples": [ "health-control conky-status", "health-control conky-status --json" ], "name": "conky-status", "options": [], "requires_sudo": false, "usage": "health-control conky-status [OPTIONS]" }, { "description": "Enable Conky on boot (autostart/systemd)", "examples": [ "health-control conky-boot-enable", "health-control conky-boot-enable --json" ], "name": "conky-boot-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-boot-enable [OPTIONS]" }, { "description": "Disable Conky on boot", "examples": [ "health-control conky-boot-disable", "health-control conky-boot-disable --json" ], "name": "conky-boot-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-boot-disable [OPTIONS]" }, { "description": "Disable XFCE screensaver", "examples": [ "health-control screensaver-disable", "health-control screensaver-disable --json" ], "name": "screensaver-disable", "options": [], "requires_sudo": false, "usage": "health-control screensaver-disable [OPTIONS]" }, { "description": "Enable XFCE screensaver", "examples": [ "health-control screensaver-enable", "health-control screensaver-enable --json" ], "name": "screensaver-enable", "options": [], "requires_sudo": false, "usage": "health-control screensaver-enable [OPTIONS]" }, { "description": "Check screensaver status", "examples": [ "health-control screensaver-status", "health-control screensaver-status --json" ], "name": "screensaver-status", "options": [], "requires_sudo": false, "usage": "health-control screensaver-status [OPTIONS]" }, { "description": "Disable display power management", "examples": [ "health-control dpms-disable", "health-control dpms-disable --json" ], "name": "dpms-disable", "options": [], "requires_sudo": false, "usage": "health-control dpms-disable [OPTIONS]" }, { "description": "Enable display power management", "examples": [ "health-control dpms-enable", "health-control dpms-enable --json" ], "name": "dpms-enable", "options": [], "requires_sudo": false, "usage": "health-control dpms-enable [OPTIONS]" }, { "description": "Check DPMS and timeout settings", "examples": [ "health-control dpms-status", "health-control dpms-status --json" ], "name": "dpms-status", "options": [], "requires_sudo": false, "usage": "health-control dpms-status [OPTIONS]" }, { "description": "Lock the screen", "examples": [ "health-control lock-screen", "health-control lock-screen --json" ], "name": "lock-screen", "options": [], "requires_sudo": false, "usage": "health-control lock-screen [OPTIONS]" }, { "description": "End XFCE session", "examples": [ "health-control session-logout", "health-control session-logout --json" ], "name": "session-logout", "options": [], "requires_sudo": false, "usage": "health-control session-logout [OPTIONS]" }, { "description": "Suspend to RAM", "examples": [ "health-control suspend", "health-control suspend --json" ], "name": "suspend", "options": [], "requires_sudo": false, "usage": "health-control suspend [OPTIONS]" }, { "description": "Mask sensitive info in Conky panels", "examples": [ "health-control conky-mask-enable", "health-control conky-mask-enable --json" ], "name": "conky-mask-enable", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-enable [OPTIONS]" }, { "description": "Unmask Conky panels", "examples": [ "health-control conky-mask-disable", "health-control conky-mask-disable --json" ], "name": "conky-mask-disable", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-disable [OPTIONS]" }, { "description": "Check if Conky privacy masking is active", "examples": [ "health-control conky-mask-status", "health-control conky-mask-status --json" ], "name": "conky-mask-status", "options": [], "requires_sudo": false, "usage": "health-control conky-mask-status [OPTIONS]" } ] }, { "category": "Emergency Operations", "commands": [ { "description": "Arm the emergency kill switch - sets system to high-alert state for manual activation. NOTE: This prepares the system for rapid response but does NOT actively monitor for threats. It's a preparedness state that allows quick manual activation via kill-switch-activate command.", "examples": [ "sudo health-control kill-switch-arm", "sudo health-control kill-switch-arm --json" ], "name": "kill-switch-arm", "options": [], "requires_sudo": true, "usage": "health-control kill-switch-arm [OPTIONS]" }, { "description": "Disarm the emergency kill switch", "examples": [ "sudo health-control kill-switch-disarm", "sudo health-control kill-switch-disarm --json" ], "name": "kill-switch-disarm", "options": [], "requires_sudo": true, "usage": "health-control kill-switch-disarm [OPTIONS]" }, { "description": "Check whether the kill switch high-alert flag is armed/disarmed. Shows armed time and trigger count. Arming is a state flag, not a monitor: nothing is watching and nothing auto-fires. Does NOT activate anything - just displays current status.", "examples": [ "health-control kill-switch-status", "health-control kill-switch-status --json" ], "name": "kill-switch-status", "options": [], "requires_sudo": false, "usage": "health-control kill-switch-status [OPTIONS]" }, { "description": "IMMEDIATELY activate emergency procedures. Unlike 'arm' (which only raises a high-alert flag and monitors nothing), this executes panic mode NOW. Choose level: soft (network+lock), medium (default: +kill processes), hard (+RAM wipe+shutdown)", "examples": [ "sudo health-control kill-switch-activate", "sudo health-control kill-switch-activate --level hard --force", "sudo health-control kill-switch-activate --level soft --json", "sudo health-control kill-switch-activate --dry-run --json" ], "name": "kill-switch-activate", "options": [ { "default": "medium", "description": "Panic level: soft, medium, hard", "flag": "--level " }, { "description": "Force activation without confirmation", "flag": "--force" }, { "description": "Test mode - shows what actions would be taken without executing", "flag": "--dry-run" } ], "requires_sudo": true, "usage": "health-control kill-switch-activate [OPTIONS]" }, { "description": "IMMEDIATE soft panic mode. Actions: Kill all network connections, clear clipboard, lock screen. NO CONFIRMATION. Reversible by restarting network. Use for quick privacy protection.", "examples": [ "sudo health-control panic-soft", "sudo health-control panic-soft --json", "sudo health-control panic-soft --dry-run" ], "name": "panic-soft", "options": [ { "description": "Test mode - shows what actions would be taken without executing", "flag": "--dry-run" } ], "requires_sudo": true, "usage": "health-control panic-soft [OPTIONS]" }, { "description": "IMMEDIATE hard panic mode with CONFIRMATION. CRITICAL: Kill network, clear clipboard, terminate ALL processes, clear memory, unmount devices, wipe RAM, IMMEDIATE SHUTDOWN. IRREVERSIBLE - system will shutdown!", "examples": [ "sudo health-control panic-hard", "sudo health-control panic-hard --json", "sudo health-control panic-hard --dry-run" ], "name": "panic-hard", "options": [ { "description": "Test mode - shows what actions would be taken without executing", "flag": "--dry-run" } ], "requires_sudo": true, "usage": "health-control panic-hard [OPTIONS]" }, { "description": "IMMEDIATE medium panic mode with CONFIRMATION. Actions: Kill network, clear clipboard, terminate non-essential processes, clear memory, unmount devices, lock screen. Requires manual system restart to fully restore.", "examples": [ "sudo health-control panic-medium", "sudo health-control panic-medium --json", "sudo health-control panic-medium --dry-run" ], "name": "panic-medium", "options": [ { "description": "Test mode - shows what actions would be taken without executing", "flag": "--dry-run" } ], "requires_sudo": true, "usage": "health-control panic-medium [OPTIONS]" }, { "description": "Configure automated emergency response profile that defines system actions during panic mode activation", "examples": [ "sudo # Configure light security response (recommended for public wifi):", "sudo health-control panic-profile --profile stealth", "sudo ", "sudo # Configure maximum security lockdown (for high-risk situations):", "sudo health-control panic-profile --profile paranoid", "sudo ", "sudo # Configure recovery mode (to restore system to safe state):", "sudo health-control panic-profile --profile recovery", "sudo ", "sudo # Get JSON output with profile configuration details:", "sudo health-control panic-profile --profile paranoid --json" ], "name": "panic-profile", "options": [ { "description": "Emergency response profile to configure:\n stealth - Light security response: minimal network blocking, clear cache, lock screen\n paranoid - Maximum security response: full network isolation, memory wipe, system lockdown\n recovery - Safe restoration mode: create recovery point, restart essential services", "flag": "--profile ", "required": true } ], "requires_sudo": true, "usage": "health-control panic-profile [OPTIONS]" }, { "description": "Activate panic recovery mode", "examples": [ "sudo health-control panic-recover", "sudo health-control panic-recover --json" ], "name": "panic-recover", "options": [], "requires_sudo": true, "usage": "health-control panic-recover [OPTIONS]" }, { "description": "Create system recovery checkpoint", "examples": [ "sudo health-control create-recovery-point", "sudo health-control create-recovery-point --name pre-update", "sudo health-control create-recovery-point --json" ], "name": "create-recovery-point", "options": [ { "description": "Recovery point name", "flag": "--name " } ], "requires_sudo": true, "usage": "health-control create-recovery-point [OPTIONS]" }, { "description": "Execute emergency data destruction sequence (DANGEROUS - use --dry-run for testing)", "examples": [ "health-control nuke-execute --dry-run", "health-control nuke-execute --method fast --dry-run", "health-control nuke-execute --method paranoid --dry-run --json" ], "name": "nuke-execute", "options": [ { "default": "secure", "description": "Wipe method: fast, secure (default), paranoid", "flag": "--method, -m ", "required": false }, { "description": "Test mode - shows actions without executing", "flag": "--dry-run", "required": false }, { "description": "Skip confirmation prompt (DANGEROUS)", "flag": "--force, -f", "required": false } ], "requires_sudo": false, "usage": "health-control nuke-execute [--method fast|secure|paranoid] [--dry-run] [--force]" }, { "description": "Get current nuke mode execution progress", "examples": [ "health-control nuke-progress", "health-control nuke-progress --json" ], "name": "nuke-progress", "options": [], "requires_sudo": false, "usage": "health-control nuke-progress" }, { "description": "Detect storage type (SSD/HDD/NVMe) for a device", "examples": [ "health-control nuke-storage-detect --device /dev/DEVICE", "health-control nuke-storage-detect -d /dev/DEVICE --json" ], "name": "nuke-storage-detect", "options": [ { "description": "Device path to check", "flag": "--device, -d ", "required": true } ], "requires_sudo": false, "usage": "health-control nuke-storage-detect --device /dev/DEVICE" } ] }, { "category": "Emergency Shortcuts", "commands": [ { "description": "Execute an emergency plan (dashboard, luks, both). Requires local session token from kodachi-session-helper daemon. Use --dry-run for testing.", "examples": [ "sudo health-control emergency-trigger --plan dashboard --dry-run", "sudo health-control emergency-trigger --plan luks --device /dev/DEVICE --dry-run", "sudo health-control emergency-trigger --plan both --device /dev/DEVICE --dry-run --json" ], "name": "emergency-trigger", "options": [ { "description": "Emergency plan: dashboard, luks, both", "flag": "--plan ", "required": true }, { "description": "LUKS device path (required for luks/both plans)", "flag": "--device ", "required": false }, { "description": "Log planned actions without executing", "flag": "--dry-run", "required": false }, { "description": "Suppress stdout output", "flag": "--silent", "required": false }, { "description": "Skip readiness checks", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "health-control emergency-trigger --plan [--device ] [--silent] [--force] [--dry-run]" }, { "description": "Start a delayed countdown that triggers an emergency plan when the timer expires. Persists state for crash recovery. Requires local session token.", "examples": [ "sudo health-control emergency-lockdown --delay 300 --dry-run", "sudo health-control emergency-lockdown --delay 60 --plan luks --device /dev/DEVICE", "sudo health-control emergency-lockdown --delay 120 --plan both --device /dev/DEVICE --json" ], "name": "emergency-lockdown", "options": [ { "description": "Countdown delay in seconds", "flag": "--delay ", "required": true }, { "default": "dashboard", "description": "Emergency plan: dashboard (default), luks, both", "flag": "--plan ", "required": false }, { "description": "LUKS device path (required for luks/both plans)", "flag": "--device ", "required": false }, { "description": "Log planned actions without starting timer", "flag": "--dry-run", "required": false } ], "requires_sudo": true, "usage": "health-control emergency-lockdown --delay [--plan ] [--device ] [--dry-run]" }, { "description": "Show current emergency lockdown state: active/inactive, remaining seconds, plan. No authentication required (read-only).", "examples": [ "health-control emergency-lockdown-status", "health-control emergency-lockdown-status --json" ], "name": "emergency-lockdown-status", "options": [], "requires_sudo": false, "usage": "health-control emergency-lockdown-status [--json]" }, { "description": "Cancel an active emergency lockdown countdown. Requires local session token.", "examples": [ "sudo health-control emergency-lockdown-cancel", "sudo health-control emergency-lockdown-cancel --json" ], "name": "emergency-lockdown-cancel", "options": [], "requires_sudo": true, "usage": "health-control emergency-lockdown-cancel" } ] }, { "category": "Hardware Security", "commands": [ { "description": "Verify hardware random number generator status", "examples": [ "sudo health-control hardware-rng-verify", "sudo health-control hardware-rng-verify --json" ], "name": "hardware-rng-verify", "options": [], "requires_sudo": true, "usage": "health-control hardware-rng-verify [OPTIONS]" }, { "description": "Check system entropy pool status and quality", "examples": [ "sudo health-control entropy-status", "sudo health-control entropy-status --json" ], "name": "entropy-status", "options": [], "requires_sudo": true, "usage": "health-control entropy-status [OPTIONS]" }, { "description": "Enable cold boot defense mechanisms", "examples": [ "sudo health-control coldboot-defense-enable", "sudo health-control coldboot-defense-enable --json" ], "name": "coldboot-defense-enable", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-enable [OPTIONS]" }, { "description": "Disable cold boot defense mechanisms", "examples": [ "sudo health-control coldboot-defense-disable", "sudo health-control coldboot-defense-disable --json", "sudo health-control coldboot-defense-disable --json-human" ], "name": "coldboot-defense-disable", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-disable [OPTIONS]" }, { "description": "Check cold boot defense mechanisms status", "examples": [ "sudo health-control coldboot-defense-status", "sudo health-control coldboot-defense-status --json" ], "name": "coldboot-defense-status", "options": [], "requires_sudo": true, "usage": "health-control coldboot-defense-status [OPTIONS]" }, { "description": "Check boot chain integrity and security status", "examples": [ "sudo health-control boot-integrity-check", "sudo health-control boot-integrity-check --json" ], "name": "boot-integrity-check", "options": [], "requires_sudo": true, "usage": "health-control boot-integrity-check [OPTIONS]" } ] }, { "category": "Hostname Management", "commands": [ { "description": "Set the default hostname", "examples": [ "sudo health-control set-default-hostname", "sudo health-control set-default-hostname --json" ], "name": "set-default-hostname", "options": [], "requires_sudo": true, "usage": "health-control set-default-hostname [OPTIONS]" }, { "description": "Set a random hostname", "examples": [ "sudo health-control set-random-hostname", "sudo health-control set-random-hostname --json" ], "name": "set-random-hostname", "options": [], "requires_sudo": true, "usage": "health-control set-random-hostname [OPTIONS]" }, { "description": "Set a custom hostname", "examples": [ "sudo health-control set-custom-hostname --name MyHost", "sudo health-control set-custom-hostname --name secure-host --json" ], "name": "set-custom-hostname", "options": [ { "description": "Custom hostname to set", "flag": "--name ", "required": true } ], "requires_sudo": true, "usage": "health-control set-custom-hostname [OPTIONS]" } ] }, { "category": "Internet Traffic Control", "commands": [ { "description": "Block all internet traffic", "examples": [ "sudo health-control block-internet", "sudo health-control block-internet --method firewall", "sudo health-control block-internet --method ufw", "sudo health-control block-internet --method iptables", "sudo health-control block-internet --method nftables", "sudo health-control block-internet --method interfaces", "sudo health-control block-internet --method all", "sudo health-control block-internet --allow-local", "sudo health-control block-internet --method iptables --allow-local", "sudo health-control block-internet --method all --allow-local", "sudo health-control block-internet --json" ], "name": "block-internet", "options": [ { "default": "auto", "description": "Block method: firewall/ufw (UFW), iptables, nftables, interfaces, auto, all", "flag": "--method " }, { "description": "Allow local network traffic (LAN)", "flag": "--allow-local" }, { "description": "Skip the iptables rollback-backup safety gate and proceed with firewall mutation even if the backup could not be created. WARNING: without a backup the firewall state cannot be restored via unblock-internet. Use only in automated emergency scenarios where backup storage is unavailable.", "flag": "--force-no-backup" } ], "requires_sudo": true, "usage": "health-control block-internet [OPTIONS]" }, { "description": "Unblock internet traffic", "examples": [ "sudo health-control unblock-internet", "sudo health-control unblock-internet --method firewall", "sudo health-control unblock-internet --method ufw", "sudo health-control unblock-internet --method iptables", "sudo health-control unblock-internet --method nftables", "sudo health-control unblock-internet --method interfaces", "sudo health-control unblock-internet --method all", "sudo health-control unblock-internet --json" ], "name": "unblock-internet", "options": [ { "default": "auto", "description": "Unblock method: firewall/ufw (UFW), iptables, nftables, interfaces, auto, all", "flag": "--method " } ], "requires_sudo": true, "usage": "health-control unblock-internet [OPTIONS]" }, { "description": "Block outbound ICMP echo-requests (ping) via iptables and ip6tables", "examples": [ "sudo health-control block-ping", "sudo health-control block-ping --family ipv4", "sudo health-control block-ping --family ipv6", "sudo health-control block-ping --json" ], "name": "block-ping", "options": [ { "default": "all", "description": "Address family to act on: all (default), ipv4, ipv6", "flag": "--family " } ], "requires_sudo": true, "usage": "health-control block-ping [OPTIONS]" }, { "description": "Unblock outbound ICMP echo-requests (ping), remove the DROP rules", "examples": [ "sudo health-control unblock-ping", "sudo health-control unblock-ping --family ipv4", "sudo health-control unblock-ping --family ipv6", "sudo health-control unblock-ping --json" ], "name": "unblock-ping", "options": [ { "default": "all", "description": "Address family to act on: all (default), ipv4, ipv6", "flag": "--family " } ], "requires_sudo": true, "usage": "health-control unblock-ping [OPTIONS]" }, { "description": "Check internet blocking status", "examples": [ "sudo health-control internet-status", "sudo health-control internet-status --silent", "sudo health-control internet-status --json" ], "name": "internet-status", "options": [ { "description": "Force quick recovery even if connectivity appears healthy", "flag": "--force" }, { "description": "Disable terminal and desktop notifications", "flag": "--silent" } ], "requires_sudo": true, "usage": "health-control internet-status [OPTIONS]" }, { "description": "Recover internet connectivity", "examples": [ "sudo health-control recover-internet", "sudo health-control recover-internet --check-dns", "sudo health-control recover-internet --force", "sudo health-control recover-internet --check-dns --force", "sudo health-control recover-internet --silent", "sudo health-control recover-internet --json" ], "name": "recover-internet", "options": [ { "description": "Check DNS resolution after recovery", "flag": "--check-dns" }, { "description": "Force recovery even if connectivity appears working", "flag": "--force" }, { "description": "Disable terminal and desktop notifications", "flag": "--silent" } ], "requires_sudo": true, "usage": "health-control recover-internet [OPTIONS]" }, { "description": "Fast internet recovery - bounce interface, restart NetworkManager, renew DHCP", "examples": [ "sudo health-control fast-recover-internet", "sudo health-control fast-recover-internet --force", "sudo health-control fast-recover-internet --force --silent", "sudo health-control fast-recover-internet --silent", "sudo health-control fast-recover-internet --json" ], "name": "fast-recover-internet", "options": [ { "description": "Force quick recovery even when connectivity appears healthy", "flag": "--force" }, { "description": "Disable terminal and desktop notifications", "flag": "--silent" } ], "requires_sudo": true, "usage": "health-control fast-recover-internet [OPTIONS]" }, { "description": "Emergency network kill switch", "examples": [ "sudo health-control kill-network", "sudo health-control kill-network --json" ], "name": "kill-network", "options": [], "requires_sudo": true, "usage": "health-control kill-network [OPTIONS]" }, { "description": "Kill specific network interface", "examples": [ "sudo health-control kill-network-interface --interface wlan0", "sudo health-control kill-network-interface --interface eth0 --json" ], "name": "kill-network-interface", "options": [ { "description": "Network interface to kill", "flag": "--interface ", "required": true } ], "requires_sudo": true, "usage": "health-control kill-network-interface [OPTIONS]" }, { "description": "Kill specific process by name or PID", "examples": [ "sudo health-control kill-process --process firefox", "sudo health-control kill-process --process 1234 --json" ], "name": "kill-process", "options": [ { "description": "Process name or PID", "flag": "--process ", "required": true } ], "requires_sudo": true, "usage": "health-control kill-process [OPTIONS]" }, { "description": "Enable a watch-guard to monitor system changes and block internet on triggers", "examples": [ "sudo health-control enable --type watch-guard --watch ip --method nftables", "sudo health-control enable --type watch-guard --watch timezone --method iptables", "sudo health-control enable --type watch-guard --watch timezone --method iptables --daemon", "sudo health-control enable --type watch-guard --watch interfaces --method firewall", "sudo health-control enable --type watch-guard --watch process --target tor --method all", "sudo health-control enable --type watch-guard --watch process --target firefox --method auto", "sudo health-control enable --type watch-guard --watch mac --method nftables --interval 5", "sudo health-control enable --type watch-guard --watch hostname --method iptables", "sudo health-control enable --type watch-guard --watch vpn --method nftables --interval 3", "sudo health-control enable --type watch-guard --watch dns --method firewall", "sudo health-control enable --type watch-guard --watch mac --method nftables --actions log_event,randomize_hostname", "sudo health-control enable --type watch-guard --watch vpn --method nftables --actions log_event,show_alert,block_network" ], "name": "enable", "options": [ { "description": "Type of watch-guard to enable", "flag": "--type", "required": true }, { "description": "What to watch for changes (vpn, dns, ip, mac, hostname, timezone, interfaces, process). vpn = cut the internet if the VPN tunnel drops", "flag": "--watch", "required": true }, { "description": "Process name to watch (required for process watch)", "flag": "--target", "required": false }, { "description": "Blocking method to use when triggered", "flag": "--method", "required": true }, { "description": "No-op, accepted for compatibility: watch-guards ALWAYS run as a persistent daemon (see daemon_mode in execute())", "flag": "--daemon", "required": false }, { "default": "varies by watch type", "description": "Custom check interval in seconds (1-300)", "flag": "--interval", "required": false }, { "default": "log_event,show_alert,play_sound,block_network", "description": "Comma-separated actions to execute when triggered", "flag": "--actions", "required": false } ], "requires_sudo": true, "usage": "health-control enable --type watch-guard --watch --method " }, { "description": "Disable an active watch-guard and optionally unblock internet", "examples": [ "sudo health-control disable --type watch-guard vpn", "sudo health-control disable --type watch-guard ip", "sudo health-control disable --type watch-guard timezone", "sudo health-control disable --type watch-guard interfaces", "sudo health-control disable --type watch-guard tor", "sudo health-control disable --type watch-guard all", "sudo health-control disable --type watch-guard all --no-unblock" ], "name": "disable", "options": [ { "description": "Type of command to disable", "flag": "--type", "required": true }, { "description": "Which watch-guard to disable: a watch type (vpn, dns, ip, mac, hostname, timezone, interfaces, process), a guard id, a process name such as tor, or all", "flag": "", "required": true }, { "description": "Do not unblock internet after disabling watch-guard", "flag": "--no-unblock", "required": false } ], "requires_sudo": true, "usage": "health-control disable --type watch-guard " }, { "description": "Show status of active watch-guards", "examples": [ "sudo health-control watch-guard status", "sudo health-control watch-guard status --json" ], "name": "watch-guard", "options": [], "requires_sudo": true, "usage": "health-control watch-guard status" }, { "description": "Run watch-guard monitoring as a persistent daemon process", "examples": [ "sudo health-control daemon --config-id " ], "name": "daemon", "options": [ { "description": "Configuration ID to monitor", "flag": "--config-id", "required": true } ], "requires_sudo": true, "usage": "health-control daemon --config-id " } ] }, { "category": "MAC Address Management", "commands": [ { "description": "Change all MAC addresses", "examples": [ "sudo health-control mac-change-all", "sudo health-control mac-change-all --json", "sudo health-control mac-change-all --force" ], "name": "mac-change-all", "options": [ { "description": "Also change the MAC of the active default-route (management/SSH) interface", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control mac-change-all [OPTIONS]" }, { "description": "Force change all MAC addresses (disable interfaces first)", "examples": [ "sudo health-control mac-force-change", "sudo health-control mac-force-change --json" ], "name": "mac-force-change", "options": [], "requires_sudo": true, "usage": "health-control mac-force-change [OPTIONS]" }, { "description": "Change specific interface MAC address", "examples": [ "sudo health-control mac-change-specific --interface eth0", "sudo health-control mac-change-specific --interface wlan0 --json", "sudo health-control mac-change-specific --interface eth0 --force" ], "name": "mac-change-specific", "options": [ { "description": "Target interface name", "flag": "--interface ", "required": true }, { "description": "Allow targeting the active default-route (management/SSH) interface", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control mac-change-specific [OPTIONS]" }, { "description": "Show available network interfaces", "examples": [ "sudo health-control mac-show-interfaces", "sudo health-control mac-show-interfaces --json" ], "name": "mac-show-interfaces", "options": [], "requires_sudo": true, "usage": "health-control mac-show-interfaces [OPTIONS]" }, { "description": "Show current MAC addresses", "examples": [ "sudo health-control mac-show-macs", "sudo health-control mac-show-macs --json" ], "name": "mac-show-macs", "options": [], "requires_sudo": true, "usage": "health-control mac-show-macs [OPTIONS]" }, { "description": "Reset all MAC addresses to default", "examples": [ "sudo health-control mac-reset-all", "sudo health-control mac-reset-all --json" ], "name": "mac-reset-all", "options": [], "requires_sudo": true, "usage": "health-control mac-reset-all [OPTIONS]" }, { "description": "Show active network interface", "examples": [ "sudo health-control mac-active-interface", "sudo health-control mac-active-interface --json" ], "name": "mac-active-interface", "options": [], "requires_sudo": true, "usage": "health-control mac-active-interface [OPTIONS]" } ] }, { "category": "Memory Management", "commands": [ { "description": "Clean memory caches and buffers", "examples": [ "sudo health-control memory-clean", "sudo health-control memory-clean --json" ], "name": "memory-clean", "options": [], "requires_sudo": true, "usage": "health-control memory-clean [OPTIONS]" }, { "description": "Force clean memory by killing top process", "examples": [ "sudo health-control memory-force-clean", "sudo health-control memory-force-clean --json" ], "name": "memory-force-clean", "options": [], "requires_sudo": true, "usage": "health-control memory-force-clean [OPTIONS]" }, { "description": "Secure RAM wipe (sdmem)", "examples": [ "sudo health-control memory-wipe", "sudo health-control memory-wipe --json" ], "name": "memory-wipe", "options": [], "requires_sudo": true, "usage": "health-control memory-wipe [OPTIONS]" }, { "description": "Wipe memory of specific process", "examples": [ "sudo health-control memory-wipe-process --value firefox", "sudo health-control memory-wipe-process --value 1234 --json" ], "name": "memory-wipe-process", "options": [ { "description": "Process name or PID", "flag": "--value ", "required": true } ], "requires_sudo": true, "usage": "health-control memory-wipe-process [OPTIONS]" }, { "description": "Manage process memory limits", "examples": [ "sudo health-control memory-limits", "sudo health-control memory-limits --value firefox --limit-mb 1024", "sudo health-control memory-limits --value chrome --limit-mb 2048", "sudo health-control memory-limits --value brave --limit-mb 1536", "sudo health-control memory-limits --json" ], "name": "memory-limits", "options": [ { "description": "Process name to set limit for", "flag": "--value " }, { "description": "Memory limit in MB", "flag": "--limit-mb " } ], "requires_sudo": true, "usage": "health-control memory-limits [OPTIONS]" }, { "description": "Display memory statistics and history", "examples": [ "sudo health-control memory-stats", "sudo health-control memory-stats --history --json" ], "name": "memory-stats", "options": [ { "description": "Include memory usage history", "flag": "--history" } ], "requires_sudo": true, "usage": "health-control memory-stats [OPTIONS]" }, { "description": "Configure swap settings", "examples": [ "sudo health-control swap-configure --swappiness 10 --cache-pressure 50", "sudo health-control swap-configure --swappiness 0 --json" ], "name": "swap-configure", "options": [ { "description": "Swappiness value (0-100)", "flag": "--swappiness " }, { "description": "Cache pressure value", "flag": "--cache-pressure " } ], "requires_sudo": true, "usage": "health-control swap-configure [OPTIONS]" }, { "description": "Disable swap memory", "examples": [ "sudo health-control disable-swap", "sudo health-control disable-swap --json" ], "name": "disable-swap", "options": [], "requires_sudo": true, "usage": "health-control disable-swap [OPTIONS]" }, { "description": "Enable swap memory", "examples": [ "sudo health-control enable-swap", "sudo health-control enable-swap --size 2048", "sudo health-control enable-swap --size 4096", "sudo health-control enable-swap --json" ], "name": "enable-swap", "options": [ { "default": "2048", "description": "Swap size in MB", "flag": "--size " } ], "requires_sudo": true, "usage": "health-control enable-swap [OPTIONS]" } ] }, { "category": "Network Connectivity", "commands": [ { "description": "Check network connectivity (IP ping, DNS, and HTTP probe)", "examples": [ "sudo health-control net-check", "sudo health-control net-check --json", "sudo health-control net-check --timeout 15", "sudo health-control net-check --http", "sudo health-control net-check --http --json", "sudo health-control net-check --ip-only", "sudo health-control net-check --domain-only", "sudo health-control net-check --http-only", "sudo health-control net-check --http-only --json", "sudo health-control net-check --domain-only --dns-server 127.0.0.1:5353" ], "name": "net-check", "options": [ { "default": "10", "description": "Timeout in seconds for each connectivity check", "flag": "--timeout ", "required": false }, { "description": "Run the extended HTTP-focused check path (IP ping + DNS + HTTP, verbose per-target reporting)", "flag": "--http", "required": false }, { "description": "Check IP ping only, skip DNS lookups and HTTP probe", "flag": "--ip-only", "required": false }, { "description": "Check DNS resolution only, skip IP ping and HTTP probe", "flag": "--domain-only", "required": false }, { "description": "Check HTTP reachability only, skip IP ping and DNS lookups (returns HTTP_ONLY_CONNECTIVITY/5 on success)", "flag": "--http-only", "required": false }, { "description": "Custom DNS server address (e.g., 127.0.0.1:5353 for Tor DNS)", "flag": "--dns-server ", "required": false } ], "requires_sudo": true, "usage": "health-control net-check [--timeout ] [--http] [--ip-only|--domain-only|--http-only] [--dns-server ]" }, { "description": "Check network connectivity including HTTP", "examples": [ "sudo health-control net-check-http", "sudo health-control net-check-http --timeout 15", "sudo health-control net-check-http --json" ], "name": "net-check-http", "options": [ { "default": "10", "description": "Timeout in seconds", "flag": "--timeout " } ], "requires_sudo": true, "usage": "health-control net-check-http [OPTIONS]" }, { "description": "List IPs used for connectivity testing", "examples": [ "sudo health-control list-ips", "sudo health-control list-ips --json" ], "name": "list-ips", "options": [], "requires_sudo": true, "usage": "health-control list-ips [OPTIONS]" }, { "description": "List domains used for connectivity testing", "examples": [ "sudo health-control list-domains", "sudo health-control list-domains --json" ], "name": "list-domains", "options": [], "requires_sudo": true, "usage": "health-control list-domains [OPTIONS]" } ] }, { "category": "Offline Actions", "commands": [ { "description": "Manage PostgreSQL database service", "examples": [ "sudo health-control offline-postgresql --action disable", "sudo health-control offline-postgresql --action enable", "sudo health-control offline-postgresql --action check --json" ], "name": "offline-postgresql", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action ", "required": true } ], "requires_sudo": true, "usage": "health-control offline-postgresql [OPTIONS]" } ] }, { "category": "Password Generation", "commands": [ { "description": "Generate secure passwords using multiple methods (pass, pwgen, xkcdpass)", "examples": [ "sudo health-control genpass", "sudo health-control genpass --method pwgen", "sudo health-control genpass --count 10", "sudo health-control genpass --method pwgen --count 50", "sudo health-control genpass --method xkcdpass --count 20 --json", "sudo health-control genpass --length 32 --symbols \"@-_!#$\"" ], "name": "genpass", "options": [ { "description": "Password generation method: pass, pwgen, or xkcdpass", "flag": "--method " }, { "default": "1", "description": "Number of passwords to generate (default: 1, max: 1000)", "flag": "-c, --count " }, { "default": "25", "description": "Password length (default: 25)", "flag": "-l, --length " }, { "description": "Include uppercase letters", "flag": "--uppercase" }, { "description": "Explicitly exclude uppercase letters", "flag": "--no-uppercase" }, { "description": "Include lowercase letters", "flag": "--lowercase" }, { "description": "Explicitly exclude lowercase letters", "flag": "--no-lowercase" }, { "description": "Include digits", "flag": "--digits" }, { "description": "Explicitly exclude digits", "flag": "--no-digits" }, { "default": "@-#", "description": "Symbols to include (default: \"@-#\")", "flag": "--symbols " }, { "description": "Force use of native Rust implementations (skip package check)", "flag": "--force-native" } ], "requires_sudo": true, "usage": "health-control genpass [OPTIONS]" } ] }, { "category": "Security", "commands": [ { "description": "Show comprehensive security status", "examples": [ "sudo health-control security-status", "sudo health-control security-status --category network", "sudo health-control security-status --category all --json", "sudo health-control security-status all", "sudo health-control security-status network --json" ], "name": "security-status", "options": [ { "description": "Specific category: network, kernel, memory, filesystem, monitoring, sandboxing, all", "flag": "" }, { "description": "Specific category (alternative to positional)", "flag": "--category " } ], "requires_sudo": true, "usage": "health-control security-status [OPTIONS]" } ] }, { "category": "Security Assessment", "commands": [ { "description": "Calculate security score and get recommendations", "examples": [ "health-control security-score", "health-control security-score --json" ], "name": "security-score", "options": [], "requires_sudo": false, "usage": "health-control security-score [OPTIONS]" }, { "description": "Generate comprehensive security report", "examples": [ "sudo health-control security-report", "sudo health-control security-report --format detailed", "sudo health-control security-report --format compliance --json" ], "name": "security-report", "options": [ { "default": "summary", "description": "Report format: summary, detailed, compliance", "flag": "--format " } ], "requires_sudo": true, "usage": "health-control security-report [OPTIONS]" }, { "description": "Set security profile and thresholds", "examples": [ "sudo health-control security-profile --value minimal", "sudo health-control security-profile --value balanced", "sudo health-control security-profile --value paranoid", "sudo health-control security-profile --value balanced --json" ], "name": "security-profile", "options": [ { "description": "Security profile: minimal, balanced, paranoid", "flag": "--value ", "required": true } ], "requires_sudo": true, "usage": "health-control security-profile [OPTIONS]" }, { "description": "View security configuration history", "examples": [ "sudo health-control security-history", "sudo health-control security-history --days 30", "sudo health-control security-history --json" ], "name": "security-history", "options": [ { "default": "7", "description": "Number of days to show", "flag": "--days " } ], "requires_sudo": true, "usage": "health-control security-history [OPTIONS]" }, { "description": "Auto-remediate security issues", "examples": [ "sudo health-control security-remediate", "sudo health-control security-remediate --bool true", "sudo health-control security-remediate --bool false --json" ], "name": "security-remediate", "options": [ { "default": "false", "description": "Apply fixes automatically without confirmation", "flag": "--bool " } ], "requires_sudo": true, "usage": "health-control security-remediate [OPTIONS]" }, { "description": "Schedule security scans (hourly, daily, weekly, monthly, disable)", "examples": [ "sudo health-control security-schedule --value daily", "sudo health-control security-schedule --value weekly", "sudo health-control security-schedule --value disable --json" ], "name": "security-schedule", "options": [ { "description": "Schedule: hourly, daily, weekly, monthly, disable", "flag": "--value ", "required": true } ], "requires_sudo": true, "usage": "health-control security-schedule [OPTIONS]" }, { "description": "Enhanced rootkit scanning with multiple tools", "examples": [ "sudo health-control rootkit-scan-enhanced", "sudo health-control rootkit-scan-enhanced --deep", "sudo health-control rootkit-scan-enhanced --json" ], "name": "rootkit-scan-enhanced", "options": [ { "description": "Perform deep scan", "flag": "--deep" } ], "requires_sudo": true, "usage": "health-control rootkit-scan-enhanced [OPTIONS]" }, { "description": "Run Lynis security audit", "examples": [ "sudo health-control lynis-audit", "sudo health-control lynis-audit --value quick", "sudo health-control lynis-audit --value pentest --json" ], "name": "lynis-audit", "options": [ { "default": "full", "description": "Audit profile: quick, full, pentest", "flag": "--value " } ], "requires_sudo": true, "usage": "health-control lynis-audit [OPTIONS]" }, { "description": "Check Lynis installation status", "examples": [ "health-control lynis-status", "health-control lynis-status --json" ], "name": "lynis-status", "options": [], "requires_sudo": false, "usage": "health-control lynis-status [OPTIONS]" }, { "description": "Scan system with ClamAV antivirus", "examples": [ "sudo health-control clamav-scan", "sudo health-control clamav-scan --path . --recursive", "sudo health-control clamav-scan --quarantine --json" ], "name": "clamav-scan", "options": [ { "description": "Path to scan (default: health-control execution directory)", "flag": "--path " }, { "description": "Scan recursively", "flag": "--recursive" }, { "description": "Quarantine infected files", "flag": "--quarantine" }, { "default": "900", "description": "Maximum scanner runtime in seconds (10-3600)", "flag": "--timeout-seconds " } ], "requires_sudo": true, "usage": "health-control clamav-scan [OPTIONS]" } ] }, { "category": "Security Hardening", "commands": [ { "description": "Apply comprehensive security hardening", "examples": [ "sudo health-control security-harden", "sudo health-control security-harden --profile standard", "sudo # STANDARD PROFILE (soft), Nothing breaks, score 5/7", "sudo # Applies: Safe kernel sysctls, secure filesystem mounts,", "sudo # ASLR=2, symlink/hardlink protection, SYN flood protection,", "sudo # auditd monitoring, AppArmor/Firejail detection", "sudo # Also normalizes: Reverts any stricter settings left from medium/paranoid", "sudo # Safe for: All systems, all browsers, VPN/Tor routing", "sudo ", "sudo health-control security-harden --profile medium", "sudo # MEDIUM PROFILE (moderate), Browsers+internet still work, score 6/7", "sudo # Includes Standard, PLUS: hidepid=2 on /proc, hardened_malloc,", "sudo # vm.dirty_ratio tuning, file integrity monitoring", "sudo # Also normalizes: Reverts paranoid-only settings (namespaces, IP forwarding)", "sudo # May affect: LUKS systems (higher memory from hardened_malloc)", "sudo ", "sudo health-control security-harden --profile paranoid", "sudo # PARANOID PROFILE (maximum), Full lockdown, score 7/7", "sudo # Includes Medium, PLUS: disable user namespaces, disable IP forwarding,", "sudo # MAC spoofing, DNS firewall, LKRG, Tirdad, SMT off, RAM wipe", "sudo # WILL BREAK: Browsers, Internet, VPN/Tor routing", "sudo # Recover: health-control security-recover", "sudo ", "sudo health-control security-harden --break-monitoring", "sudo # Alias for --profile paranoid + makes /sys/class/net root-only", "sudo ", "sudo health-control security-harden --modules kernel,network --json", "sudo # Apply only specific modules with JSON output", "sudo ", "sudo # LUKS encryption notice:", "sudo # On LUKS systems, medium/paranoid profiles increase memory usage.", "sudo # If OOM or browser crashes occur: health-control security-recover" ], "name": "security-harden", "options": [ { "default": "standard", "description": "Security profile: 'standard' (soft, nothing breaks), 'medium' (moderate, browsers+internet OK), 'paranoid' (maximum, WILL break browsers+internet)", "flag": "--profile " }, { "description": "Force paranoid hardening and make /sys/class/net root-only (breaks btop/conky/dashboard monitoring)", "flag": "--break-monitoring" }, { "description": "Apply only specific security modules (comma-separated): kernel (sysctl hardening), process (isolation/namespaces), filesystem (secure mounts), network (firewall rules), memory (ASLR/protection), monitoring (auditd), sandboxing (AppArmor/seccomp)", "flag": "--modules " } ], "requires_sudo": true, "usage": "health-control security-harden [OPTIONS]" }, { "description": "Verify if security hardening is properly applied (checks all 7 modules and reports their status)", "examples": [ "sudo health-control security-verify", "sudo # Check status of all 7 security modules against current profile", "sudo # Also checks for forbidden leftover settings from higher profiles", "sudo # Standard expects: 5/7 modules, no medium/paranoid leftovers", "sudo # Medium expects: 6/7 modules, no paranoid leftovers", "sudo # Paranoid expects: 7/7 modules configured", "sudo ", "sudo health-control security-verify --profile medium", "sudo # Verify against medium profile expectations", "sudo ", "sudo health-control security-verify --profile paranoid", "sudo # Verify against paranoid profile expectations", "sudo ", "sudo health-control security-verify --json", "sudo # Get detailed JSON output with all verification data + leftover warnings" ], "name": "security-verify", "options": [ { "description": "Security profile to verify against. Defaults to the profile used during hardening, or 'standard' if no hardening has been applied.", "flag": "--profile " } ], "requires_sudo": true, "usage": "health-control security-verify [OPTIONS]" }, { "description": "Temporarily revert security hardening (keeps framework enabled for quick re-hardening)", "examples": [ "sudo # Temporarily revert security hardening (keeps framework ready for re-hardening)", "sudo health-control security-recover", "sudo ", "sudo # After recovery, modules show 'ENABLED (needs configuration)'", "sudo # This means: Framework is ready but no restrictions are enforced", "sudo # Use this when: Troubleshooting issues, planning to re-harden later", "sudo ", "sudo # Recover only specific modules", "sudo health-control security-recover --modules network,kernel", "sudo ", "sudo # LUKS systems: If hardening caused OOM kills or browser crashes,", "sudo # recovery restores vm.dirty_ratio=20 (default) and re-enables", "sudo # user namespaces for browser sandbox compatibility.", "sudo ", "sudo # To re-apply hardening after recovery:", "sudo health-control security-harden" ], "name": "security-recover", "options": [ { "description": "Specific modules to recover: kernel,process,filesystem,network,memory,monitoring,sandboxing", "flag": "--modules " } ], "requires_sudo": true, "usage": "health-control security-recover [OPTIONS]" }, { "description": "Completely disable all security modules and framework (permanent removal)", "examples": [ "sudo # Completely disable all security modules and framework", "sudo health-control security-reset", "sudo ", "sudo # After reset, security-verify shows modules as NOT HARDENED", "sudo # This means: All applied security hardening has been reverted", "sudo # Use this when: You want to permanently remove security hardening", "sudo ", "sudo # Skip confirmation prompt", "sudo health-control security-reset --force", "sudo ", "sudo # Warning: After reset, security-harden will need to rebuild framework" ], "name": "security-reset", "options": [ { "description": "Skip confirmation prompt", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control security-reset [OPTIONS]" }, { "description": "Enable system monitoring features", "examples": [ "sudo health-control monitoring-enable", "sudo health-control monitoring-enable --modules auditd,lkrg,file-integrity", "sudo health-control monitoring-enable --json" ], "name": "monitoring-enable", "options": [ { "description": "Specific monitoring modules: auditd,lkrg,file-integrity,auth-events,process,network", "flag": "--modules " } ], "requires_sudo": true, "usage": "health-control monitoring-enable [OPTIONS]" }, { "description": "Disable system monitoring features", "examples": [ "sudo health-control monitoring-disable", "sudo health-control monitoring-disable --modules auditd,lkrg", "sudo health-control monitoring-disable --json" ], "name": "monitoring-disable", "options": [ { "description": "Specific monitoring modules: auditd,lkrg,file-integrity,auth-events,process,network", "flag": "--modules " } ], "requires_sudo": true, "usage": "health-control monitoring-disable [OPTIONS]" }, { "description": "Check system security monitoring status", "examples": [ "sudo health-control monitoring-status", "sudo health-control monitoring-status --json" ], "name": "monitoring-status", "options": [], "requires_sudo": true, "usage": "health-control monitoring-status [OPTIONS]" }, { "description": "Disable IPv6 system-wide", "examples": [ "sudo health-control ipv6-disable", "sudo health-control ipv6-disable --json" ], "name": "ipv6-disable", "options": [], "requires_sudo": true, "usage": "health-control ipv6-disable [OPTIONS]" }, { "description": "Enable IPv6 system-wide", "examples": [ "sudo health-control ipv6-enable", "sudo health-control ipv6-enable --json" ], "name": "ipv6-enable", "options": [], "requires_sudo": true, "usage": "health-control ipv6-enable [OPTIONS]" }, { "description": "Enable Tirdad TCP ISN randomization", "examples": [ "sudo health-control tirdad-enable", "sudo health-control tirdad-enable --json" ], "name": "tirdad-enable", "options": [], "requires_sudo": true, "usage": "health-control tirdad-enable [OPTIONS]" }, { "description": "Disable Tirdad TCP ISN randomization", "examples": [ "sudo health-control tirdad-disable", "sudo health-control tirdad-disable --json" ], "name": "tirdad-disable", "options": [], "requires_sudo": true, "usage": "health-control tirdad-disable [OPTIONS]" }, { "description": "Check Tirdad TCP ISN randomization status", "examples": [ "health-control tirdad-status", "health-control tirdad-status --json" ], "name": "tirdad-status", "options": [], "requires_sudo": false, "usage": "health-control tirdad-status [OPTIONS]" }, { "description": "Check IPv6 status", "examples": [ "health-control ipv6-status", "health-control ipv6-status --json" ], "name": "ipv6-status", "options": [], "requires_sudo": false, "usage": "health-control ipv6-status [OPTIONS]" }, { "description": "Enable secure RAM wiping on shutdown", "examples": [ "sudo health-control ram-wipe", "sudo health-control ram-wipe --json" ], "name": "ram-wipe", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe [OPTIONS]" }, { "description": "Install RAM wipe system (hooks + configuration) - Run this first if not already installed", "examples": [ "sudo health-control wipe-ram-install", "sudo health-control wipe-ram-install --policy kodachi-wiper", "sudo health-control wipe-ram-install --policy sdmem --passes 3", "sudo health-control wipe-ram-install --time 120", "sudo health-control wipe-ram-install --policy sdmem --passes 5", "sudo health-control wipe-ram-install --policy both --time 120 --passes 3", "sudo health-control wipe-ram-install --force", "sudo health-control wipe-ram-install --json" ], "name": "wipe-ram-install", "options": [ { "default": "false", "description": "Force installation even if Kicksecure/Whonix RAM wipe detected. WARNING: May conflict with existing systems", "flag": "--force" }, { "default": "kodachi-wiper", "description": "Initial wipe policy: kodachi-wiper (fast, recommended)|sdmem (secure DoD-standard)|both (hybrid)|auto (intelligent auto-selection)", "flag": "--policy " }, { "default": "60", "description": "Time budget for shutdown RAM wiping (default: 60s). Recommended: 60-90s desktops, 120-300s servers", "flag": "--time " }, { "default": "3", "description": "Number of sdmem overwrite passes 1-9 (default: 3). More passes = more secure but slower. Recommended: 3 balanced, 7+ high-security", "flag": "--passes " } ], "requires_sudo": true, "usage": "health-control wipe-ram-install [OPTIONS]" }, { "description": "Show RAM wipe system status - Check this first before installing or configuring", "examples": [ "sudo health-control ram-wipe-status", "sudo health-control ram-wipe-status --json" ], "name": "ram-wipe-status", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-status [OPTIONS]" }, { "description": "Update RAM wipe configuration - Use this to modify settings after installation", "examples": [ "sudo health-control wipe-ram-config --policy auto", "sudo health-control wipe-ram-config --policy kodachi-wiper", "sudo health-control wipe-ram-config --time 120", "sudo health-control wipe-ram-config --passes 5", "sudo health-control wipe-ram-config --split 70", "sudo health-control wipe-ram-config --policy both --time 120", "sudo health-control wipe-ram-config --policy both --time 90 --passes 3 --split 60", "sudo health-control wipe-ram-config --json" ], "name": "wipe-ram-config", "options": [ { "description": "Set policy: kodachi-wiper (fast native wiper)|sdmem (secure multi-pass)|both (balanced hybrid)|auto (intelligent auto-detection: prefers kodachi-wiper, falls back to sdmem if unavailable)", "flag": "--policy " }, { "description": "Set time budget for shutdown RAM wiping. Recommended: 60-90s desktops, 120-300s servers", "flag": "--time " }, { "description": "Set number of sdmem passes (1-9). More = secure but slower. Recommended: 3 balanced, 7+ high-security", "flag": "--passes " }, { "description": "Set time split for 'both' mode (10-90). Example: 70 = 70% kodachi-wiper, 30% sdmem. Higher = faster but less secure", "flag": "--split " } ], "requires_sudo": true, "usage": "health-control wipe-ram-config [OPTIONS]" }, { "description": "Enable automatic RAM wiping on shutdown", "examples": [ "sudo health-control ram-wipe-enable", "sudo health-control ram-wipe-enable --passes 5", "sudo health-control ram-wipe-enable --schedule shutdown --passes 3", "sudo health-control ram-wipe-enable --json", "sudo health-control wipe-ram # wipe RAM NOW (this is the real 'immediate')" ], "name": "ram-wipe-enable", "options": [ { "default": "shutdown", "description": "When the wipe runs. ONLY 'shutdown' is implemented (executed by the systemd shutdown hook). 'immediate' and 'delay' are accepted but IGNORED: for an immediate wipe use `health-control wipe-ram`", "flag": "--schedule", "required": false }, { "default": "3", "description": "Number of overwrite passes (this IS honoured)", "flag": "--passes", "required": false } ], "requires_sudo": true, "usage": "health-control ram-wipe-enable [OPTIONS]" }, { "description": "Disable automatic RAM wiping", "examples": [ "sudo health-control ram-wipe-disable", "sudo health-control ram-wipe-disable --preserve-config", "sudo health-control ram-wipe-disable --json" ], "name": "ram-wipe-disable", "options": [ { "description": "Keep configuration for future use", "flag": "--preserve-config" } ], "requires_sudo": true, "usage": "health-control ram-wipe-disable [OPTIONS]" }, { "description": "Test RAM wipe operation (dry-run with short time budget) - Run this to verify installation before relying on automatic wipes", "examples": [ "sudo health-control wipe-ram-test", "sudo health-control wipe-ram-test --policy kodachi-wiper", "sudo health-control wipe-ram-test --policy sdmem", "sudo health-control wipe-ram-test --policy both --time 60", "sudo health-control wipe-ram-test --time 30", "sudo health-control wipe-ram-test --policy kodachi-wiper --time 20", "sudo health-control wipe-ram-test --json" ], "name": "wipe-ram-test", "options": [ { "description": "Test specific wipe policy: kodachi-wiper (fast)|sdmem (secure DoD-standard)|both (hybrid)|auto (intelligent auto-selection)", "flag": "--policy " }, { "default": "10", "description": "Test time budget in seconds (default: 10). Quick test only - actual shutdown wipe uses configured time budget from wipe-ram-config", "flag": "--time " } ], "requires_sudo": true, "usage": "health-control wipe-ram-test [OPTIONS]" }, { "description": "Execute RAM wipe operation (primarily used by systemd/init shutdown hooks, but can be run manually for testing)", "examples": [ "sudo health-control wipe-ram", "sudo health-control wipe-ram --policy kodachi-wiper", "sudo health-control wipe-ram --policy sdmem", "sudo health-control wipe-ram --policy both --time 120", "sudo health-control wipe-ram --time 120", "sudo health-control wipe-ram --no-console", "sudo health-control wipe-ram --json", "sudo health-control wipe-ram --shutdown-mode" ], "name": "wipe-ram", "options": [ { "default": "false", "description": "INTERNAL USE - Shutdown-optimized mode for systemd/init hooks. Users should use 'wipe-ram' without this flag", "flag": "--shutdown-mode" }, { "default": "false", "description": "Disable console output for silent operation (useful in scripts and background tasks)", "flag": "--no-console" }, { "description": "Override wipe policy: kodachi-wiper (fast native wiper for quick shutdowns)|sdmem (secure DoD-standard multi-pass for maximum security)|both (hybrid approach: fast+secure)|auto (intelligent auto-selection based on system capabilities)", "flag": "--policy " }, { "description": "Override time budget in seconds (how long to spend wiping RAM). Higher values = more memory wiped but longer shutdown time", "flag": "--time " } ], "requires_sudo": true, "usage": "health-control wipe-ram [OPTIONS]" }, { "description": "Detect Kicksecure/Whonix RAM wipe installation", "examples": [ "sudo health-control ram-wipe-detect-kicksecure", "sudo health-control ram-wipe-detect-kicksecure --json", "sudo health-control ram-wipe-detect-kicksecure --json-human" ], "name": "ram-wipe-detect-kicksecure", "options": [], "requires_sudo": true, "usage": "health-control ram-wipe-detect-kicksecure" }, { "description": "Update RAM wipe configuration (alias for wipe-ram-config)", "examples": [ "sudo health-control ram-wipe-update --policy auto", "sudo health-control ram-wipe-update --policy both --time 150", "sudo health-control ram-wipe-update --policy kodachi-wiper", "sudo health-control ram-wipe-update --time 120", "sudo health-control ram-wipe-update --passes 5", "sudo health-control ram-wipe-update --json" ], "name": "ram-wipe-update", "options": [ { "description": "Set policy: kodachi-wiper (fast native wiper)|sdmem (secure multi-pass)|both (balanced hybrid)|auto (intelligent auto-detection: prefers kodachi-wiper, falls back to sdmem if unavailable)", "flag": "--policy " }, { "description": "Set time budget in seconds", "flag": "--time " }, { "description": "Set sdmem passes (1-9)", "flag": "--passes " }, { "description": "Set custom/sdmem split for 'both' mode (10-90)", "flag": "--split " } ], "requires_sudo": true, "usage": "health-control ram-wipe-update [OPTIONS]" }, { "description": "Check disk encryption status and security", "examples": [ "sudo health-control disk-encryption-status", "sudo health-control disk-encryption-status --json" ], "name": "disk-encryption-status", "options": [], "requires_sudo": true, "usage": "health-control disk-encryption-status [OPTIONS]" }, { "description": "Enable swap partition/file", "examples": [ "sudo health-control swap-enable", "sudo health-control swap-enable --json" ], "name": "swap-enable", "options": [], "requires_sudo": true, "usage": "health-control swap-enable [OPTIONS]" }, { "description": "Disable swap partition/file", "examples": [ "sudo health-control swap-disable", "sudo health-control swap-disable --json" ], "name": "swap-disable", "options": [], "requires_sudo": true, "usage": "health-control swap-disable [OPTIONS]" }, { "description": "Encrypt swap partition/file", "examples": [ "sudo health-control swap-encrypt", "sudo health-control swap-encrypt --json" ], "name": "swap-encrypt", "options": [], "requires_sudo": true, "usage": "health-control swap-encrypt [OPTIONS]" }, { "description": "Check swap status and configuration", "examples": [ "sudo health-control swap-status", "sudo health-control swap-status --json" ], "name": "swap-status", "options": [], "requires_sudo": true, "usage": "health-control swap-status [OPTIONS]" }, { "description": "Decrypt encrypted swap partition/file", "examples": [ "sudo health-control swap-decrypt", "sudo health-control swap-decrypt --device /dev/DEVICE", "sudo health-control swap-decrypt --json" ], "name": "swap-decrypt", "options": [ { "description": "Swap device to decrypt", "flag": "--device " } ], "requires_sudo": true, "usage": "health-control swap-decrypt [OPTIONS]" }, { "description": "Check swap encryption status", "examples": [ "sudo health-control swap-encrypt-status", "sudo health-control swap-encrypt-status --json" ], "name": "swap-encrypt-status", "options": [], "requires_sudo": true, "usage": "health-control swap-encrypt-status [OPTIONS]" }, { "description": "List all USB devices", "examples": [ "sudo health-control usb-list", "sudo health-control usb-list --json" ], "name": "usb-list", "options": [], "requires_sudo": true, "usage": "health-control usb-list [OPTIONS]" }, { "description": "Manage LUKS nuke passwords", "examples": [ "sudo # AUTOMATED HEADER BACKUP + Nuke Configuration", "sudo ", "sudo # Check nuke password status", "sudo health-control luks-nuke --action status", "sudo ā†’ Shows all LUKS devices and nuke password status", "sudo ", "sudo # Check specific device", "sudo health-control luks-nuke --action status --device /dev/DEVICE", "sudo ā†’ Shows nuke password status for /dev/DEVICE only", "sudo ", "sudo # Configure nuke password (FULLY AUTOMATED)", "sudo health-control luks-nuke --action configure --device /dev/DEVICE", "sudo ā†’ Backs up LUKS header AUTOMATICALLY to /backups/", "sudo ā†’ Encrypts backup with GPG automatically", "sudo ā†’ Configures nuke password via cryptsetup-nuke-password", "sudo ā†’ Verifies everything works", "sudo ā†’ NO manual cryptsetup commands needed!", "sudo ", "sudo # Configure with CLI password (INSECURE - visible in history)", "sudo health-control luks-nuke --action configure --device /dev/DEVICE --password ''", "sudo āš ļø WARNING: Password visible in shell history!", "sudo ā†’ Still backs up header automatically", "sudo ", "sudo # Header backup location", "sudo # Saved to: /backups/header-{device-name}-{timestamp}.img.gpg", "sudo # Keep this file SAFE - it's your ONLY recovery option!", "sudo ", "sudo # Remove nuke password", "sudo health-control luks-nuke --action remove --device /dev/DEVICE", "sudo ā†’ Removes nuke password via cryptsetup-nuke-password", "sudo ", "sudo # MANUAL EMERGENCY EXECUTE (IRREVERSIBLE)", "sudo health-control luks-nuke --action execute --device /dev/DEVICE --force-execute", "sudo ā†’ Immediately destroys LUKS key material on selected device.", "sudo ā†’ Data becomes permanently unrecoverable.", "sudo ", "sudo # ā„¹ļø FILE-BASED LUKS CONTAINERS SUPPORTED", "sudo # Works with both block devices (/dev/*) AND file-based containers", "sudo ", "sudo # Configure nuke for live-boot persistence image (AUTOMATED)", "sudo health-control luks-nuke --action configure --device /tmp/persistence", "sudo ā†’ Backs up header automatically", "sudo ā†’ Supports file-based LUKS containers created by create-persistence", "sudo ", "sudo # Check nuke status on encrypted persistence file", "sudo health-control luks-nuke --action status --device /media/kodachi/persistence", "sudo ā†’ File must exist and be a valid LUKS container", "sudo ", "sudo # Remove nuke from file-based container", "sudo health-control luks-nuke --action remove --device /tmp/encrypted-container.img", "sudo ā†’ Works identically with files and block devices", "sudo ", "sudo # COMPLETE AUTOMATED WORKFLOW", "sudo # Create encrypted persistence with nuke password - ZERO manual steps", "sudo ", "sudo # Step 1: List devices to find USB", "sudo health-control list-storage-devices", "sudo ", "sudo # Step 2: Check device safety", "sudo health-control usb-safety-check --device /dev/DEVICE", "sudo ", "sudo # Step 3: Create encrypted persistence (AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type kali --encrypted", "sudo ā†’ Confirms device selection", "sudo ā†’ Formats automatically", "sudo ā†’ Creates persistence.conf automatically", "sudo ā†’ Done!", "sudo ", "sudo # Step 4: Configure nuke password (AUTOMATED)", "sudo health-control luks-nuke --action configure --device /dev/DEVICE", "sudo ā†’ Backs up header automatically to /backups/", "sudo ā†’ Configures nuke password automatically", "sudo ā†’ Verifies everything works", "sudo ā†’ Done!", "sudo ", "sudo # āœ… ZERO MANUAL COMMANDS!", "sudo # āœ… NO manual mounting/unmounting!", "sudo # āœ… NO manual backup commands!", "sudo # āœ… Everything automated with safety confirmations!", "sudo ", "sudo # EMERGENCY: Restore header if nuke password used accidentally", "sudo gpg -d /backups/header-DEVICE-*.img.gpg | sudo cryptsetup luksHeaderRestore /dev/DEVICE", "sudo ", "sudo # List available encrypted header backups", "sudo health-control luks-nuke --action list-backups --device /dev/DEVICE", "sudo ", "sudo # Restore from encrypted backup", "sudo health-control luks-nuke --action restore-backup --device /dev/DEVICE --backup-file header-DEVICE-20260304-014630.img.gpg", "sudo ", "sudo # Delete old backup", "sudo health-control luks-nuke --action delete-backup --backup-file header-sda1-20260304-014630.img.gpg", "sudo āš ļø USE ONLY IF nuke password was accidentally entered!", "sudo ", "sudo # JSON output for monitoring", "sudo health-control luks-nuke --action status --json" ], "name": "luks-nuke", "options": [ { "description": "Action: configure, remove, status, execute, list-backups, restore-backup, delete-backup", "flag": "--action ", "required": true }, { "description": "LUKS device path (block device or file-based LUKS container)", "flag": "--device " }, { "description": "Nuke password (for configure action)", "flag": "--password " }, { "description": "GPG password for header-backup encryption (configure action)", "flag": "--gpg-password " }, { "description": "Current LUKS password (configure/remove actions)", "flag": "--luks-password " }, { "description": "Backup file path or file name (restore-backup/delete-backup actions)", "flag": "--backup-file " }, { "description": "Force overwrite when a nuke password is already configured (configure action)", "flag": "--force-overwrite" }, { "description": "Skip interactive confirmation for remove action", "flag": "--force-remove" }, { "description": "Skip interactive confirmation for execute action", "flag": "--force-execute" }, { "description": "Read passwords from stdin as JSON instead of CLI args (avoids /proc exposure)", "flag": "--stdin-passwords" } ], "requires_sudo": true, "usage": "health-control luks-nuke [OPTIONS]" }, { "description": "Detect valid LUKS devices on the system", "examples": [ "sudo health-control luks-detect", "sudo health-control luks-detect --all-devices", "sudo health-control luks-detect --json" ], "name": "luks-detect", "options": [ { "description": "Check all block devices including loop devices", "flag": "--all-devices" } ], "requires_sudo": true, "usage": "health-control luks-detect [OPTIONS]" }, { "description": "Manage LUKS encrypted devices", "examples": [ "sudo health-control luks-manage --action list", "sudo health-control luks-manage --action unlock --device /dev/DEVICE", "sudo health-control luks-manage --action lock --device /dev/DEVICE" ], "name": "luks-manage", "options": [ { "default": "list", "description": "Action: add, remove, unlock, lock, list", "flag": "--action " }, { "description": "Device path", "flag": "--device " } ], "requires_sudo": true, "usage": "health-control luks-manage [OPTIONS]" }, { "description": "Advanced LUKS nuke configuration (emergency wipe)", "examples": [ "sudo health-control luks-nuke-advanced --device /dev/DEVICE --password ''", "sudo health-control luks-nuke-advanced --device /dev/DEVICE --json" ], "name": "luks-nuke-advanced", "options": [ { "description": "Device to configure nuke for", "flag": "--device ", "required": true }, { "description": "Nuke password (WARNING: will destroy data)", "flag": "--password " } ], "requires_sudo": true, "usage": "health-control luks-nuke-advanced [OPTIONS]" }, { "description": "Remove LUKS encryption from device", "examples": [ "sudo health-control luks-remove \"$LUKS_DEVICE\"", "sudo health-control luks-remove \"$LUKS_DEVICE\" --force" ], "name": "luks-remove", "options": [ { "description": "Device to remove LUKS from", "flag": "", "required": true }, { "description": "Force removal without confirmation", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control luks-remove [OPTIONS]" }, { "description": "Advanced LUKS device management", "examples": [ "sudo health-control luks-manage-advanced --action backup-header --device /dev/DEVICE --backup-file /tmp/header.backup", "sudo health-control luks-manage-advanced --action restore-header --device /dev/DEVICE --backup-file /tmp/header.backup", "sudo health-control luks-manage-advanced --action add-key --device /dev/DEVICE --key-file /tmp/newkey" ], "name": "luks-manage-advanced", "options": [ { "description": "Action: create, format, backup-header, restore-header, change-key, add-key, remove-key", "flag": "--action ", "required": true }, { "description": "Device path", "flag": "--device " }, { "description": "Key file path", "flag": "--key-file " }, { "description": "Backup file path", "flag": "--backup-file " } ], "requires_sudo": true, "usage": "health-control luks-manage-advanced [OPTIONS]" }, { "description": "Create Debian live-boot persistence media", "examples": [ "sudo health-control create-persistence", "sudo health-control create-persistence --size 8", "sudo health-control create-persistence --encrypted", "sudo health-control create-persistence --encrypted --size 8", "sudo health-control create-persistence --encrypted --password ''", "sudo health-control create-persistence --size 4 --output /tmp/persistence --json" ], "name": "create-persistence", "options": [ { "default": "4", "description": "Size in GB", "flag": "--size " }, { "description": "Enable encryption", "flag": "--encrypted" }, { "description": "Output file path or directory (live-boot defaults to a file named 'persistence')", "flag": "--output " }, { "description": "LUKS encryption password (INSECURE: visible in shell history! Use interactive mode instead)", "flag": "--password " } ], "requires_sudo": true, "usage": "health-control create-persistence [OPTIONS]" }, { "description": "Create persistence for other Linux distributions (Kali, Parrot, Tails)", "examples": [ "sudo # FULLY AUTOMATED - No manual mounting needed!", "sudo ", "sudo # RECOMMENDED: List devices first to see what's safe", "sudo health-control list-storage-devices", "sudo ā†’ Shows which devices are SAFE vs DANGEROUS", "sudo ", "sudo # Check if your device is safe", "sudo health-control usb-safety-check --device /dev/DEVICE", "sudo ā†’ Verifies device before formatting", "sudo ", "sudo # Unencrypted persistence for Kali Linux (AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type kali", "sudo ā†’ Confirms device selection", "sudo ā†’ Formats partition automatically", "sudo ā†’ Creates persistence.conf automatically", "sudo ā†’ Ready to use - NO manual mounting!", "sudo ", "sudo # Encrypted persistence for Parrot OS (FULLY AUTOMATED)", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type parrot --encrypted", "sudo ā†’ Password prompted securely (not visible in history)", "sudo ā†’ Confirms device selection", "sudo ā†’ Encrypts partition automatically", "sudo ā†’ Mounts, configures, unmounts automatically", "sudo ā†’ Everything automated with safety confirmations!", "sudo ", "sudo # Encrypted persistence for Tails with CLI password (INSECURE)", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type tails --encrypted --password ''", "sudo āš ļø WARNING: Password visible in shell history!", "sudo ", "sudo # Complete safe workflow (AUTOMATED)", "sudo health-control list-storage-devices && \\", "sudo health-control usb-safety-check --device /dev/DEVICE && \\", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type kali --encrypted", "sudo ā†’ Entire workflow automated - just type YES when prompted!", "sudo ", "sudo # With JSON output", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type kali --encrypted --json" ], "name": "create-persistence-other-os", "options": [ { "description": "Target partition device (e.g., /dev/DEVICE)", "flag": "--device ", "required": true }, { "description": "Operating system type: kali, parrot, or tails", "flag": "--os-type ", "required": true }, { "description": "Enable LUKS encryption", "flag": "--encrypted" }, { "description": "LUKS encryption password (INSECURE: visible in shell history! Use interactive mode instead)", "flag": "--password " }, { "description": "Skip the interactive device confirmation - required for non-interactive use (dashboard, scripts, --json)", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control create-persistence-other-os [OPTIONS]" }, { "description": "Check storage encryption status", "examples": [ "sudo # Check overall system encryption status", "sudo health-control encryption-status", "sudo ā†’ Shows: LUKS devices, encrypted filesystems, swap encryption", "sudo ā†’ Shows: Home directory encryption, full disk encryption status", "sudo ā†’ Reports: Encryption count summary (X/Y devices encrypted)", "sudo ā†’ Lists: Active encrypted containers and their mount points", "sudo ", "sudo # Typical output includes:", "sudo # - LUKS devices: /dev/DEVICE (/, 120 GB), /dev/OTHER_DEVICE (backup, 500 GB)", "sudo # - Encrypted swap: Yes (dm-crypt)", "sudo # - Home encryption: Yes (LUKS)", "sudo # - Full disk encryption: Yes (all partitions encrypted)", "sudo # - Encryption strength: AES-256-XTS", "sudo ", "sudo # JSON output for monitoring/scripting", "sudo health-control encryption-status --json", "sudo ā†’ Structured data: luks_devices[], encrypted_filesystems[]", "sudo ā†’ Boolean flags: home_encryption, swap_encrypted, full_disk_encryption", "sudo ā†’ Device details: cipher, key_size, device_path, mount_point, size", "sudo ā†’ Use in monitoring scripts for encryption compliance" ], "name": "encryption-status", "options": [], "requires_sudo": true, "usage": "health-control encryption-status [OPTIONS]" }, { "description": "Create encrypted container", "examples": [ "sudo # Create encrypted container (default: ext4, 1GB)", "sudo health-control container-create --path /tmp/secure.img", "sudo ā†’ Size: 1024 MB (default)", "sudo ā†’ Filesystem: ext4 (default)", "sudo ā†’ Creates sparse file (doesn't use full size immediately)", "sudo ā†’ Ready to mount and use", "sudo ", "sudo # Create large LUKS encrypted container", "sudo health-control container-create --path /secure/data.img --size 5000 --fs-type luks", "sudo ā†’ Size: 5000 MB (5 GB)", "sudo ā†’ Prompts for strong password (8+ chars recommended)", "sudo ā†’ Uses cryptsetup for LUKS2 format", "sudo ā†’ Hardware crypto acceleration if available", "sudo ", "sudo # Create VeraCrypt compatible container", "sudo health-control container-create --path /backup/portable.img --size 2048 --fs-type veracrypt", "sudo ā†’ Cross-platform compatibility (Windows, Mac, Linux)", "sudo ā†’ Can be opened with VeraCrypt GUI", "sudo ā†’ Good for external backup drives", "sudo ", "sudo # Filesystem types explained:", "sudo # --fs-type ext4:", "sudo # - Standard Linux filesystem (fastest)", "sudo # - No encryption by default", "sudo # - Best for temporary/non-sensitive data", "sudo ", "sudo # --fs-type luks:", "sudo # - LUKS2 encrypted container (RECOMMENDED for sensitive data)", "sudo # - AES-256-XTS encryption", "sudo # - Linux native, best performance", "sudo # - Requires password to mount", "sudo ", "sudo # --fs-type veracrypt:", "sudo # - VeraCrypt compatible (cross-platform)", "sudo # - Works on Windows, Mac, Linux", "sudo # - Slightly slower than LUKS", "sudo # - Good for portability", "sudo ", "sudo # Size guidelines:", "sudo # Small (100-500 MB): Documents, passwords, keys", "sudo # Medium (500-2000 MB): Photos, code projects", "sudo # Large (2000-10000 MB): Videos, backups, archives", "sudo # Very Large (10000+ MB): Full system backups" ], "name": "container-create", "options": [ { "description": "Container file path", "flag": "--path ", "required": true }, { "default": "1024", "description": "Size in MB", "flag": "--size " }, { "default": "ext4", "description": "Filesystem type: ext4, luks, veracrypt", "flag": "--fs-type " } ], "requires_sudo": true, "usage": "health-control container-create [OPTIONS]" }, { "description": "Mount encrypted container", "examples": [ "sudo # Mount encrypted container (password prompted securely)", "sudo health-control container-mount --container /path/to/secure.img --mount-point /mnt/secure", "sudo ā†’ Prompts for LUKS password (not visible, not logged)", "sudo ā†’ Creates /mnt/secure automatically if it doesn't exist", "sudo ā†’ Opens LUKS device with cryptsetup", "sudo ā†’ Mounts to /mnt/secure/ - ready to use", "sudo ", "sudo # Complete workflow: create ā†’ mount ā†’ use ā†’ unmount", "sudo ", "sudo # Step 1: Create encrypted container", "sudo health-control container-create --path /tmp/data.img --size 500 --fs-type luks", "sudo ", "sudo # Step 2: Mount container", "sudo health-control container-mount --container /tmp/data.img --mount-point /mnt/data", "sudo # Enter password when prompted", "sudo ", "sudo # Step 3: Use the container (copy files, edit, etc.)", "sudo cp -r /sensitive/documents /mnt/data/", "sudo echo 'secret data' > /mnt/data/confidential.txt", "sudo ", "sudo # Step 4: Unmount when done", "sudo health-control container-unmount --mount-point /mnt/data", "sudo ", "sudo # āœ… Complete encrypted container lifecycle!", "sudo # āœ… Data encrypted at rest, decrypted only when mounted", "sudo # āœ… Mount point automatically created and cleaned up" ], "name": "container-mount", "options": [ { "description": "Container file path", "flag": "--container ", "required": true }, { "description": "Mount point directory", "flag": "--mount-point ", "required": true } ], "requires_sudo": true, "usage": "health-control container-mount [OPTIONS]" }, { "description": "Unmount encrypted container", "examples": [ "sudo # Safely unmount encrypted container", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo ā†’ Unmounts filesystem from /mnt/secure", "sudo ā†’ Closes LUKS mapper device automatically", "sudo ā†’ Cleans up mount point (removes directory)", "sudo ā†’ āš ļø Close all files in /mnt/secure BEFORE unmounting!", "sudo ", "sudo # Check if anything is using the mount before unmounting", "sudo lsof +D /mnt/secure # List open files in mount point", "sudo # If files are open, close them first, then:", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo ", "sudo # Error handling: If unmount fails due to busy device", "sudo # 1. Check for open files:", "sudo lsof +D /mnt/secure", "sudo # 2. Kill processes using the mount:", "sudo fuser -km /mnt/secure # Kill processes (use with caution!)", "sudo # 3. Try unmounting again:", "sudo health-control container-unmount --mount-point /mnt/secure", "sudo ", "sudo # Safe workflow: Always unmount before system shutdown", "sudo # 1. Copy files out of container", "sudo # 2. Close all applications accessing the mount", "sudo # 3. Unmount container", "sudo # 4. Container is now encrypted and safe to store/transport" ], "name": "container-unmount", "options": [ { "description": "Mount point directory", "flag": "--mount-point ", "required": true } ], "requires_sudo": true, "usage": "health-control container-unmount [OPTIONS]" } ] }, { "category": "Security Tools", "commands": [ { "description": "Quick rootkit scan (fast, essential checks)", "examples": [ "sudo health-control rootkit-scan", "sudo health-control rootkit-scan --json" ], "name": "rootkit-scan", "options": [], "requires_sudo": true, "usage": "health-control rootkit-scan [OPTIONS]" }, { "description": "Check Kloak keyboard anonymization status", "examples": [ "health-control kloak-status", "health-control kloak-status --json" ], "name": "kloak-status", "options": [], "requires_sudo": false, "usage": "health-control kloak-status [OPTIONS]" }, { "description": "Enable Kloak keyboard anonymization", "examples": [ "sudo health-control kloak-enable", "sudo health-control kloak-enable --json" ], "name": "kloak-enable", "options": [], "requires_sudo": true, "usage": "health-control kloak-enable [OPTIONS]" }, { "description": "Disable Kloak keyboard anonymization", "examples": [ "sudo health-control kloak-disable", "sudo health-control kloak-disable --json" ], "name": "kloak-disable", "options": [], "requires_sudo": true, "usage": "health-control kloak-disable [OPTIONS]" }, { "description": "Configure Kloak keystroke anonymization settings", "examples": [ "sudo health-control kloak-configure --max-delay 100", "sudo health-control kloak-configure --rescue-delay 20 --startup-delay 100", "sudo health-control kloak-configure --max-delay 100 --verbose --json" ], "name": "kloak-configure", "options": [ { "description": "Kloak rescue delay in milliseconds", "flag": "--rescue-delay " }, { "description": "Kloak startup delay in milliseconds", "flag": "--startup-delay " }, { "description": "Kloak maximum keystroke delay in milliseconds", "flag": "--max-delay " }, { "description": "Enable Kloak verbose logging", "flag": "--verbose" }, { "description": "Keyboard input device passed to Kloak", "flag": "--device " } ], "requires_sudo": true, "usage": "health-control kloak-configure [OPTIONS]" }, { "description": "Set Kloak event processing mode", "examples": [ "sudo health-control kloak-event-mode --mode raw", "sudo health-control kloak-event-mode --mode normal", "sudo health-control kloak-event-mode --mode raw --json" ], "name": "kloak-event-mode", "options": [ { "description": "Event mode: raw or normal", "flag": "--mode ", "required": true } ], "requires_sudo": true, "usage": "health-control kloak-event-mode [OPTIONS]" }, { "description": "Show Kloak keystroke anonymization statistics", "examples": [ "health-control kloak-stats", "health-control kloak-stats --json" ], "name": "kloak-stats", "options": [], "requires_sudo": false, "usage": "health-control kloak-stats [OPTIONS]" }, { "description": "Update AIDE database after legitimate changes", "examples": [ "sudo health-control aide-update", "sudo health-control aide-update --accept-changes", "sudo health-control aide-update --json" ], "name": "aide-update", "options": [ { "description": "Accept all detected changes and update baseline", "flag": "--accept-changes" } ], "requires_sudo": true, "usage": "health-control aide-update [OPTIONS]" }, { "description": "Check file integrity with AIDE", "examples": [ "sudo health-control aide-check", "sudo health-control aide-check --json" ], "name": "aide-check", "options": [], "requires_sudo": true, "usage": "health-control aide-check [OPTIONS]" }, { "description": "Initialize AIDE database for file integrity monitoring", "examples": [ "sudo health-control aide-init", "sudo health-control aide-init --config ./aide.conf", "sudo health-control aide-init --timeout 7200", "sudo health-control aide-init --background", "sudo health-control aide-init --json" ], "name": "aide-init", "options": [ { "description": "Path to AIDE configuration file", "flag": "--config " }, { "description": "Timeout in seconds (default: 3600 - 1 hour)", "flag": "--timeout " }, { "description": "Run AIDE initialization in background and return immediately", "flag": "--background" } ], "requires_sudo": true, "usage": "health-control aide-init [OPTIONS]" }, { "description": "Reinitialize AIDE database (reset baseline)", "examples": [ "sudo health-control aide-reinit", "sudo health-control aide-reinit --force", "sudo health-control aide-reinit --background --timeout 7200 --json", "sudo health-control aide-reinit --json" ], "name": "aide-reinit", "options": [ { "description": "Force reinitialization without confirmation", "flag": "--force" }, { "description": "Timeout in seconds for AIDE initialization (default: 3600)", "flag": "--timeout " }, { "description": "Run AIDE reinitialization in background and return immediately", "flag": "--background" } ], "requires_sudo": true, "usage": "health-control aide-reinit [OPTIONS]" }, { "description": "Scan specific directory with AIDE", "examples": [ "sudo health-control aide-scan-dir ./config", "sudo health-control aide-scan-dir /usr/bin --recursive", "sudo health-control aide-scan-dir /home --json" ], "name": "aide-scan-dir", "options": [ { "description": "Directory path to scan", "flag": "", "required": true }, { "description": "Scan recursively", "flag": "-r, --recursive" } ], "requires_sudo": true, "usage": "health-control aide-scan-dir [OPTIONS]" } ] }, { "category": "Storage & USB Security", "commands": [ { "description": "List all storage devices with safety information for persistence operations", "examples": [ "sudo # List all storage devices with safety indicators", "sudo health-control list-storage-devices", "sudo ā†’ Shows which devices are safe (USB) vs dangerous (system)", "sudo ", "sudo # Include all devices (loop, ram, etc)", "sudo health-control list-storage-devices --all", "sudo ", "sudo # JSON output for scripting", "sudo health-control list-storage-devices --json", "sudo ", "sudo # Before creating persistence (recommended workflow)", "sudo health-control list-storage-devices && \\", "sudo health-control create-persistence-other-os --device /dev/DEVICE --os-type kali" ], "name": "list-storage-devices", "options": [ { "description": "Include all devices (loop, ram, etc)", "flag": "--all" } ], "requires_sudo": true, "usage": "health-control list-storage-devices [OPTIONS]" }, { "description": "Check if a device is safe for persistence/formatting operations", "examples": [ "sudo # Check if device is safe for persistence", "sudo health-control usb-safety-check --device /dev/DEVICE", "sudo ā†’ Returns: SAFE, CAUTION, or DANGER with details", "sudo ", "sudo # Check system drive (will warn)", "sudo health-control usb-safety-check --device /dev/DEVICE", "sudo ā†’ Shows why device is dangerous (system drive)", "sudo ", "sudo # JSON output for scripting", "sudo health-control usb-safety-check --device /dev/DEVICE --json" ], "name": "usb-safety-check", "options": [ { "description": "Device to check (e.g., /dev/DEVICE)", "flag": "--device ", "required": true } ], "requires_sudo": true, "usage": "health-control usb-safety-check [OPTIONS]" } ] }, { "category": "Storage Security", "commands": [ { "description": "Securely wipe storage devices and free space", "examples": [ "sudo health-control storage-wipe --free-space", "sudo health-control storage-wipe --device /dev/DEVICE --json", "sudo health-control storage-wipe --device /dev/DEVICE --allow-root-device --json" ], "name": "storage-wipe", "options": [ { "description": "Storage device to wipe", "flag": "--device " }, { "default": "3", "description": "Number of overwrite passes (default: 3)", "flag": "--passes " }, { "description": "Wipe free space on all mounted filesystems", "flag": "--free-space" }, { "description": "Allow wiping the block device that backs the running root filesystem. WITHOUT this flag the wipe is refused when the target is (or contains) the active root device, preventing accidental destruction of the live system.", "flag": "--allow-root-device" } ], "requires_sudo": true, "usage": "health-control storage-wipe [OPTIONS]" }, { "description": "Encrypt a storage device", "examples": [ "sudo health-control storage-encrypt --device /dev/DEVICE", "sudo health-control storage-encrypt --device /dev/DEVICE --json" ], "name": "storage-encrypt", "options": [ { "description": "Device to encrypt", "flag": "--device ", "required": true } ], "requires_sudo": true, "usage": "health-control storage-encrypt [OPTIONS]" }, { "description": "Optimize encryption performance and security settings", "examples": [ "sudo # Understanding encryption performance profiles", "sudo ", "sudo # Benchmark all ciphers and show recommendations (dry-run, no changes)", "sudo health-control encryption-tune --profile performance --benchmark", "sudo ā†’ Benchmarks all available ciphers", "sudo ā†’ Recommends fastest cipher for your hardware", "sudo ā†’ Shows throughput in MB/s", "sudo ā†’ No changes applied (dry-run mode)", "sudo ", "sudo # Apply performance optimizations", "sudo health-control encryption-tune --profile performance --apply", "sudo ā†’ Sets: aes-xts-plain64 cipher, 256-bit key", "sudo ā†’ Optimizes: I/O scheduler (deadline), queue depth (256)", "sudo ā†’ Enables hardware crypto acceleration", "sudo ā†’ May require reboot for full effect", "sudo ", "sudo # Security-focused tuning (paranoid mode)", "sudo health-control encryption-tune --profile security --iter-time 5000 --apply", "sudo ā†’ Maximizes key derivation time (slower unlock, more secure)", "sudo ā†’ Uses strongest available cipher", "sudo ā†’ 5000ms iteration time (vs 2000ms default)", "sudo ā†’ Recommended for high-security environments", "sudo ", "sudo # Balanced profile (default)", "sudo health-control encryption-tune --profile balanced", "sudo ā†’ Good balance between performance and security", "sudo ā†’ aes-xts-plain64 with 256-bit key", "sudo ā†’ Standard iteration time (2000ms)", "sudo ā†’ Shows recommendations without applying (add --apply to implement)", "sudo ", "sudo # Device-specific tuning for external drive", "sudo health-control encryption-tune --device /dev/DEVICE --cipher aes-xts-plain64 --key-size 512", "sudo ā†’ Applies settings to specific device only", "sudo ā†’ 512-bit key for maximum security", "sudo ā†’ Requires unlocking and reformatting (data loss!)", "sudo ", "sudo # Check current tuning status", "sudo health-control encryption-tune", "sudo ā†’ Shows current encryption settings", "sudo ā†’ Shows cipher, key size, iteration time", "sudo ā†’ No changes made (default dry-run)", "sudo ", "sudo # JSON output for scripting", "sudo health-control encryption-tune --json", "sudo ā†’ Structured output with recommendations", "sudo ā†’ Cipher benchmarks and current settings" ], "name": "encryption-tune", "options": [ { "default": "balanced", "description": "Optimization profile: performance, security, balanced", "flag": "--profile " }, { "description": "Encryption cipher: aes-xts-plain64, chacha20-poly1305, aes-gcm-random", "flag": "--cipher " }, { "description": "Key size in bits: 128, 256, 512", "flag": "--key-size " }, { "description": "PBKDF2 iteration time in milliseconds", "flag": "--iter-time " }, { "description": "Target device or container path", "flag": "--device " }, { "description": "Run encryption benchmark before applying settings", "flag": "--benchmark" }, { "description": "Apply tuning recommendations (dry-run by default)", "flag": "--apply" } ], "requires_sudo": true, "usage": "health-control encryption-tune [OPTIONS]" } ] }, { "category": "System Control", "commands": [ { "description": "Get the current hostname", "examples": [ "health-control get-hostname", "health-control get-hostname --json" ], "name": "get-hostname", "options": [], "requires_sudo": false, "usage": "health-control get-hostname" }, { "description": "Change hostname (prompts for new hostname)", "examples": [ "sudo health-control change-hostname", "sudo health-control change-hostname new-hostname", "sudo health-control change-hostname --json" ], "name": "change-hostname", "options": [ { "description": "New hostname to set", "flag": "" } ], "requires_sudo": true, "usage": "health-control change-hostname [OPTIONS]" }, { "description": "List available hostnames by category", "examples": [ "health-control list-hostnames", "health-control list-hostnames --category all", "health-control list-hostnames --category windows", "health-control list-hostnames --category linux", "health-control list-hostnames --category apple", "health-control list-hostnames --category network", "health-control list-hostnames --category mobile", "health-control list-hostnames --category iot", "health-control list-hostnames --category gaming", "health-control list-hostnames --category fiction", "health-control list-hostnames --json" ], "name": "list-hostnames", "options": [ { "description": "Category to list (all, windows, linux, apple, network, mobile, iot, gaming, fiction, business)", "flag": "-c, --category " } ], "requires_sudo": false, "usage": "health-control list-hostnames [OPTIONS]" }, { "description": "Set a random hostname from a specific category", "examples": [ "sudo health-control set-random-hostname-category", "sudo health-control set-random-hostname-category --category windows", "sudo health-control set-random-hostname-category --category linux", "sudo health-control set-random-hostname-category --category apple", "sudo health-control set-random-hostname-category --category network", "sudo health-control set-random-hostname-category --category fiction --json" ], "name": "set-random-hostname-category", "options": [ { "description": "Category to select from (all, windows, linux, apple, network, mobile, iot, gaming, fiction, business)", "flag": "-c, --category " } ], "requires_sudo": true, "usage": "health-control set-random-hostname-category [OPTIONS]" }, { "description": "Get the actual logged-in user (handles sudo correctly)", "examples": [ "health-control get-logged-user", "health-control get-logged-user --json", "sudo health-control get-logged-user", "sudo health-control get-logged-user --json-pretty" ], "name": "get-logged-user", "options": [], "requires_sudo": false, "usage": "health-control get-logged-user [OPTIONS]" }, { "description": "Show current system timezone", "examples": [ "health-control show-timezone", "health-control show-timezone --json" ], "name": "show-timezone", "options": [], "requires_sudo": false, "usage": "health-control show-timezone [OPTIONS]" }, { "description": "Sync timezone based on IP geolocation", "examples": [ "sudo health-control sync-timezone", "sudo health-control sync-timezone --json" ], "name": "sync-timezone", "options": [], "requires_sudo": true, "usage": "health-control sync-timezone [OPTIONS]" }, { "description": "Show timezone based on current IP location", "examples": [ "health-control show-remote-timezone", "health-control show-remote-timezone --json" ], "name": "show-remote-timezone", "options": [], "requires_sudo": false, "usage": "health-control show-remote-timezone [OPTIONS]" }, { "description": "Set system timezone", "examples": [ "sudo health-control set-timezone --timezone America/New_York", "sudo health-control set-timezone --timezone Europe/London", "sudo health-control set-timezone --timezone Asia/Tokyo --json" ], "name": "set-timezone", "options": [ { "description": "Timezone to set (e.g., America/New_York)", "flag": "--timezone ", "required": true } ], "requires_sudo": true, "usage": "health-control set-timezone [OPTIONS]" }, { "description": "List available timezones by category", "examples": [ "health-control list-timezones", "health-control list-timezones --category all", "health-control list-timezones --category africa", "health-control list-timezones --category americas", "health-control list-timezones --category asia", "health-control list-timezones --category europe", "health-control list-timezones --category australia", "health-control list-timezones --category pacific", "health-control list-timezones --category utc", "health-control list-timezones --json" ], "name": "list-timezones", "options": [ { "description": "Category to list (all, africa, americas, asia, europe, australia, pacific, utc)", "flag": "-c, --category " } ], "requires_sudo": false, "usage": "health-control list-timezones [OPTIONS]" }, { "description": "Set a random timezone from a specific category", "examples": [ "sudo health-control set-random-timezone", "sudo health-control set-random-timezone --category americas", "sudo health-control set-random-timezone --category europe", "sudo health-control set-random-timezone --category asia", "sudo health-control set-random-timezone --category africa", "sudo health-control set-random-timezone --category pacific --json" ], "name": "set-random-timezone", "options": [ { "description": "Category/region to select from (all, africa, americas, asia, europe, australia, pacific, utc)", "flag": "-c, --category " } ], "requires_sudo": true, "usage": "health-control set-random-timezone [OPTIONS]" }, { "description": "Play notification sound", "examples": [ "sudo health-control play-sound", "sudo health-control play-sound --sound alert", "sudo health-control play-sound success", "sudo health-control play-sound warning -m mp3", "sudo health-control play-sound alert --debug" ], "name": "play-sound", "options": [ { "description": "Sound type to play: alert, success, warning, notification", "flag": "" }, { "description": "Sound type (alternative to positional)", "flag": "--sound " }, { "description": "Sound format (mp3, wav, etc.)", "flag": "-m, --format " }, { "description": "Enable debug output", "flag": "--debug" } ], "requires_sudo": true, "usage": "health-control play-sound [OPTIONS]" }, { "description": "Send desktop notification", "examples": [ "health-control notify --message \"Security check complete\"", "health-control notify --message \"Hello from Kodachi\"", "health-control notify --message \"Alert\" --body \"VPN connected\"", "health-control notify --message \"Warning\" --urgency critical --duration 30", "health-control notify --message \"Update\" --notify-icon \"/path/to/icon.png\"" ], "name": "notify", "options": [ { "description": "Notification title, the bold first line", "flag": "--message ", "required": true }, { "default": "empty", "description": "Notification body, the smaller second line", "flag": "--body <TEXT>", "required": false }, { "default": "desktop default", "description": "How long the notification stays on screen", "flag": "--duration <SECONDS>", "required": false }, { "default": "normal", "description": "Urgency level: low, normal or critical", "flag": "--urgency <LEVEL>", "required": false }, { "description": "Path to the icon shown next to the notification", "flag": "--notify-icon <PATH>", "required": false } ], "requires_sudo": false, "usage": "health-control notify [OPTIONS]" } ] }, { "category": "System Information", "commands": [ { "description": "Display comprehensive system information", "examples": [ "sudo health-control offline-info-system", "sudo health-control offline-info-system --json" ], "name": "offline-info-system", "options": [], "requires_sudo": true, "usage": "health-control offline-info-system [OPTIONS]" }, { "description": "Display hardware information", "examples": [ "sudo health-control offline-info-hardware", "sudo health-control offline-info-hardware --json" ], "name": "offline-info-hardware", "options": [], "requires_sudo": true, "usage": "health-control offline-info-hardware [OPTIONS]" }, { "description": "Display process information", "examples": [ "sudo health-control offline-info-process", "sudo health-control offline-info-process --json" ], "name": "offline-info-process", "options": [], "requires_sudo": true, "usage": "health-control offline-info-process [OPTIONS]" }, { "description": "Display security and encryption status", "examples": [ "sudo health-control offline-info-security", "sudo health-control offline-info-security --json" ], "name": "offline-info-security", "options": [], "requires_sudo": true, "usage": "health-control offline-info-security [OPTIONS]" }, { "description": "Display network information", "examples": [ "sudo health-control offline-info-network", "sudo health-control offline-info-network --json" ], "name": "offline-info-network", "options": [], "requires_sudo": true, "usage": "health-control offline-info-network [OPTIONS]" }, { "description": "Display user information", "examples": [ "sudo health-control offline-info-user", "sudo health-control offline-info-user --json" ], "name": "offline-info-user", "options": [], "requires_sudo": true, "usage": "health-control offline-info-user [OPTIONS]" }, { "description": "Display storage information", "examples": [ "sudo health-control offline-info-storage", "sudo health-control offline-info-storage --json" ], "name": "offline-info-storage", "options": [], "requires_sudo": true, "usage": "health-control offline-info-storage [OPTIONS]" }, { "description": "Display system services information", "examples": [ "sudo health-control offline-info-services", "sudo health-control offline-info-services --json" ], "name": "offline-info-services", "options": [], "requires_sudo": true, "usage": "health-control offline-info-services [OPTIONS]" }, { "description": "Display all system information", "examples": [ "sudo health-control offline-info-all", "sudo health-control offline-info-all --json" ], "name": "offline-info-all", "options": [], "requires_sudo": true, "usage": "health-control offline-info-all [OPTIONS]" }, { "description": "Ping a random privacy-respecting target and return latency", "examples": [ "health-control ping", "health-control ping --json" ], "name": "ping", "options": [], "requires_sudo": false, "usage": "health-control ping [OPTIONS]" }, { "description": "Get process uptime for VPN or Tor", "examples": [ "health-control process-age --process vpn", "health-control process-age --process tor", "health-control process-age --process vpn --json", "health-control process-age --process tor --json" ], "name": "process-age", "options": [ { "description": "Process name: 'vpn' or 'tor'", "flag": "--process <NAME>", "required": true } ], "requires_sudo": false, "usage": "health-control process-age [OPTIONS]" } ] }, { "category": "System Information & Offline Actions", "commands": [ { "description": "Enable/disable/check Bluetooth service", "examples": [ "sudo health-control offline-bluetooth --action disable", "sudo health-control offline-bluetooth --action enable", "sudo health-control offline-bluetooth --action check --json" ], "name": "offline-bluetooth", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-bluetooth [OPTIONS]" }, { "description": "Manage WiFi connectivity", "examples": [ "sudo health-control offline-wifi --action disable", "sudo health-control offline-wifi --action enable", "sudo health-control offline-wifi --action check --json" ], "name": "offline-wifi", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-wifi [OPTIONS]" }, { "description": "Manage USB storage devices", "examples": [ "sudo health-control offline-usb-storage --action disable", "sudo health-control offline-usb-storage --action enable", "sudo health-control offline-usb-storage --action check --json" ], "name": "offline-usb-storage", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-usb-storage [OPTIONS]" }, { "description": "Manage webcam device", "examples": [ "sudo health-control offline-webcam --action disable", "sudo health-control offline-webcam --action enable", "sudo health-control offline-webcam --action check --json" ], "name": "offline-webcam", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-webcam [OPTIONS]" }, { "description": "Manage microphone device", "examples": [ "sudo health-control offline-microphone --action disable", "sudo health-control offline-microphone --action enable", "sudo health-control offline-microphone --action check --json" ], "name": "offline-microphone", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-microphone [OPTIONS]" }, { "description": "Manage system logging", "examples": [ "sudo health-control offline-systemlogs --action disable", "sudo health-control offline-systemlogs --action enable", "sudo health-control offline-systemlogs --action check --json" ], "name": "offline-systemlogs", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-systemlogs [OPTIONS]" }, { "description": "Manage CUPS printing service", "examples": [ "sudo health-control offline-cups --action disable # Disable printer service (CUPS)", "sudo health-control offline-cups --action enable # Enable printer service (CUPS)", "sudo health-control offline-cups --action check --json" ], "name": "offline-cups", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-cups [OPTIONS]" }, { "description": "Manage NetworkManager service", "examples": [ "sudo health-control offline-networkmanager --action disable", "sudo health-control offline-networkmanager --action enable", "sudo health-control offline-networkmanager --action check --json" ], "name": "offline-networkmanager", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-networkmanager [OPTIONS]" }, { "description": "Manage NumLock configuration", "examples": [ "sudo health-control offline-numlock --action enable", "sudo health-control offline-numlock --action disable", "sudo health-control offline-numlock --action check --json" ], "name": "offline-numlock", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-numlock [OPTIONS]" }, { "description": "Manage command history", "examples": [ "sudo health-control offline-cmdhistory --action disable", "sudo health-control offline-cmdhistory --action enable", "sudo health-control offline-cmdhistory --action check --json" ], "name": "offline-cmdhistory", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-cmdhistory [OPTIONS]" }, { "description": "Enable/disable/check auto-login functionality", "examples": [ "sudo health-control offline-autologin --action disable", "sudo health-control offline-autologin --action enable", "sudo health-control offline-autologin --action check --json" ], "name": "offline-autologin", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-autologin [OPTIONS]" }, { "description": "Manage screen locking", "examples": [ "sudo health-control offline-screen-lock --action enable", "sudo health-control offline-screen-lock --action disable", "sudo health-control offline-screen-lock --action check --json" ], "name": "offline-screen-lock", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-screen-lock [OPTIONS]" }, { "description": "Enable/disable/check file descriptor limits", "examples": [ "sudo health-control offline-fdlimit --action enable --soft-limit 1024 --hard-limit 4096", "sudo health-control offline-fdlimit --action disable", "sudo health-control offline-fdlimit --action check --json" ], "name": "offline-fdlimit", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true }, { "description": "Soft limit value", "flag": "--soft-limit <LIMIT>" }, { "description": "Hard limit value", "flag": "--hard-limit <LIMIT>" } ], "requires_sudo": true, "usage": "health-control offline-fdlimit [OPTIONS]" }, { "description": "Enable/disable/check network optimization", "examples": [ "sudo health-control offline-netoptimize --action enable", "sudo health-control offline-netoptimize --action disable", "sudo health-control offline-netoptimize --action check --json" ], "name": "offline-netoptimize", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-netoptimize [OPTIONS]" }, { "description": "Enable/disable/check BBR congestion control", "examples": [ "sudo health-control offline-bbr --action enable", "sudo health-control offline-bbr --action disable", "sudo health-control offline-bbr --action check --json" ], "name": "offline-bbr", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-bbr [OPTIONS]" }, { "description": "Enable/disable/check interface speed optimization", "examples": [ "sudo health-control offline-ifspeed --action enable --interface eth0 --speed 1000", "sudo health-control offline-ifspeed --action disable", "sudo health-control offline-ifspeed --action check --json", "sudo health-control offline-ifspeed --action enable --interface wlan0", "sudo health-control offline-ifspeed --action disable --interface eth0 --force" ], "name": "offline-ifspeed", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true }, { "description": "Network interface to configure (e.g., eth0, wlan0)", "flag": "--interface <INTERFACE>" }, { "description": "Interface speed in Mbps (e.g., 1000 for gigabit)", "flag": "--speed <SPEED>" }, { "description": "Allow enable/disable to touch the active default-route (management/SSH) interface", "flag": "--force" } ], "requires_sudo": true, "usage": "health-control offline-ifspeed [OPTIONS]" }, { "description": "Manage Avahi daemon service", "examples": [ "sudo health-control offline-avahi --action disable", "sudo health-control offline-avahi --action enable", "sudo health-control offline-avahi --action check --json" ], "name": "offline-avahi", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-avahi [OPTIONS]" }, { "description": "Manage ModemManager service", "examples": [ "sudo health-control offline-modem-manager --action disable", "sudo health-control offline-modem-manager --action enable", "sudo health-control offline-modem-manager --action check --json" ], "name": "offline-modem-manager", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-modem-manager [OPTIONS]" }, { "description": "Manage SSH daemon service", "examples": [ "sudo health-control offline-ssh --action disable", "sudo health-control offline-ssh --action enable", "sudo health-control offline-ssh --action check --json" ], "name": "offline-ssh", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-ssh [OPTIONS]" }, { "description": "Manage Apache web server service", "examples": [ "sudo health-control offline-apache --action disable", "sudo health-control offline-apache --action enable", "sudo health-control offline-apache --action check --json" ], "name": "offline-apache", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-apache [OPTIONS]" }, { "description": "Manage Nginx web server service", "examples": [ "sudo health-control offline-nginx --action disable", "sudo health-control offline-nginx --action enable", "sudo health-control offline-nginx --action check --json" ], "name": "offline-nginx", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-nginx [OPTIONS]" }, { "description": "Manage Docker container service", "examples": [ "sudo health-control offline-docker --action disable", "sudo health-control offline-docker --action enable", "sudo health-control offline-docker --action check --json" ], "name": "offline-docker", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-docker [OPTIONS]" }, { "description": "Manage MySQL database service", "examples": [ "sudo health-control offline-mysql --action disable", "sudo health-control offline-mysql --action enable", "sudo health-control offline-mysql --action check --json" ], "name": "offline-mysql", "options": [ { "description": "Action to perform: enable, disable, check", "flag": "--action <ACTION>", "required": true } ], "requires_sudo": true, "usage": "health-control offline-mysql [OPTIONS]" } ] }, { "category": "System Maintenance", "commands": [ { "description": "Enable automatic security updates", "examples": [ "sudo health-control auto-updates-enable", "sudo health-control auto-updates-enable --json" ], "name": "auto-updates-enable", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-enable [OPTIONS]" }, { "description": "Disable automatic security updates", "examples": [ "sudo health-control auto-updates-disable", "sudo health-control auto-updates-disable --json" ], "name": "auto-updates-disable", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-disable [OPTIONS]" }, { "description": "Check automatic updates status", "examples": [ "sudo health-control auto-updates-status", "sudo health-control auto-updates-status --json" ], "name": "auto-updates-status", "options": [], "requires_sudo": true, "usage": "health-control auto-updates-status [OPTIONS]" }, { "description": "Enable system maintenance settings", "examples": [ "sudo health-control system-maintenance-enable", "sudo health-control system-maintenance-enable --json" ], "name": "system-maintenance-enable", "options": [], "requires_sudo": true, "usage": "health-control system-maintenance-enable [OPTIONS]" }, { "description": "Disable system maintenance settings", "examples": [ "sudo health-control system-maintenance-disable", "sudo health-control system-maintenance-disable --json" ], "name": "system-maintenance-disable", "options": [], "requires_sudo": true, "usage": "health-control system-maintenance-disable [OPTIONS]" }, { "description": "Check system maintenance status", "examples": [ "health-control system-maintenance-status", "health-control system-maintenance-status --json" ], "name": "system-maintenance-status", "options": [], "requires_sudo": false, "usage": "health-control system-maintenance-status [OPTIONS]" }, { "description": "Enable password policy enforcement", "examples": [ "sudo health-control password-policy-enable", "sudo health-control password-policy-enable --json" ], "name": "password-policy-enable", "options": [], "requires_sudo": true, "usage": "health-control password-policy-enable [OPTIONS]" }, { "description": "Disable password policy enforcement", "examples": [ "sudo health-control password-policy-disable", "sudo health-control password-policy-disable --json" ], "name": "password-policy-disable", "options": [], "requires_sudo": true, "usage": "health-control password-policy-disable [OPTIONS]" }, { "description": "Check password policy status", "examples": [ "sudo health-control password-policy-status", "sudo health-control password-policy-status --json" ], "name": "password-policy-status", "options": [], "requires_sudo": true, "usage": "health-control password-policy-status [OPTIONS]" }, { "description": "Enable user security hardening", "examples": [ "sudo health-control user-security-enable", "sudo health-control user-security-enable --json" ], "name": "user-security-enable", "options": [], "requires_sudo": true, "usage": "health-control user-security-enable [OPTIONS]" }, { "description": "Disable user security hardening", "examples": [ "sudo health-control user-security-disable", "sudo health-control user-security-disable --json" ], "name": "user-security-disable", "options": [], "requires_sudo": true, "usage": "health-control user-security-disable [OPTIONS]" }, { "description": "Check user security status", "examples": [ "sudo health-control user-security-status", "sudo health-control user-security-status --json" ], "name": "user-security-status", "options": [], "requires_sudo": true, "usage": "health-control user-security-status [OPTIONS]" }, { "description": "Enable two-factor authentication", "examples": [ "sudo # WARNING: 2FA has known bugs with XFCE/LightDM login.", "sudo # Works reliably for SSH and sudo. Unreliable for XFCE login and the lock screen.", "sudo health-control 2fa-enable", "sudo health-control 2fa-enable --value $(id -un) --json", "sudo # Note: $(id -un) writes the current username into shell history." ], "name": "2fa-enable", "options": [ { "description": "Target user (optional, defaults to all users)", "flag": "--value <USERNAME>" } ], "requires_sudo": true, "usage": "health-control 2fa-enable [OPTIONS]" }, { "description": "Disable two-factor authentication", "examples": [ "sudo # Use this to recover if 2FA locked you out of the XFCE/LightDM login.", "sudo health-control 2fa-disable", "sudo health-control 2fa-disable --json" ], "name": "2fa-disable", "options": [], "requires_sudo": true, "usage": "health-control 2fa-disable [OPTIONS]" }, { "description": "Check two-factor authentication status", "examples": [ "# āš ļø WARNING: 2FA has known bugs with XFCE/LightDM login!", "# Works reliably for: SSH, sudo | Unreliable for: XFCE login, lock screen", "health-control 2fa-status", "health-control 2fa-status --json" ], "name": "2fa-status", "options": [], "requires_sudo": false, "usage": "health-control 2fa-status [OPTIONS]" }, { "description": "Check and install required packages", "examples": [ "sudo health-control check-and-install tor openvpn", "sudo health-control check-and-install rkhunter chkrootkit --json" ], "name": "check-and-install", "options": [ { "description": "Packages to check and install", "flag": "<PACKAGES>", "required": true } ], "requires_sudo": true, "usage": "health-control check-and-install [OPTIONS]" }, { "description": "Execute installation after checking dependencies", "examples": [ "sudo health-control check-and-install-do", "sudo health-control check-and-install-do --json" ], "name": "check-and-install-do", "options": [], "requires_sudo": true, "usage": "health-control check-and-install-do [OPTIONS]" }, { "description": "Clean up unnecessary packages", "examples": [ "sudo health-control package-cleanup", "sudo health-control package-cleanup --json" ], "name": "package-cleanup", "options": [], "requires_sudo": true, "usage": "health-control package-cleanup [OPTIONS]" }, { "description": "Clear system memory caches", "examples": [ "sudo health-control clear-cache", "sudo health-control clear-cache --level 1", "sudo health-control clear-cache --level 2", "sudo health-control clear-cache --level 3", "sudo health-control clear-cache --json" ], "name": "clear-cache", "options": [ { "default": "3", "description": "Cache level to clear (1, 2, or 3)", "flag": "--level <LEVEL>" } ], "requires_sudo": true, "usage": "health-control clear-cache [OPTIONS]" } ] }, { "category": "System Recovery", "commands": [ { "description": "Fix broken sudo permissions (uses pkexec/su, no sudo required)", "examples": [ "sudo health-control fix-sudo", "sudo health-control fix-sudo --json", "sudo # This command tries pkexec first, then su -c, to fix sudo without sudo" ], "name": "fix-sudo", "options": [], "requires_sudo": true, "usage": "health-control fix-sudo [OPTIONS]" }, { "description": "Check sudo installation status and permissions", "examples": [ "sudo health-control check-sudo", "sudo health-control check-sudo --json" ], "name": "check-sudo", "options": [], "requires_sudo": true, "usage": "health-control check-sudo [OPTIONS]" } ] }, { "category": "USB Security", "commands": [ { "description": "Check USB Guard protection status", "examples": [ "sudo health-control usb-status", "sudo health-control usb-status --json" ], "name": "usb-status", "options": [], "requires_sudo": true, "usage": "health-control usb-status [OPTIONS]" }, { "description": "Enable USB Guard protection", "examples": [ "sudo health-control usb-guard-enable", "sudo health-control usb-guard-enable --json" ], "name": "usb-guard-enable", "options": [], "requires_sudo": true, "usage": "health-control usb-guard-enable [OPTIONS]" }, { "description": "Disable USB Guard protection", "examples": [ "sudo health-control usb-guard-disable", "sudo health-control usb-guard-disable --json" ], "name": "usb-guard-disable", "options": [], "requires_sudo": true, "usage": "health-control usb-guard-disable [OPTIONS]" }, { "description": "Manage USB device policies", "examples": [ "sudo health-control usb-policy --action list", "sudo health-control usb-policy --action add --device-id 1234:5678 --allow", "sudo health-control usb-policy --action remove --device-id 1234:5678" ], "name": "usb-policy", "options": [ { "default": "list", "description": "Action: add, remove, list", "flag": "--action <ACTION>" }, { "description": "Device ID (vendor:product)", "flag": "--device-id <ID>" }, { "description": "Allow device", "flag": "--allow" } ], "requires_sudo": true, "usage": "health-control usb-policy [OPTIONS]" }, { "description": "Monitor USB device connections in real-time", "examples": [ "sudo health-control usb-monitor", "sudo health-control usb-monitor --duration 300", "sudo health-control usb-monitor --alert", "sudo health-control usb-monitor --block-unauthorized --log-only", "sudo health-control usb-monitor --json" ], "name": "usb-monitor", "options": [ { "default": "0", "description": "Monitoring duration in seconds (0 = infinite)", "flag": "--duration <SECONDS>" }, { "description": "Only log events, don't display them", "flag": "--log-only" }, { "description": "Alert on unauthorized devices", "flag": "--alert" }, { "description": "Automatically block unauthorized devices", "flag": "--block-unauthorized" } ], "requires_sudo": true, "usage": "health-control usb-monitor [OPTIONS]" }, { "description": "View USB device connection history", "examples": [ "sudo health-control usb-history", "sudo health-control usb-history --days 30", "sudo health-control usb-history --device-id 1234:5678", "sudo health-control usb-history --json" ], "name": "usb-history", "options": [ { "default": "7", "description": "Number of days of history to show", "flag": "--days <DAYS>" }, { "description": "Filter by specific device ID", "flag": "--device-id <ID>" } ], "requires_sudo": true, "usage": "health-control usb-history [OPTIONS]" }, { "description": "Manage USB device whitelist", "examples": [ "sudo # Find device IDs first (use lsusb)", "sudo lsusb # Shows vendor:product IDs (e.g., 1234:5678)", "sudo ā†’ Bus 003 Device 002: ID 1234:5678 Vendor Name Product Name", "sudo ", "sudo # List current whitelist", "sudo health-control usb-whitelist --action list", "sudo ā†’ Shows all whitelisted device IDs", "sudo ", "sudo # Add device to whitelist", "sudo health-control usb-whitelist --action add --device-id 1234:5678", "sudo ā†’ Device allowed to connect automatically", "sudo ", "sudo # Remove device from whitelist", "sudo health-control usb-whitelist --action remove --device-id 1234:5678", "sudo ā†’ Device will be blocked on next connection", "sudo ", "sudo # Export whitelist (backup configuration)", "sudo health-control usb-whitelist --action export --file ~/usb-whitelist-backup.json", "sudo ā†’ Saves whitelist to JSON file for backup/transfer", "sudo ", "sudo # Import whitelist (restore configuration)", "sudo health-control usb-whitelist --action import --file ~/usb-whitelist-backup.json", "sudo ā†’ Restores whitelist from JSON backup file", "sudo ", "sudo # Clear all whitelisted devices", "sudo health-control usb-whitelist --action clear", "sudo āš ļø WARNING: Removes ALL whitelisted devices - use with caution!", "sudo ", "sudo # Repair the base policy (composite mice/mics getting blocked?)", "sudo health-control usb-whitelist --action repair-policy", "sudo ā†’ Installs the canonical block-first policy if the on-disk one is", "sudo missing/empty or the legacy 'equals' policy; keeps your whitelist", "sudo and backs up the old file. Safe no-op if already current.", "sudo ", "sudo # JSON output for scripting", "sudo health-control usb-whitelist --action list --json" ], "name": "usb-whitelist", "options": [ { "default": "list", "description": "Action: add, remove, list, import, export, clear, repair-policy", "flag": "--action <ACTION>" }, { "description": "Device ID (vendor:product)", "flag": "--device-id <ID>" }, { "description": "File path for import/export", "flag": "--file <PATH>" } ], "requires_sudo": true, "usage": "health-control usb-whitelist [OPTIONS]" } ] } ], "description": "Health control system for Kodachi that includes network connectivity checks and system health monitoring", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "info", "description": "Set the log level for env_logger", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir <PATH>" }, { "description": "Set custom port number (1024-65535)", "flag": "--port <PORT>" }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level <LEVEL>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config <FILE>" }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout <SECS>" } ], "name": "health-control", "usage": "health-control [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 26, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:22.237415880Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Test network connectivity and configuration", "examples": [ { "command": "sudo health-control net-check", "description": "Full connectivity check: IP ping + DNS + HTTP probe", "expectedOutput": "NETWORK_STATUS: FULL_CONNECTIVITY (ping: <ms>, DNS: <ms>, HTTP: <ms>) (2)" }, { "command": "sudo health-control net-check --http", "description": "Full check via the extended HTTP path with per-target verbose reporting", "expectedOutput": "Full internet connectivity confirmed (IP, DNS and HTTP)" }, { "command": "sudo health-control net-check --json", "description": "Full connectivity check with JSON output for automation", "expectedOutput": "JSON payload with ping/DNS/HTTP timings and status_code 2 (FULL)" }, { "command": "sudo health-control net-check --http --json", "description": "Extended HTTP check path with JSON output", "expectedOutput": "JSON payload with per-target HTTP probe details" }, { "command": "sudo health-control net-check --ip-only", "description": "Check IP ping only, skip DNS lookups and HTTP probe", "expectedOutput": "NETWORK_STATUS: IP_ONLY_CONNECTIVITY (ping: <ms>) (1)", "notes": "Mutually exclusive with --domain-only and --http-only." }, { "command": "sudo health-control net-check --domain-only", "description": "Check DNS resolution only, skip IP ping and HTTP probe", "expectedOutput": "NETWORK_STATUS: DOMAIN_ONLY_CONNECTIVITY (DNS: <ms>) (4)", "notes": "Mutually exclusive with --ip-only and --http-only." }, { "command": "sudo health-control net-check --http-only", "description": "Check HTTP reachability only, skip IP ping and DNS lookups", "expectedOutput": "NETWORK_STATUS: HTTP_ONLY_CONNECTIVITY (HTTP: <ms>) (5)", "notes": "Mutually exclusive with --ip-only and --domain-only." }, { "command": "sudo health-control net-check --http-only --json", "description": "HTTP-only reachability check with JSON output", "expectedOutput": "JSON payload with HTTP probe latency and status_code 5 (HTTP_ONLY)" }, { "command": "sudo health-control net-check --timeout 15", "description": "Full connectivity check with a custom 15 second timeout", "expectedOutput": "NETWORK_STATUS: FULL_CONNECTIVITY (ping: <ms>, DNS: <ms>, HTTP: <ms>) (2)" }, { "command": "sudo health-control net-check --ip-only --json", "description": "IP-only ping check with JSON output", "expectedOutput": "JSON payload with ping latency and status_code 1 (IP_ONLY)" }, { "command": "sudo health-control net-check --domain-only --timeout 20", "description": "Domain-only DNS check with a custom 20 second timeout", "expectedOutput": "NETWORK_STATUS: DOMAIN_ONLY_CONNECTIVITY (DNS: <ms>) (4)" }, { "command": "sudo health-control list-ips", "description": "Show IPs used for connectivity testing", "expectedOutput": "List of test IP addresses" }, { "command": "sudo health-control list-domains", "description": "Show domains used for connectivity testing", "expectedOutput": "List of test domain names" }, { "command": "sudo health-control net-check-http --timeout 10", "description": "Dedicated HTTP connectivity probe with a custom timeout in seconds", "expectedOutput": "HTTP reachability result with per-target probe latency", "notes": "--timeout defaults to 10 seconds when omitted." } ], "id": "1_network_connectivity", "title": "Network Connectivity" }, { "description": "Block and unblock internet traffic", "examples": [ { "command": "sudo health-control block-internet", "description": "Block internet using auto-detected method (tries nftables, then iptables, then UFW, then interfaces)", "expectedOutput": "Internet blocked successfully", "notes": "Without --method specified, health-control automatically selects the best available method" }, { "command": "sudo health-control block-internet --method iptables", "description": "Block using iptables firewall rules", "expectedOutput": "Iptables rules applied successfully", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method nftables", "description": "Block using nftables firewall rules (preferred modern firewall)", "expectedOutput": "Nftables rules applied successfully", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method firewall", "description": "Block using UFW (Uncomplicated Firewall)", "expectedOutput": "UFW rules applied successfully", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method interfaces", "description": "Block by disabling network interfaces", "expectedOutput": "Network interfaces disabled successfully", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method all", "description": "Block using ALL methods (UFW, nftables, iptables, and interfaces)", "expectedOutput": "All blocking methods applied successfully", "notes": "Applies all available blocking methods for maximum security" }, { "command": "sudo health-control block-internet --allow-local", "description": "Block internet but allow local network traffic", "expectedOutput": "Internet blocked, local traffic allowed", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --json", "description": "Block internet with JSON output", "expectedOutput": "JSON formatted blocking status", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method iptables --allow-local --json", "description": "Block internet with iptables, allow local, JSON output", "expectedOutput": "JSON formatted blocking status with details", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control block-internet --method all --allow-local", "description": "Block using ALL methods but allow local network traffic", "expectedOutput": "All blocking methods applied, local traffic allowed", "notes": "DESTRUCTIVE TO CONNECTIVITY: this severs internet access for the whole machine, including whatever is running in the background (downloads, Tor circuits, VPN). Restore it with 'sudo health-control unblock-internet' or 'sudo health-control recover-internet'. --allow-local keeps LAN/loopback reachable so you do not lock yourself out of an SSH session." }, { "command": "sudo health-control unblock-internet", "description": "Unblock internet traffic", "expectedOutput": "Internet unblocked successfully" }, { "command": "sudo health-control unblock-internet --method nftables", "description": "Unblock using nftables specifically", "expectedOutput": "Internet unblocked using nftables" }, { "command": "sudo health-control unblock-internet --method iptables", "description": "Unblock using iptables specifically", "expectedOutput": "Internet unblocked using iptables" }, { "command": "sudo health-control unblock-internet --method firewall", "description": "Unblock using UFW specifically", "expectedOutput": "Internet unblocked using UFW" }, { "command": "sudo health-control unblock-internet --method all", "description": "Unblock ALL methods (clears UFW, nftables, iptables, and re-enables interfaces)", "expectedOutput": "All blocking methods cleared successfully", "notes": "Ensures complete restoration by clearing all possible blocks" }, { "command": "sudo health-control unblock-internet --json", "description": "Unblock internet with JSON output", "expectedOutput": "JSON formatted unblocking status" }, { "command": "sudo health-control block-ping", "description": "Block OUTBOUND ICMP echo-requests (ping) for both IPv4 and IPv6. Inserts a DROP rule in the iptables/ip6tables OUTPUT chain so this host can no longer ping out, while all normal TCP/UDP traffic (web, DNS, apps) keeps working", "expectedOutput": "ping block [ipv4]: blocked / ping block [ipv6]: blocked", "notes": "Equivalent to: sudo iptables -I OUTPUT -p icmp --icmp-type echo-request -j DROP AND sudo ip6tables -I OUTPUT -p ipv6-icmp --icmpv6-type echo-request -j DROP. Idempotent, running it twice does not add duplicate rules. Use this to reduce the host's network fingerprint (stealth) without killing connectivity." }, { "command": "sudo health-control block-ping --family ipv4", "description": "Block ping for IPv4 only (iptables), leave IPv6 ICMP untouched", "expectedOutput": "ping block [ipv4]: blocked", "notes": "Equivalent to: sudo iptables -I OUTPUT -p icmp --icmp-type echo-request -j DROP" }, { "command": "sudo health-control block-ping --family ipv6", "description": "Block ping for IPv6 only (ip6tables)", "expectedOutput": "ping block [ipv6]: blocked", "notes": "Equivalent to: sudo ip6tables -I OUTPUT -p ipv6-icmp --icmpv6-type echo-request -j DROP. Reports 'unavailable' if ip6tables is absent (IPv6 disabled)." }, { "command": "sudo health-control block-ping --json", "description": "Block ping with JSON output (per-family result envelope)", "expectedOutput": "{ \"results\": [{\"family\":\"ipv4\",\"state\":\"blocked\"}, ...] }" }, { "command": "sudo health-control unblock-ping", "description": "Unblock OUTBOUND ICMP echo-requests (ping), removes the DROP rule(s) for both IPv4 and IPv6 so this host can ping out again", "expectedOutput": "ping unblock [ipv4]: unblocked / ping unblock [ipv6]: unblocked", "notes": "Equivalent to: sudo iptables -D OUTPUT -p icmp --icmp-type echo-request -j DROP AND sudo ip6tables -D OUTPUT -p ipv6-icmp --icmpv6-type echo-request -j DROP. Removes every duplicate copy of the rule; safe to run when no rule exists (reports 'already-unblocked')." }, { "command": "sudo health-control unblock-ping --family ipv4", "description": "Unblock ping for IPv4 only", "expectedOutput": "ping unblock [ipv4]: unblocked", "notes": "Equivalent to: sudo iptables -D OUTPUT -p icmp --icmp-type echo-request -j DROP" }, { "command": "sudo health-control unblock-ping --family ipv6 --json", "description": "Unblock ping for IPv6 only with JSON output", "expectedOutput": "JSON envelope with ipv6 state" }, { "command": "sudo health-control internet-status", "description": "Check current internet blocking status", "expectedOutput": "Internet traffic status" }, { "command": "sudo health-control internet-status --json", "description": "Check if internet traffic is blocked with JSON output", "expectedOutput": "JSON formatted block status" }, { "command": "sudo health-control kill-switch-arm", "description": "ARM the emergency kill switch - raise the high-alert state flag (does not monitor; use a watch-guard for automatic response)", "expectedOutput": "Kill switch ARMED - high-alert state flag set", "notes": "HIGH-ALERT STATE FLAG. Arming does NOT monitor anything: it starts no watcher and no daemon, and nothing activates panic mode on its own. Firing the kill switch stays manual (kill-switch-activate).\nWhat arming actually does:\nā€¢ Records the high-alert state so other components can see it\nā€¢ While armed, tor-switch will not force firewall policies back to ACCEPT during detorrify, so an existing protective DROP policy is not silently torn down. Arming does not itself block any traffic\nā€¢ Is read by security scoring, but the comprehensive scorer credits it ONLY when egress is actually denied by the firewall. Armed without an enforced default-deny scores zero\nFor an automatic kill switch that reacts on its own, enable a watch-guard instead. It runs a daemon and blocks the network when the trigger fires, e.g. on a VPN tunnel drop:\n sudo health-control enable --type watch-guard --watch vpn --method nftables" }, { "command": "sudo health-control kill-switch-disarm", "description": "DISARM the kill switch (clear the high-alert flag)", "expectedOutput": "Kill switch DISARMED", "notes": "Clears the high-alert state flag (no monitoring was running). Use after the threat has passed or on a false alarm." }, { "command": "health-control kill-switch-status", "description": "Check if monitoring is armed/disarmed", "expectedOutput": "Shows armed status, trigger count, armed time", "notes": "READ-ONLY: Just displays current state, takes no action" }, { "command": "sudo health-control kill-switch-activate", "description": "IMMEDIATELY activate kill switch (default: medium panic)", "expectedOutput": "KILL SWITCH ACTIVATED - emergency procedures executed", "notes": "IMMEDIATE ACTION: Unlike 'arm', this executes panic NOW. Prompts for confirmation. Use --level soft/medium/hard" }, { "command": "sudo health-control panic-soft", "description": "IMMEDIATE soft panic (NO confirmation)", "expectedOutput": "Soft panic activated", "notes": "Actions: Kill network, clear clipboard (adaptive: wl-copy/xclip/xsel for Wayland/X11), lock screen. Reversible." }, { "command": "sudo health-control panic-medium", "description": "IMMEDIATE medium panic (WITH confirmation)", "expectedOutput": "Medium panic activated", "notes": "Actions: Kill network, terminate processes, clear memory, unmount devices. Requires manual restart." }, { "command": "sudo health-control panic-hard", "description": "IMMEDIATE hard panic with SHUTDOWN (WITH confirmation)", "expectedOutput": "Hard panic activated - system will shutdown", "notes": "CRITICAL: Wipes RAM, unmounts all, IMMEDIATE SHUTDOWN. IRREVERSIBLE!" }, { "command": "sudo health-control panic-recover", "description": "Recover from panic mode", "expectedOutput": "System recovered from panic mode", "notes": "Re-enables network, remounts volumes, restores services" }, { "command": "sudo health-control kill-network", "description": "āš ļø Immediately kill ALL network connectivity (emergency cut-off)", "expectedOutput": "All network interfaces brought down and traffic blocked", "notes": "āš ļø DANGEROUS: Severs all networking instantly. Takes no arguments. Use recover-internet / panic-recover to restore connectivity." } ], "id": "2_internet_traffic_control", "title": "Internet Traffic Control" }, { "description": "The auto kill switch: watch one thing, cut the internet when it changes. A watch-guard always runs as a persistent daemon. --watch accepts 8 types: ip, timezone, interfaces, process (needs --target), mac, hostname, vpn, dns. --method chooses how the block is applied: nftables, iptables, firewall, interfaces, auto or all. All watch-guard commands need root.", "examples": [ { "command": "sudo health-control enable --type watch-guard --watch vpn --method nftables", "description": "Automatic kill switch: cut the internet the moment the VPN tunnel drops", "expectedOutput": "Watch-guard enabled, polling VPN state every 5 seconds", "notes": "This is the auto kill switch. A daemon polls the tunnel every 5s and blocks the network on drop, then verifies the block actually took effect. Watch-guards always run as a persistent daemon, so no extra flag is needed." }, { "command": "sudo health-control enable --type watch-guard --watch ip --method nftables", "description": "Block internet if the external IP changes", "expectedOutput": "Watch-guard enabled message with initial IP", "notes": "Blocks internet using nftables if external IP changes. For tunnel-drop protection use --watch vpn instead." }, { "command": "sudo health-control enable --type watch-guard --watch timezone --method iptables", "description": "Enable watch-guard for timezone changes", "expectedOutput": "Watch-guard enabled with current timezone", "notes": "Detects system time manipulation attempts" }, { "command": "sudo health-control enable --type watch-guard --watch interfaces --method firewall", "description": "Monitor network interfaces for changes", "expectedOutput": "Watch-guard monitoring interface list", "notes": "Blocks if new interfaces appear or existing ones change" }, { "command": "sudo health-control enable --type watch-guard --watch process --target tor --method interfaces", "description": "Monitor Tor process and block if it dies", "expectedOutput": "Watch-guard watching Tor process count", "notes": "Ensures no clearnet traffic if Tor crashes" }, { "command": "sudo health-control enable --type watch-guard --watch process --target firefox --method all", "description": "Monitor Firefox and use all block methods if it stops", "expectedOutput": "Watch-guard active for Firefox process", "notes": "Maximum blocking using all available methods" }, { "command": "sudo health-control enable --type watch-guard --watch dns --method nftables", "description": "Block internet if the DNS resolver configuration changes under you", "expectedOutput": "Watch-guard enabled, recording the current resolver set", "notes": "Leak guard: a resolver swap (rogue DHCP, a VPN client rewriting resolv.conf) is a DNS-leak precursor. Blocks the network when it happens." }, { "command": "sudo health-control enable --type watch-guard --watch mac --method auto", "description": "Block internet if a network interface MAC address changes", "expectedOutput": "Watch-guard enabled with the current MAC per interface", "notes": "Anonymity guard: catches an unexpected MAC change (for example a re-randomisation you did not ask for) that would re-identify you on the local network." }, { "command": "sudo health-control enable --type watch-guard --watch hostname --method auto", "description": "Block internet if the system hostname changes", "expectedOutput": "Watch-guard enabled with the current hostname", "notes": "Anonymity guard: the hostname leaks into DHCP and mDNS. Valid --watch values are ip, timezone, interfaces, process, mac, hostname, vpn and dns." }, { "command": "sudo health-control watch-guard status", "description": "Show all active watch-guards, their trigger counts and their config ids", "expectedOutput": "List of active watch-guards with details, including the config id of each", "notes": "This is where you read the config id that 'health-control daemon --config-id <ID>' needs." }, { "command": "sudo health-control disable --type watch-guard ip", "description": "Disable IP watch-guard and unblock internet", "expectedOutput": "Watch-guard disabled confirmation", "notes": "Automatically unblocks internet unless --no-unblock used" }, { "command": "sudo health-control disable --type watch-guard all --no-unblock", "description": "Disable all watch-guards but keep internet blocked", "expectedOutput": "All watch-guards disabled message", "notes": "Use when you want manual control over unblocking" }, { "command": "sudo health-control daemon --config-id \"$WATCHGUARD_CONFIG_ID\"", "description": "Run watch-guard monitoring as a persistent daemon process", "expectedOutput": "Daemon started, monitoring the selected watch-guard configuration", "notes": "--config-id is required and comes from the 'watch-guard status' output. Add --json for machine-readable output. Long-running foreground process intended for service supervision." }, { "command": "sudo health-control daemon --config-id <ID>", "description": "Same thing with the id pasted in literally, after reading it from watch-guard status", "expectedOutput": "Blocks in the foreground and keeps monitoring until you stop it", "notes": "Run 'sudo health-control watch-guard status' first to get <ID>. This command does not return: run it under a service unit or in a background shell." } ], "id": "3_watchguard", "title": "Watch-Guard Management" }, { "description": "Diagnose and fix connectivity issues", "examples": [ { "command": "sudo health-control recover-internet", "description": "Automatically diagnose and fix connectivity issues", "expectedOutput": "Recovery steps performed and status" }, { "command": "sudo health-control recover-internet --check-dns", "description": "Include DNS resolution testing and fixes", "expectedOutput": "Recovery with DNS diagnostics" }, { "command": "sudo health-control recover-internet --force", "description": "Force recovery even if connectivity appears working", "expectedOutput": "Forced recovery completion status" }, { "command": "sudo health-control recover-internet --silent", "description": "Run full internet recovery without desktop/terminal notifications", "expectedOutput": "Recovery runs silently (no notifications)", "notes": "Also supports --skipnotification, --skip-notification, and typo-compatible --skipnotifcation" }, { "command": "sudo health-control fast-recover-internet", "description": "Fast recovery: bounce interface + restart NetworkManager + DHCP renew", "expectedOutput": "FAST_RECOVER: SUCCESS", "notes": "Lightweight alternative to recover-internet, tries quick fix before full 9-method recovery" }, { "command": "sudo health-control fast-recover-internet --silent", "description": "Run fast recovery without desktop/terminal notifications", "expectedOutput": "FAST_RECOVER runs silently (no notifications)", "notes": "Also supports --skipnotification, --skip-notification, and typo-compatible --skipnotifcation" }, { "command": "sudo health-control fast-recover-internet --json", "description": "Fast recovery with JSON output", "expectedOutput": "JSON envelope with success status and method details" } ], "id": "4_network_recovery", "title": "Network Recovery" }, { "description": "Manage system timezone settings", "examples": [ { "command": "sudo health-control sync-timezone", "description": "Sync timezone based on IP geolocation", "expectedOutput": "Timezone synchronized to detected location" }, { "command": "health-control show-timezone", "description": "Show current system timezone", "expectedOutput": "Current timezone information" }, { "command": "sudo health-control set-timezone --timezone \"America/New_York\"", "description": "Set specific timezone", "expectedOutput": "Timezone set to America/New_York" }, { "command": "health-control show-remote-timezone", "description": "Show timezone based on current IP location", "expectedOutput": "Remote location timezone information" }, { "command": "health-control list-timezones", "description": "List all timezone categories", "expectedOutput": "List of timezone categories with counts" }, { "command": "health-control list-timezones --category all", "description": "List all available timezones", "expectedOutput": "Complete list of timezones" }, { "command": "health-control list-timezones --category africa", "description": "List African timezones", "expectedOutput": "List of African timezones" }, { "command": "health-control list-timezones --category americas", "description": "List American timezones", "expectedOutput": "List of North and South American timezones" }, { "command": "health-control list-timezones --category asia", "description": "List Asian timezones", "expectedOutput": "List of Asian timezones" }, { "command": "health-control list-timezones --category europe", "description": "List European timezones", "expectedOutput": "List of European timezones" }, { "command": "health-control list-timezones --category australia", "description": "List Australian timezones", "expectedOutput": "List of Australian timezones" }, { "command": "health-control list-timezones --category pacific", "description": "List Pacific timezones", "expectedOutput": "List of Pacific timezones" }, { "command": "health-control list-timezones --category utc", "description": "List UTC timezones", "expectedOutput": "List of UTC timezones" }, { "command": "health-control list-timezones --json", "description": "List timezone categories in JSON format", "expectedOutput": "JSON output of timezone categories" }, { "command": "sudo health-control set-random-timezone", "description": "Set a random timezone from all available", "expectedOutput": "Timezone set to random value", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category americas", "description": "Set random American timezone", "expectedOutput": "Timezone set to random American timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category europe", "description": "Set random European timezone", "expectedOutput": "Timezone set to random European timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category asia", "description": "Set random Asian timezone", "expectedOutput": "Timezone set to random Asian timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category africa", "description": "Set random African timezone", "expectedOutput": "Timezone set to random African timezone", "notes": "Requires sudo privileges" }, { "command": "sudo health-control set-random-timezone --category pacific --json", "description": "Set random Pacific timezone with JSON output", "expectedOutput": "JSON output of timezone change", "notes": "Requires sudo privileges" } ], "id": "5_timezone_management", "title": "Timezone Management" }, { "description": "Change and manage MAC addresses", "examples": [ { "command": "sudo health-control mac-change-all", "description": "Change MAC addresses for all interfaces", "expectedOutput": "All MAC addresses changed", "notes": "Every interface briefly drops while its MAC is re-randomised, so active connections (SSH, VPN, downloads) will be cut. Undo with 'sudo health-control mac-reset-all'." }, { "command": "sudo health-control mac-force-change", "description": "Force change MAC addresses", "expectedOutput": "MAC addresses force-changed", "notes": "Use when regular change fails" }, { "command": "sudo health-control mac-change-specific --interface eth0", "description": "Change MAC for specific interface", "expectedOutput": "MAC address changed for eth0" }, { "command": "sudo health-control mac-show-interfaces", "description": "Show all network interfaces", "expectedOutput": "List of network interfaces" }, { "command": "sudo health-control mac-show-macs", "description": "Show current MAC addresses", "expectedOutput": "List of interfaces and MAC addresses" }, { "command": "sudo health-control mac-reset-all", "description": "Reset all MACs to original values", "expectedOutput": "MAC addresses reset to original", "notes": "Restores the hardware (permanent) MAC on every interface, which de-anonymises you on the local network again. Interfaces bounce, so live connections drop." }, { "command": "sudo health-control mac-active-interface", "description": "Show active network interface", "expectedOutput": "Currently active network interface" } ], "id": "6_mac_address_management", "title": "MAC Address Management" }, { "description": "Get and set system hostname", "examples": [ { "command": "sudo health-control get-hostname", "description": "Get current system hostname", "expectedOutput": "Current hostname" }, { "command": "sudo health-control get-hostname --json", "description": "Get hostname in JSON format", "expectedOutput": "JSON formatted hostname" }, { "command": "health-control get-logged-user", "description": "Get the actual logged-in user (handles sudo correctly)", "expectedOutput": "Username of logged-in user", "notes": "Returns actual user even when run with sudo" }, { "command": "health-control get-logged-user --json", "description": "Get logged user with additional info in JSON format", "expectedOutput": "JSON with username, home directory, and detection method" }, { "command": "sudo health-control set-default-hostname", "description": "Set default system hostname", "expectedOutput": "Default hostname set" }, { "command": "sudo health-control set-random-hostname", "description": "Set random hostname for privacy", "expectedOutput": "Random hostname set" }, { "command": "sudo health-control set-random-hostname --json", "description": "Set random hostname with JSON output", "expectedOutput": "JSON formatted hostname change result" }, { "command": "sudo health-control set-custom-hostname --name MyHost", "description": "Set custom hostname", "expectedOutput": "Hostname set to MyHost" }, { "command": "sudo health-control set-custom-hostname --name privacy-machine", "description": "Set descriptive custom hostname", "expectedOutput": "Hostname set to privacy-machine" }, { "command": "sudo health-control set-custom-hostname --name secure-workstation --json", "description": "Set custom hostname with JSON output", "expectedOutput": "JSON formatted hostname change result" }, { "command": "health-control list-hostnames", "description": "List all hostname categories", "expectedOutput": "List of available hostname categories with counts" }, { "command": "health-control list-hostnames --category all", "description": "List all available hostnames", "expectedOutput": "Complete list of all predefined hostnames" }, { "command": "health-control list-hostnames --category windows", "description": "List Windows hostnames", "expectedOutput": "List of Windows-style hostnames" }, { "command": "health-control list-hostnames --category linux", "description": "List Linux hostnames", "expectedOutput": "List of Linux distribution hostnames" }, { "command": "health-control list-hostnames --category apple", "description": "List Apple/Mac hostnames", "expectedOutput": "List of macOS and Apple device hostnames" }, { "command": "health-control list-hostnames --json", "description": "List hostname categories in JSON format", "expectedOutput": "JSON formatted category list with counts" }, { "command": "sudo health-control set-random-hostname-category", "description": "Set random hostname from all categories", "expectedOutput": "Random hostname selected and set" }, { "command": "sudo health-control set-random-hostname-category --category windows", "description": "Set random Windows hostname", "expectedOutput": "Random Windows-style hostname set" }, { "command": "sudo health-control set-random-hostname-category --category linux", "description": "Set random Linux hostname", "expectedOutput": "Random Linux distribution hostname set" }, { "command": "sudo health-control set-random-hostname-category --category fiction --json", "description": "Set random fictional hostname with JSON output", "expectedOutput": "Random fictional hostname set with JSON result" }, { "command": "sudo health-control change-hostname mylaptop", "description": "Set the system hostname to a specific value", "expectedOutput": "Hostname changed to mylaptop", "notes": "HOSTNAME positional argument is optional; when omitted a hostname is generated/applied per default behavior." } ], "id": "7_hostname_management", "title": "Hostname Management" }, { "description": "Control and monitor IPv6 protocol settings", "examples": [ { "command": "health-control ipv6-status", "description": "Check current IPv6 configuration status", "expectedOutput": "IPv6 Status: ENABLED/DISABLED with interface details", "notes": "Shows runtime status, boot config, and active interfaces" }, { "command": "sudo health-control ipv6-disable", "description": "Disable IPv6 system-wide (sysctl and GRUB)", "expectedOutput": "IPv6 disabled with details of changes applied", "notes": "Reboot recommended for full effect" }, { "command": "sudo health-control ipv6-enable", "description": "Enable IPv6 system-wide", "expectedOutput": "IPv6 enabled with details of changes applied", "notes": "Reboot recommended for full effect" }, { "command": "health-control ipv6-status --json", "description": "Get detailed IPv6 status in JSON format", "expectedOutput": "Complete IPv6 configuration including runtime, boot config, and interfaces" } ], "id": "8_ipv6_management", "title": "IPv6 Management" }, { "description": "Apply and verify comprehensive security settings (7 modules: kernel, process, filesystem, network, memory, monitoring, sandboxing)", "examples": [ { "command": "sudo health-control security-harden", "description": "Apply standard security hardening (network-safe): kernel hardening, process isolation, filesystem security, memory protection, monitoring, sandboxing - PRESERVES internet connectivity", "expectedOutput": "Security hardening completed (network connectivity preserved)", "notes": "Standard profile maintains system usability and network connectivity" }, { "command": "sudo health-control security-harden --profile medium", "description": "Apply MEDIUM profile - Enhanced security with hidepid, hardened_malloc, file integrity monitoring. Browsers and internet still work", "expectedOutput": "Medium security hardening applied (browsers and internet preserved)", "notes": "Medium profile adds hidepid=2, hardened_malloc, dirty_ratio tuning, file integrity. May increase memory on LUKS systems" }, { "command": "sudo health-control security-harden --profile paranoid", "description": "Apply PARANOID profile - WARNING: WILL BREAK browsers and internet: disables user namespaces, IP forwarding, DNS firewall, MAC spoofing", "expectedOutput": "Paranoid security applied (network isolated)", "notes": "āš ļø BROWSERS AND INTERNET DISABLED - To recover: sudo health-control security-recover" }, { "command": "sudo health-control security-harden --break-monitoring", "description": "Apply paranoid profile plus break-monitoring mode: forces /sys/class/net to root-only and breaks non-root monitoring tools (btop/conky/dashboard)", "expectedOutput": "Paranoid hardening applied with monitoring intentionally restricted", "notes": "āš ļø ALSO BREAKS NON-ROOT MONITORING - Use only when this behavior is explicitly required" }, { "command": "sudo health-control security-verify", "description": "Check if all 7 security modules are enabled and properly configured", "expectedOutput": "Shows each module: ENABLED/DISABLED and configuration status", "notes": "Use after security-harden to verify settings are applied" }, { "command": "sudo health-control security-harden --modules kernel,network", "description": "Apply only specific modules (kernel sysctl and network firewall)", "expectedOutput": "Applied 2 modules: kernel and network hardening", "notes": "Modules: kernel, process, filesystem, network, memory, monitoring, sandboxing" }, { "command": "sudo health-control security-recover", "description": "Temporarily revert security hardening (keeps framework ready for quick re-hardening)", "expectedOutput": "Security recovery completed - modules show 'ENABLED (needs configuration)'", "notes": "Use for troubleshooting. Framework remains enabled for easy re-hardening with security-harden." }, { "command": "sudo health-control security-recover --modules network,kernel", "description": "Recover only specific security modules", "expectedOutput": "Selected modules recovered", "notes": "Available modules: kernel, filesystem, network, memory, monitoring, smt" }, { "command": "sudo health-control security-reset", "description": "Completely disable all security modules and framework (permanent removal)", "expectedOutput": "All modules show 'DISABLED' - framework completely removed", "notes": "WARNING: Unlike security-recover, this permanently disables the framework. Requires rebuilding to re-enable." }, { "command": "sudo health-control security-reset --force", "description": "Reset security framework without confirmation prompt", "expectedOutput": "Security framework completely disabled", "notes": "Use --force to skip the confirmation prompt in automation scripts" }, { "command": "sudo health-control monitoring-enable", "description": "Enable system security monitoring (auditd, LKRG, file integrity, auth events)", "expectedOutput": "Security monitoring enabled", "notes": "Enables auditd for system call auditing, LKRG for kernel integrity, file integrity monitoring (AIDE/Tripwire), and auth event logging" }, { "command": "sudo health-control monitoring-disable", "description": "Disable system security monitoring services", "expectedOutput": "Security monitoring disabled", "notes": "Stops all security monitoring services - reduces system overhead but decreases security visibility" }, { "command": "sudo health-control monitoring-status", "description": "Check current system security monitoring status", "expectedOutput": "Security monitoring status details", "notes": "Shows status of auditd, LKRG, AIDE, and auth logging - helps verify which monitoring services are active" }, { "command": "sudo health-control tirdad-enable", "description": "Enable Tirdad kernel module for TCP ISN randomization (prevents OS fingerprinting)", "expectedOutput": "Tirdad enabled successfully", "notes": "Randomizes TCP Initial Sequence Numbers to prevent remote OS fingerprinting attacks and TCP sequence prediction" }, { "command": "sudo health-control tirdad-disable", "description": "Disable Tirdad TCP ISN randomization module", "expectedOutput": "Tirdad disabled successfully", "notes": "Restores default TCP ISN generation - may make system identifiable via network fingerprinting" }, { "command": "health-control tirdad-status", "description": "Check Tirdad TCP ISN randomization module status", "expectedOutput": "Tirdad status: ENABLED/DISABLED", "notes": "Shows if kernel module is loaded and TCP ISN randomization is active" }, { "command": "sudo health-control disk-encryption-status", "description": "Check disk encryption status", "expectedOutput": "Disk encryption configuration", "notes": "Displays LUKS encryption status for all disks, cipher algorithms, and key slot usage" }, { "command": "sudo health-control usb-list", "description": "List all USB devices", "expectedOutput": "Connected USB devices", "notes": "Shows all connected USB devices with vendor/product IDs for security auditing" }, { "command": "sudo health-control create-persistence", "description": "Create unencrypted live-boot persistence media", "expectedOutput": "Debian live-boot persistence media created successfully", "notes": "Creates a 4GB unencrypted ext4 persistence image named 'persistence' with a root persistence.conf of '/ union' so /opt, /etc, and other system paths survive reboots on Kodachi live USBs. Use --encrypted for LUKS encryption or --size to change size." }, { "command": "sudo health-control create-persistence --encrypted", "description": "Create encrypted persistence (interactive)", "expectedOutput": "Encrypted persistence media created", "notes": "Creates LUKS2-encrypted Debian live-boot persistence media named 'persistence' and writes '/ union' to persistence.conf. Secure method - password not visible in history." }, { "command": "read -rsp 'Persistence password: ' PERSISTENCE_PASSWORD && printf '\\n' && sudo health-control create-persistence --encrypted --password \"$PERSISTENCE_PASSWORD\" && unset PERSISTENCE_PASSWORD", "description": "Create encrypted persistence with a hidden interactive password prompt", "expectedOutput": "Encrypted persistence media created", "notes": "The password is read without terminal echo and is never embedded in the catalog or shell history. The variable is cleared after a successful command." }, { "command": "sudo health-control encryption-status", "description": "Show overall encryption status", "expectedOutput": "System encryption status report", "notes": "Comprehensive report of all encryption: disks, swap, home directories, and key management" } ], "id": "9_security_hardening", "title": "Security Hardening" }, { "description": "Monitor system health and run security audits", "examples": [ { "command": "sudo health-control security-score --json", "description": "Compute the overall security score from real read-only checks", "expectedOutput": "Security score with per-check breakdown", "notes": "Aggregates the individual read-only checks (entropy, boot-integrity, lynis-status, etc.)" }, { "command": "sudo health-control rootkit-scan", "description": "Scan system for rootkits", "expectedOutput": "Rootkit scan results" }, { "command": "sudo health-control security-status --json", "description": "Check system security status", "expectedOutput": "JSON formatted security status info" }, { "command": "sudo health-control lynis-audit", "description": "Run comprehensive Lynis security audit", "expectedOutput": "Complete Lynis audit report", "notes": "Comprehensive security assessment" }, { "command": "health-control lynis-status", "description": "Check Lynis installation and status", "expectedOutput": "Lynis service status" }, { "command": "sudo health-control aide-init", "description": "Initialize AIDE database", "expectedOutput": "AIDE database created successfully", "notes": "First time setup required" }, { "command": "sudo health-control aide-check", "description": "Check file integrity with AIDE", "expectedOutput": "File integrity check results" }, { "command": "health-control kloak-status", "description": "Check kloak keystroke anonymization status", "expectedOutput": "Kloak service status and configuration" }, { "command": "sudo health-control kloak-enable", "description": "Enable kloak keystroke anonymization", "expectedOutput": "Kloak enabled successfully" }, { "command": "sudo health-control kloak-disable", "description": "Disable kloak keystroke anonymization", "expectedOutput": "Kloak disabled successfully" }, { "command": "sudo health-control kloak-configure --rescue-delay 20 --max-delay 100", "description": "Configure kloak keystroke delay, jitter and operating mode", "expectedOutput": "Kloak configuration updated", "notes": "--mode accepts normal, aggressive, or minimal. All flags are optional." }, { "command": "sudo health-control kloak-event-mode --mode normal", "description": "Set the kloak event-processing mode", "expectedOutput": "Kloak event mode set to adaptive", "notes": "--mode is required: raw, filtered, or adaptive." }, { "command": "health-control kloak-stats", "description": "Show kloak keystroke anonymization statistics", "expectedOutput": "Kloak counters and timing statistics", "notes": "Add --reset to clear the statistics counters." }, { "command": "sudo health-control aide-update", "description": "Update the AIDE baseline database after reviewing changes", "expectedOutput": "AIDE database updated", "notes": "Add --accept-changes to accept all detected changes and update the baseline." }, { "command": "sudo health-control aide-reinit --background --timeout 7200 --json", "description": "Start AIDE database reinitialization in the background", "expectedOutput": "JSON background launch status with log path", "notes": "Use --force only when intentionally replacing an existing baseline." }, { "command": "sudo health-control aide-reinit --force", "description": "Rebuild the AIDE baseline from the current filesystem, in the foreground", "expectedOutput": "AIDE database reinitialized, new baseline written", "notes": "DESTROYS THE OLD BASELINE. Every tampering signal AIDE was holding is replaced by \"whatever the disk looks like right now\", so if the machine is already compromised you are baselining the compromise. Only reinit on a system you trust. Flags: --force (no confirmation), --timeout <SECONDS> (default 3600), --background. It can take a long time: --background returns immediately." }, { "command": "sudo health-control aide-scan-dir /etc --recursive", "description": "Run an AIDE integrity scan against a specific directory", "expectedOutput": "File integrity results for the scanned directory", "notes": "PATH positional argument is required. -r/--recursive scans subdirectories." } ], "id": "10_system_health_security", "title": "System Health & Security Tools" }, { "description": "LUKS nuke passwords for emergency data destruction", "examples": [ { "command": "sudo health-control luks-nuke --action status", "description": "List all LUKS devices and nuke password status", "expectedOutput": "LUKS device status and configuration", "notes": "Shows which devices have nuke passwords configured" }, { "command": "sudo health-control luks-nuke --action status --device \"$LUKS_DEVICE\"", "description": "āš ļø STEP 1: Check current nuke status for target device", "expectedOutput": "Current LUKS nuke configuration status for the selected device", "notes": "āš ļø ALWAYS backup header BEFORE configuring nuke password. This status check helps confirm current device state before changes." }, { "command": "sudo health-control luks-nuke --action configure --device \"$LUKS_DEVICE\" --password \"$LUKS_NUKE_PASSWORD\"", "description": "āš ļø STEP 2: Configure nuke password (DATA DESTRUCTION FEATURE)", "expectedOutput": "Nuke password configured in keyslot 7", "notes": "āš ļø CRITICAL WARNING: This creates a password that will PERMANENTLY DESTROY all data on the selected LUKS device when entered! Use only if you understand the consequences. Requires header backup from STEP 1. Password must be strong (12+ chars, mixed case, numbers, symbols). Avoid obvious words like 'nuke', 'destroy', 'emergency'." }, { "command": "sudo health-control luks-nuke --action remove --device \"$LUKS_DEVICE\"", "description": "Remove nuke password from device", "expectedOutput": "Nuke password removed from keyslot 7", "notes": "Removes the data destruction feature from the device. You will be prompted to confirm which keyslot to remove (usually keyslot 7). Requires current LUKS password." }, { "command": "gpg -d \"$LUKS_HEADER_BACKUP\" | sudo cryptsetup luksHeaderRestore \"$LUKS_DEVICE\"", "description": "āš ļø EMERGENCY: Restore LUKS header after nuke password was used", "expectedOutput": "LUKS header restored from backup", "notes": "āš ļø USE ONLY IF nuke password was accidentally used! This restores the LUKS header from your encrypted backup. You MUST have created a header backup BEFORE the nuke password was triggered. After restoration, you can unlock the device with your original LUKS password. Without a backup, data is PERMANENTLY LOST." }, { "command": "sudo health-control luks-detect", "description": "Detect LUKS-encrypted devices on the system", "expectedOutput": "List of detected LUKS containers", "notes": "Add --all-devices to also scan loop and other block devices." }, { "command": "sudo health-control luks-manage --action list", "description": "Manage LUKS devices (add, remove, unlock, lock, list)", "expectedOutput": "LUKS device management result", "notes": "--action defaults to list. Use --device to target a specific device path for add/remove/unlock/lock." }, { "command": "sudo health-control luks-manage-advanced --action backup-header --device \"$LUKS_DEVICE\" --backup-file \"$LUKS_HEADER_BACKUP\"", "description": "Advanced LUKS header operations and key management", "expectedOutput": "Advanced LUKS operation completed", "notes": "--action is required: create, format, backup-header, restore-header, change-key, add-key, remove-key. Provide --device / --key-file / --backup-file as the action requires." }, { "command": "sudo health-control luks-nuke-advanced --device \"$LUKS_DEVICE\" --password \"$LUKS_NUKE_PASSWORD\"", "description": "āš ļø Configure an advanced LUKS nuke password (DATA DESTRUCTION)", "expectedOutput": "Advanced nuke configuration applied to the selected LUKS device", "notes": "āš ļø CRITICAL: --device is required; entering the nuke --password later PERMANENTLY DESTROYS all data on the device. Always back up the LUKS header first." }, { "command": "sudo health-control luks-remove \"$LUKS_DEVICE\" --force", "description": "āš ļø Remove LUKS encryption from a device", "expectedOutput": "LUKS removed from the selected device", "notes": "āš ļø DESTRUCTIVE: DEVICE positional argument is required. --force skips the confirmation prompt." } ], "id": "11_luks_nuke_operations", "title": "LUKS Nuke & Data Destruction" }, { "description": "Full system data destruction for emergency situations. IRREVERSIBLE - use with extreme caution.", "examples": [ { "command": "health-control nuke-execute --dry-run", "description": "āš ļø TEST MODE: Preview what would be destroyed without actually wiping", "expectedOutput": "[DRY_RUN] messages showing all files/directories that would be wiped", "notes": "ALWAYS test with --dry-run first! Shows exactly what will be destroyed including: SSH keys, GPG keys, crypto wallets, browser data, messaging apps, email, documents, and system logs." }, { "command": "health-control nuke-execute --method fast --dry-run", "description": "Fast wipe mode (1-pass) - quickest destruction (~27 seconds)", "expectedOutput": "Fast wipe simulation with single-pass overwrite", "notes": "Best for SSDs where multi-pass is ineffective. Uses blkdiscard for SSDs, single shred pass for HDDs." }, { "command": "health-control nuke-execute --method secure --dry-run", "description": "Secure wipe mode (3-pass DoD) - balanced security (~45 seconds)", "expectedOutput": "Secure wipe simulation with 3-pass DoD standard", "notes": "DEFAULT mode. 3-pass overwrite following DoD 5220.22-M standard. Good balance of speed and security for HDDs." }, { "command": "health-control nuke-execute --method paranoid --dry-run", "description": "Paranoid wipe mode (7-pass) - maximum security (~60 seconds)", "expectedOutput": "Paranoid wipe simulation with 7-pass Gutmann-style", "notes": "Maximum security. 7-pass overwrite. Also wipes boot sector, GRUB, kernel, initrd, and MBR. System will be unbootable." }, { "command": "health-control nuke-execute --method fast --force", "description": "āš ļø DANGER: Execute REAL fast wipe - DESTROYS ALL DATA", "expectedOutput": "Data destruction in progress... System will reboot when complete.", "notes": "āš ļø IRREVERSIBLE! This PERMANENTLY DESTROYS: ~/.ssh, ~/.gnupg, crypto wallets (Bitcoin/Monero/Electrum), all browsers, Signal/Telegram/Discord, Thunderbird, Documents/Downloads/Desktop, AWS/Docker/Kube credentials, bash history, system logs. System forces reboot after completion." }, { "command": "health-control nuke-progress", "description": "Check current nuke operation progress", "expectedOutput": "Phase: 5 - browser_data, Complete: false, Active: true", "notes": "Monitor ongoing destruction progress. Shows current phase, completion status, and any errors." }, { "command": "health-control nuke-storage-detect --device \"${TARGET_DEVICE:?Set TARGET_DEVICE after reviewing lsblk output}\"", "description": "Detect storage type for optimal wipe method", "expectedOutput": "Selected device path and detected storage type", "notes": "Detects if device is SSD, HDD, or NVMe. SSDs use blkdiscard (instant secure erase), HDDs use shred (multi-pass overwrite), NVMe uses nvme format command." } ], "id": "11b_emergency_nuke_operations", "title": "Emergency Nuke Operations" }, { "description": "Complete USB security management: device listing, USBGuard policies, storage control, and monitoring.\n\nUNDERSTANDING USB SECURITY LAYERS. USB security has TWO independent control systems:\n\n1. USBGuard (usb-guard-* commands):\n- Controls WHICH devices are allowed or blocked\n- Device authorization policy management\n- Works at the USBGuard daemon level\n\n2. USB Storage Modules (offline-usb-storage):\n- Controls IF USB storage drivers are loaded at all\n- Manages kernel modules (usb_storage, uas)\n- Manages device authorization at kernel level\n- Integrates with USBGuard automatically\n\nCRITICAL: for USB drives to work you need all of:\n- USB storage modules enabled (offline-usb-storage --action enable)\n- USBGuard allowing the device (or USBGuard disabled)\n- The device authorized at kernel level (handled by offline-usb-storage)\n\nTIP: 'sudo health-control offline-usb-storage --action enable' gives complete USB storage\naccess. It handles all 4 layers automatically.", "examples": [ { "command": "sudo health-control usb-list", "description": "List all connected USB devices", "expectedOutput": "USB device list with security status" }, { "command": "sudo health-control offline-usb-storage --action check", "description": "Check USB storage module status (all 4 layers)", "expectedOutput": "Modules loaded: yes/no, Blacklist exists: yes/no, USBGuard active: yes/no, Authorized devices: N", "notes": "Shows complete status of all USB storage control layers" }, { "command": "sudo health-control offline-usb-storage --action enable", "description": "Enable USB storage completely (recommended)", "expectedOutput": "USB storage enabled successfully - All layers configured", "notes": "Handles ALL 4 layers: Removes blacklist, loads modules, authorizes devices, integrates with USBGuard.\nYour USB drives should appear immediately in 'lsblk' after this command." }, { "command": "sudo health-control offline-usb-storage --action enable --verbose", "description": "Enable USB storage with detailed layer-by-layer output", "expectedOutput": "Shows: modules loaded ā†’ devices authorized ā†’ USBGuard integration ā†’ udev triggered", "notes": "Use verbose mode to see exactly what happens at each layer" }, { "command": "sudo health-control offline-usb-storage --action disable", "description": "Disable USB storage completely (security lockdown)", "expectedOutput": "USB storage disabled successfully - All layers configured", "notes": "Blocks USB storage at all 4 layers: deauthorizes devices, blocks in USBGuard, unloads modules, creates blacklist" }, { "command": "sudo health-control usb-guard-enable", "description": "Enable USB Guard protection service", "expectedOutput": "USB Guard enabled successfully", "notes": "āš ļø This only enables USBGuard service - does NOT enable USB storage modules!\nIf USB storage modules are blocked, your drives won't appear even with USBGuard enabled.\nUse 'offline-usb-storage --action enable' for complete access." }, { "command": "sudo health-control usb-guard-disable", "description": "Disable USB Guard protection service", "expectedOutput": "USB Guard disabled successfully", "notes": "Disables USBGuard service but does NOT affect USB storage modules.\nStorage modules may still be blocked separately." }, { "command": "sudo health-control usb-policy --action add --device-id 1234:5678 --allow", "description": "Add USB device to USBGuard allow policy", "expectedOutput": "USB device policy added", "notes": "Use lsusb to find device IDs. This manages USBGuard policy only.\nDevice must also be authorized at kernel level (handled by offline-usb-storage)." }, { "command": "sudo health-control usb-policy --action list", "description": "List all USB policies in USBGuard", "expectedOutput": "Current USB device policies" }, { "command": "sudo health-control usb-policy --action status", "description": "Check USB security policies", "expectedOutput": "USB security policy assessment" }, { "command": "sudo health-control usb-monitor", "description": "Start USB device monitoring", "expectedOutput": "USB monitoring started" }, { "command": "sudo health-control usb-history --days 7", "description": "View USB device history for last 7 days", "expectedOutput": "USB device connection history" }, { "command": "sudo health-control usb-status", "description": "Show overall USB security status", "expectedOutput": "USB security status summary" }, { "command": "sudo health-control usb-whitelist --action add --device-id 1234:5678", "description": "Manage the USB device whitelist (add, remove, list, import, export)", "expectedOutput": "USB whitelist updated", "notes": "--action defaults to list. Use --device-id (vendor:product) for add/remove, or --file for import/export." } ], "id": "12_usb_device_security", "title": "USB & Device Security" }, { "description": "Secure data wiping procedures", "examples": [ { "command": "sudo health-control wipe-file --file /path/to/file --passes 7", "description": "Securely wipe file with 7 passes", "expectedOutput": "File securely wiped and unrecoverable", "notes": "Multiple passes increase security" }, { "command": "sudo health-control wipe-directory --path /path/to/directory --passes 3", "description": "Securely wipe entire directory", "expectedOutput": "Directory and contents wiped securely", "notes": "All files in directory will be destroyed" }, { "command": "sudo health-control wipe-free-space --device \"$TARGET_BLOCK_DEVICE\"", "description": "Wipe free space on device", "expectedOutput": "Free space wiped securely", "notes": "Prevents recovery of deleted files" }, { "command": "sudo health-control wipe-logs", "description": "Wipe system and application logs", "expectedOutput": "Logs wiped successfully", "notes": "Removes log file traces" }, { "command": "sudo health-control wipe-browser-data", "description": "Wipe browser history and data", "expectedOutput": "Browser data wiped", "notes": "Removes browsing history and cache" }, { "command": "sudo health-control wipe-schedule temp --frequency daily", "description": "Schedule automatic temporary file wiping daily", "expectedOutput": "File wipe scheduled successfully", "notes": "Automatically wipes temp files based on frequency" }, { "command": "sudo health-control wipe-pattern \"*.tmp\"", "description": "Wipe all temporary files matching pattern", "expectedOutput": "Files matching pattern wiped", "notes": "Uses glob patterns to match files for wiping" }, { "command": "sudo health-control wipe-verify --path /path/to/file", "description": "Verify file has been securely wiped", "expectedOutput": "File wipe verification results", "notes": "Read-only check: it re-reads the target and reports whether the wipe pattern actually landed. It does not wipe anything itself and it cannot recover a wiped file." }, { "command": "sudo health-control wipe-batch /path1 /path2 /path3 --passes 7", "description": "Batch wipe multiple files with 7 passes", "expectedOutput": "Batch file wiping completed", "notes": "Space-separated file paths" }, { "command": "sudo health-control wipe-user-dir --target downloads", "description": "āš ļø Securely wipe a standard user directory", "expectedOutput": "User directory securely wiped", "notes": "āš ļø DESTRUCTIVE: --target is required and must be one of downloads, desktop, documents. All contents are permanently destroyed." } ], "id": "13_data_destruction", "title": "Data Destruction & Secure Wiping" }, { "description": "Automated updates, password policies, and system maintenance", "examples": [ { "command": "sudo health-control auto-updates-enable", "description": "Enable automatic security updates", "expectedOutput": "Automatic security updates enabled" }, { "command": "sudo health-control auto-updates-disable", "description": "Disable automatic updates", "expectedOutput": "Automatic updates disabled" }, { "command": "sudo health-control auto-updates-status", "description": "Check automatic updates status", "expectedOutput": "Auto-updates configuration status" }, { "command": "sudo health-control password-policy-enable", "description": "Enable strong password policy", "expectedOutput": "Strong password policy enforced" }, { "command": "sudo health-control password-policy-disable", "description": "Disable strong password policy", "expectedOutput": "Password policy disabled" }, { "command": "sudo health-control user-security-enable", "description": "Enable user security checks", "expectedOutput": "User security policies enabled" }, { "command": "sudo health-control 2fa-enable --value username", "description": "Enable 2FA for specific user", "expectedOutput": "Two-factor authentication enabled", "notes": "Configures PAM. WARNING: 2FA is known to be unreliable with the XFCE/LightDM graphical login and the lock screen (it works for SSH and sudo). Keep a root shell open while you test it, and know that 'sudo health-control 2fa-disable' is the way out." }, { "command": "sudo health-control 2fa-disable", "description": "Disable 2FA for user", "expectedOutput": "Two-factor authentication disabled", "notes": "Recovery path if 2FA locked you out of the desktop login. Removes the PAM requirement, so the account drops back to password-only." }, { "command": "sudo health-control system-maintenance-enable", "description": "Enable automatic system maintenance", "expectedOutput": "System maintenance automation enabled" }, { "command": "sudo health-control package-cleanup", "description": "Clean up unnecessary packages", "expectedOutput": "System packages cleaned and optimized" }, { "command": "sudo health-control password-policy-status", "description": "Check password policy status", "expectedOutput": "Current password policy configuration" }, { "command": "sudo health-control user-security-disable", "description": "Disable user security checks", "expectedOutput": "User security policies disabled" }, { "command": "sudo health-control user-security-status", "description": "Check user security status", "expectedOutput": "User security configuration status" }, { "command": "health-control 2fa-status", "description": "Check 2FA status for users", "expectedOutput": "Two-factor authentication status" }, { "command": "sudo health-control system-maintenance-disable", "description": "Disable automatic system maintenance", "expectedOutput": "System maintenance automation disabled" }, { "command": "health-control system-maintenance-status", "description": "Check system maintenance status", "expectedOutput": "System maintenance configuration status" }, { "command": "sudo health-control check-and-install curl wget", "description": "Check whether packages are installed and install the missing ones", "expectedOutput": "Package check and installation results", "notes": "PACKAGES is a required, space-separated list of one or more package names." }, { "command": "sudo health-control check-and-install-do", "description": "Run the predefined check-and-install routine for required packages", "expectedOutput": "Required packages checked and installed", "notes": "Takes no arguments; installs the built-in required package set." }, { "command": "sudo health-control clear-cache --level 3", "description": "Clear system caches at the specified level", "expectedOutput": "System caches cleared", "notes": "--level accepts 1, 2 or 3 (defaults to 3, the most thorough)." }, { "command": "sudo health-control check-sudo", "description": "Diagnose whether sudo is working correctly", "expectedOutput": "Sudo health diagnostic report", "notes": "Read-only check; takes no arguments. Use fix-sudo to repair a broken sudo configuration." }, { "command": "sudo health-control fix-sudo", "description": "Repair a broken sudo configuration without requiring sudo", "expectedOutput": "Sudo configuration repaired", "notes": "Takes no arguments. Designed to recover from a misconfigured/broken sudoers state." } ], "id": "14_system_maintenance", "title": "System Maintenance & Updates" }, { "description": "System configuration and control operations", "examples": [ { "command": "sudo health-control play-sound --sound alert", "description": "Play system alert sound", "expectedOutput": "Sound played successfully" }, { "command": "sudo health-control play-sound success", "description": "Play success notification sound", "expectedOutput": "Success sound played" }, { "command": "sudo health-control play-sound warning -m mp3", "description": "Play warning sound in MP3 format", "expectedOutput": "Warning sound played in MP3" }, { "command": "sudo health-control play-sound alert --debug", "description": "Play alert sound with debug output", "expectedOutput": "Alert sound played with debug info" }, { "command": "health-control notify --message \"Security check complete\"", "description": "Send system notification", "expectedOutput": "Notification sent successfully" }, { "command": "health-control notify --message \"Hello from Kodachi\"", "description": "Send basic notification message", "expectedOutput": "Notification sent successfully" }, { "command": "health-control notify --message \"Alert\" --body \"VPN connected\"", "description": "Send notification with message body", "expectedOutput": "Detailed notification sent" }, { "command": "health-control notify --message \"Warning\" --urgency critical --duration 30", "description": "Send critical notification with 30 second duration", "expectedOutput": "Critical notification sent" }, { "command": "health-control notify --message \"Update\" --notify-icon \"/path/to/icon.png\"", "description": "Send notification with custom icon", "expectedOutput": "Notification with icon sent" } ], "id": "15_system_control", "title": "System Control & Notifications" }, { "description": "Emergency security measures with two modes: PREPARATION (arm/disarm) raises a high-alert flag, IMMEDIATE (panic/activate) executes emergency procedures. Neither monitors: for automatic response use a watch-guard", "examples": [ { "command": "sudo health-control kill-switch-arm", "description": "ARM the kill switch (preparation mode: a high-alert flag, not a monitor)", "expectedOutput": "Kill switch ARMED - high-alert state flag set", "notes": "HIGH-ALERT STATE FLAG. Arming does NOT monitor anything: it starts no watcher and no daemon, and nothing activates panic mode on its own. Firing the kill switch stays manual (kill-switch-activate).\nWhat arming actually does:\nā€¢ Records the high-alert state so other components can see it\nā€¢ While armed, tor-switch will not force firewall policies back to ACCEPT during detorrify, so an existing protective DROP policy is not silently torn down. Arming does not itself block any traffic\nā€¢ Is read by security scoring, but the comprehensive scorer credits it ONLY when egress is actually denied by the firewall. Armed without an enforced default-deny scores zero\nFor an automatic kill switch that reacts on its own, enable a watch-guard instead. It runs a daemon and blocks the network when the trigger fires, e.g. on a VPN tunnel drop:\n sudo health-control enable --type watch-guard --watch vpn --method nftables" }, { "command": "sudo health-control kill-switch-disarm", "description": "DISARM the kill switch (clear the high-alert flag)", "expectedOutput": "Kill switch DISARMED", "notes": "Clears the high-alert state flag (no monitoring was running). Use after the threat has passed or on a false alarm." }, { "command": "sudo health-control kill-switch-status", "description": "Check if monitoring is armed/disarmed", "expectedOutput": "Shows armed status, trigger count, armed time", "notes": "READ-ONLY: Just displays current state, takes no action" }, { "command": "sudo health-control kill-switch-activate", "description": "IMMEDIATELY activate kill switch (default: medium panic)", "expectedOutput": "KILL SWITCH ACTIVATED - emergency procedures executed", "notes": "IMMEDIATE ACTION: Unlike 'arm', this executes panic NOW. Prompts for confirmation. Use --level soft/medium/hard" }, { "command": "sudo health-control panic-soft", "description": "IMMEDIATE soft panic (NO confirmation)", "expectedOutput": "Network killed, clipboard cleared (adaptive: Wayland/X11), screen locked", "notes": "INSTANT: Kill network + clear clipboard (wl-copy/xclip/xsel) + lock screen. Reversible. Good for quick privacy." }, { "command": "sudo health-control panic-medium", "description": "IMMEDIATE medium panic (requires confirmation)", "expectedOutput": "Panic mode activated after confirmation", "notes": "WITH CONFIRMATION: Kill network + clear clipboard (adaptive: wl-copy/xclip/xsel) + terminate processes + clear memory + unmount devices + lock screen (6 actions). Requires manual restart to restore." }, { "command": "sudo health-control panic-hard", "description": "IMMEDIATE hard panic (double confirmation)", "expectedOutput": "System shutdown initiated", "notes": "CRITICAL - DOUBLE CONFIRM: All medium actions + RAM wipe + IMMEDIATE shutdown (7 actions total). IRREVERSIBLE! System shuts down NOW!" }, { "command": "sudo health-control create-recovery-point", "description": "Create recovery checkpoint BEFORE panic", "expectedOutput": "Recovery point created", "notes": "Create BEFORE activating panic modes. Allows restoration of configs after emergency." }, { "command": "sudo health-control panic-recover", "description": "Restore system after panic activation", "expectedOutput": "System recovered from panic mode", "notes": "Use AFTER panic to restore normal operation. Restarts services, fixes permissions." }, { "command": "sudo health-control panic-profile --profile paranoid", "description": "Configure panic response to paranoid security level", "expectedOutput": "Panic profile set: paranoid\nActions configured: 12", "notes": "PROFILE MODES:\nā€¢ STEALTH: Light response (network blocking only, preserve user data)\nā€¢ PARANOID: Maximum security (network kill, data wipe, process termination, interface shutdown)\nā€¢ RECOVERY: System restoration (restart services, fix permissions, restore connectivity)\n\nProfile determines automatic actions when panic mode triggers. Use 'kill-switch-activate' to manually trigger the configured profile." }, { "command": "sudo health-control kill-network-interface --interface eth0", "description": "Kill specific network interface", "expectedOutput": "Network interface eth0 terminated", "notes": "Selective network isolation" }, { "command": "sudo health-control kill-process --process firefox", "description": "Terminate specific process immediately", "expectedOutput": "Process firefox terminated", "notes": "Emergency process termination" } ], "id": "16_emergency_operations", "title": "Emergency Operations - Kill Switch & Panic Modes" }, { "description": "Storage device encryption, secure wiping, LUKS encrypted containers, and volume management", "examples": [ { "command": "sudo health-control list-storage-devices", "description": "List all storage devices with safety indicators (SAFE/CAUTION/DANGER)", "expectedOutput": "Shows devices categorized by safety level for persistence operations", "notes": "Use BEFORE creating persistence to identify safe devices. Protects against accidental system drive formatting." }, { "command": "sudo health-control list-storage-devices --all", "description": "List all storage devices including loop and ram devices", "expectedOutput": "Complete device inventory with safety categorization including virtual devices" }, { "command": "sudo health-control usb-safety-check --device \"${REMOVABLE_DEVICE:?Set REMOVABLE_DEVICE after reviewing lsblk output}\"", "description": "Check if specific device is safe for persistence operations", "expectedOutput": "Returns safety level: SAFE, CAUTION, or DANGER with detailed warnings", "notes": "Validates device before destructive operations. Prevents accidental system drive formatting." }, { "command": "sudo health-control storage-encrypt --device \"${REMOVABLE_DEVICE:?Set REMOVABLE_DEVICE after reviewing lsblk output}\"", "description": "Encrypt storage device", "expectedOutput": "Storage device encrypted successfully", "notes": "Backup data before encryption" }, { "command": "sudo health-control storage-wipe --device \"${REMOVABLE_DEVICE:?Set REMOVABLE_DEVICE after reviewing lsblk output}\" --passes 3", "description": "Securely wipe storage device", "expectedOutput": "Storage device wiped securely", "notes": "Data will be permanently destroyed" }, { "command": "sudo health-control container-create --path /secure/data.img --size 500", "description": "Create encrypted container (500MB)", "expectedOutput": "Encrypted container created successfully", "notes": "Creates LUKS2-encrypted container file. You'll be prompted for password interactively.\nContainer file path is supplied with the required --path option." }, { "command": "sudo health-control container-create --path /tmp/secure.img --size 100", "description": "Create small encrypted container (100MB)", "expectedOutput": "Container created: /tmp/secure.img, Size: 100 MB", "notes": "Smaller size for testing. Password will be prompted." }, { "command": "sudo health-control container-mount --container /secure/data.img --mount-point /mnt/secure", "description": "Mount encrypted container", "expectedOutput": "Container mounted successfully", "notes": "You'll be prompted for the container password.\nMount point will be created automatically if it doesn't exist." }, { "command": "sudo health-control container-unmount --mount-point /mnt/secure", "description": "Unmount encrypted container", "expectedOutput": "Container unmounted: /mnt/secure", "notes": "Automatically closes the LUKS mapper device." }, { "command": "sudo health-control encryption-tune --profile balanced", "description": "Recommend or apply LUKS encryption tuning settings", "expectedOutput": "Encryption tuning recommendations (dry-run by default)", "notes": "--profile defaults to balanced (also performance, security). Optional --cipher, --key-size, --iter-time, --device, --benchmark. Runs as a dry-run unless --apply is given." }, { "command": "sudo health-control create-persistence-other-os --device \"${REMOVABLE_DEVICE:?Set REMOVABLE_DEVICE after reviewing lsblk output}\" --os-type kali --force", "description": "Create persistence storage for another live OS (Kali, Parrot, or Tails)", "expectedOutput": "Persistence media created for the target OS", "notes": "āš ļø --device and --os-type are required; targets/formats the given partition. --force is required for non-interactive use (dashboard/scripts/--json). Add --encrypted (optionally with --password) for LUKS." } ], "id": "17_storage_encryption", "title": "Storage Encryption & Secure Containers" }, { "description": "Security scoring and reporting", "examples": [ { "command": "health-control security-score", "description": "Calculate overall security score", "expectedOutput": "Shows score (0-100), security level (Critical/Basic/Fair/Good/Excellent), and actionable fixes" }, { "command": "health-control security-score --json", "description": "Get security score in JSON format", "expectedOutput": "Full JSON with category breakdowns (Core/Network/Hardening/Device/Advanced), individual check scores, and specific remediation commands" }, { "command": "sudo health-control security-report", "description": "Generate comprehensive security report", "expectedOutput": "Detailed security assessment report" }, { "command": "sudo health-control security-report --json", "description": "Generate security report in JSON format", "expectedOutput": "JSON formatted security report" }, { "command": "sudo health-control security-history --days 30", "description": "View security score history for last 30 days", "expectedOutput": "Security score trends and historical data", "notes": "Shows security improvements over time" }, { "command": "sudo health-control security-history --days 7 --json", "description": "View last 7 days security history in JSON", "expectedOutput": "JSON formatted security history" }, { "command": "sudo health-control security-remediate", "description": "Review security fixes before applying", "expectedOutput": "Security fix recommendations displayed", "notes": "Manual review mode for security fixes" }, { "command": "sudo health-control rootkit-scan-enhanced --deep", "description": "Run the enhanced rootkit scanner", "expectedOutput": "Enhanced rootkit scan results", "notes": "Add --deep to perform a thorough deep scan." }, { "command": "sudo health-control clamav-scan --path / --recursive", "description": "Scan the filesystem for malware with ClamAV", "expectedOutput": "ClamAV scan results with any detections", "notes": "--path defaults to /. Add --recursive to descend into subdirectories and --quarantine to isolate infected files." }, { "command": "sudo health-control security-profile --value balanced", "description": "Set the security profile and scoring thresholds", "expectedOutput": "Security profile set to balanced", "notes": "--value is required: minimal, balanced, or paranoid." }, { "command": "sudo health-control security-schedule --value daily", "description": "Schedule automated security assessments", "expectedOutput": "Security assessment schedule updated", "notes": "--value is required: hourly, daily, weekly, monthly, or disable." } ], "id": "18_security_assessment", "title": "Security Assessment & Scoring" }, { "description": "Hardware-level security features", "examples": [ { "command": "sudo health-control hardware-rng-verify", "description": "Verify hardware random number generator", "expectedOutput": "Hardware RNG status and quality", "notes": "Checks if hardware RNG is available and functioning properly for cryptographic operations" }, { "command": "sudo health-control entropy-status", "description": "Check system entropy status", "expectedOutput": "Entropy pool status and quality", "notes": "Monitors available entropy for secure random number generation, critical for encryption" }, { "command": "sudo health-control boot-integrity-check", "description": "Check boot integrity", "expectedOutput": "Boot integrity verification results", "notes": "Verifies boot process integrity to detect tampering or unauthorized modifications to bootloader/kernel" } ], "id": "19_hardware_security", "title": "Hardware Security" }, { "description": "System information, diagnostics, and hardware/service management", "examples": [ { "command": "sudo health-control offline-info-system", "description": "Display comprehensive system information", "expectedOutput": "Complete system details and configuration" }, { "command": "sudo health-control offline-info-hardware", "description": "Display hardware information", "expectedOutput": "Hardware components and specifications" }, { "command": "sudo health-control offline-info-hardware --json", "description": "Display hardware information in JSON", "expectedOutput": "JSON formatted hardware details" }, { "command": "sudo health-control offline-info-process", "description": "Display process information", "expectedOutput": "Running processes and resource usage" }, { "command": "sudo health-control offline-info-security", "description": "Display security configuration", "expectedOutput": "Security settings and status" }, { "command": "sudo health-control offline-info-network", "description": "Display network configuration", "expectedOutput": "Network interfaces and settings" }, { "command": "sudo health-control offline-info-user", "description": "Display user information", "expectedOutput": "User accounts and permissions" }, { "command": "sudo health-control offline-info-storage", "description": "Display storage information", "expectedOutput": "Disk usage and filesystem details" }, { "command": "sudo health-control offline-info-services", "description": "Display services information", "expectedOutput": "System services status" }, { "command": "sudo health-control offline-info-all", "description": "Display all system information", "expectedOutput": "Complete system information report" }, { "command": "sudo health-control offline-bluetooth --action check", "description": "Check Bluetooth status", "expectedOutput": "Bluetooth status: enabled/disabled" }, { "command": "sudo health-control offline-bluetooth --action enable", "description": "Enable Bluetooth service", "expectedOutput": "Bluetooth enabled successfully" }, { "command": "sudo health-control offline-bluetooth --action disable", "description": "Disable Bluetooth service", "expectedOutput": "Bluetooth disabled successfully" }, { "command": "sudo health-control offline-wifi --action check", "description": "Check WiFi status", "expectedOutput": "WiFi status: enabled/disabled" }, { "command": "sudo health-control offline-wifi --action enable", "description": "Enable WiFi service", "expectedOutput": "WiFi enabled successfully" }, { "command": "sudo health-control offline-wifi --action disable", "description": "Disable WiFi with persistent blacklisting", "expectedOutput": "WiFi disabled and blacklisted" }, { "command": "sudo health-control offline-webcam --action check", "description": "Check webcam status", "expectedOutput": "Webcam status: enabled/disabled" }, { "command": "sudo health-control offline-webcam --action enable", "description": "Enable webcam devices", "expectedOutput": "Webcam access enabled" }, { "command": "sudo health-control offline-webcam --action disable", "description": "Disable webcam devices", "expectedOutput": "Webcam access disabled" }, { "command": "sudo health-control offline-microphone --action check", "description": "Check microphone status", "expectedOutput": "Microphone status: enabled/disabled" }, { "command": "sudo health-control offline-microphone --action enable", "description": "Enable microphone devices", "expectedOutput": "Microphone access enabled" }, { "command": "sudo health-control offline-microphone --action disable", "description": "Disable microphone devices", "expectedOutput": "Microphone access disabled" }, { "command": "sudo health-control offline-screen-lock --action check", "description": "Check automatic screen lock status", "expectedOutput": "Screen lock status reported" }, { "command": "sudo health-control offline-screen-lock --action enable", "description": "Enable automatic screen lock", "expectedOutput": "Screen lock enabled" }, { "command": "sudo health-control offline-screen-lock --action disable", "description": "Disable automatic screen lock", "expectedOutput": "Screen lock disabled" }, { "command": "sudo health-control offline-systemlogs --action check", "description": "Check system logging status", "expectedOutput": "System logging status reported" }, { "command": "sudo health-control offline-systemlogs --action enable", "description": "Enable system logging", "expectedOutput": "System logging enabled" }, { "command": "sudo health-control offline-systemlogs --action disable", "description": "Disable system logging", "expectedOutput": "System logging disabled" }, { "command": "sudo health-control offline-cups --action check", "description": "Check CUPS printing service status", "expectedOutput": "CUPS status reported" }, { "command": "sudo health-control offline-cups --action enable", "description": "Enable CUPS printing service", "expectedOutput": "CUPS printing enabled" }, { "command": "sudo health-control offline-cups --action disable", "description": "Disable CUPS printing service", "expectedOutput": "CUPS printing disabled" }, { "command": "sudo health-control offline-networkmanager --action check", "description": "Check NetworkManager status", "expectedOutput": "NetworkManager status reported" }, { "command": "sudo health-control offline-networkmanager --action enable", "description": "Enable NetworkManager", "expectedOutput": "NetworkManager enabled" }, { "command": "sudo health-control offline-networkmanager --action disable", "description": "Disable NetworkManager", "expectedOutput": "NetworkManager disabled" }, { "command": "sudo health-control offline-numlock --action check", "description": "Check NumLock-on-boot status", "expectedOutput": "NumLock status reported" }, { "command": "sudo health-control offline-numlock --action enable", "description": "Enable NumLock on boot", "expectedOutput": "NumLock enabled on boot" }, { "command": "sudo health-control offline-numlock --action disable", "description": "Disable NumLock on boot", "expectedOutput": "NumLock disabled on boot" }, { "command": "sudo health-control offline-cmdhistory --action check", "description": "Check command history logging status", "expectedOutput": "Command history status reported" }, { "command": "sudo health-control offline-cmdhistory --action enable", "description": "Enable command history logging", "expectedOutput": "Command history enabled" }, { "command": "sudo health-control offline-cmdhistory --action disable", "description": "Disable command history logging", "expectedOutput": "Command history disabled" }, { "command": "sudo health-control offline-autologin --action check", "description": "Check automatic login status", "expectedOutput": "Automatic login status reported" }, { "command": "sudo health-control offline-autologin --action enable", "description": "Enable automatic login", "expectedOutput": "Automatic login enabled" }, { "command": "sudo health-control offline-autologin --action disable", "description": "Disable automatic login", "expectedOutput": "Automatic login disabled" }, { "command": "sudo health-control offline-fdlimit --action check", "description": "Check current file descriptor limits", "expectedOutput": "File descriptor limits reported" }, { "command": "sudo health-control offline-fdlimit --action enable --soft-limit 1024 --hard-limit 4096", "description": "Set file descriptor limits", "expectedOutput": "File descriptor limit set" }, { "command": "sudo health-control offline-fdlimit --action disable", "description": "Revert file descriptor limits to defaults", "expectedOutput": "File descriptor limits reverted" }, { "command": "sudo health-control offline-netoptimize --action check", "description": "Check network optimization status", "expectedOutput": "Network optimization status reported" }, { "command": "sudo health-control offline-netoptimize --action enable", "description": "Enable network optimizations", "expectedOutput": "Network optimizations enabled" }, { "command": "sudo health-control offline-netoptimize --action disable", "description": "Disable network optimizations", "expectedOutput": "Network optimizations disabled" }, { "command": "sudo health-control offline-bbr --action check", "description": "Check BBR congestion control status", "expectedOutput": "BBR status reported" }, { "command": "sudo health-control offline-bbr --action enable", "description": "Enable BBR congestion control", "expectedOutput": "BBR congestion control enabled" }, { "command": "sudo health-control offline-bbr --action disable", "description": "Disable BBR congestion control", "expectedOutput": "BBR congestion control disabled" }, { "command": "sudo health-control offline-ifspeed --action check", "description": "Check current interface speed configuration", "expectedOutput": "Interface speed reported" }, { "command": "sudo health-control offline-ifspeed --action enable --interface eth0 --speed 1000", "description": "Configure interface speed", "expectedOutput": "Interface speed configured" }, { "command": "sudo health-control offline-ifspeed --action disable --interface eth0", "description": "Revert interface speed to auto-negotiation", "expectedOutput": "Interface speed reset" }, { "command": "sudo health-control offline-avahi --action check", "description": "Check Avahi service discovery status", "expectedOutput": "Avahi status reported", "notes": "Supported services: avahi, modem-manager, ssh, apache, nginx, docker, mysql, postgresql" }, { "command": "sudo health-control offline-avahi --action enable", "description": "Enable Avahi service discovery", "expectedOutput": "Avahi service enabled" }, { "command": "sudo health-control offline-avahi --action disable", "description": "Disable Avahi service discovery", "expectedOutput": "Avahi service disabled" }, { "command": "sudo health-control offline-modem-manager --action check", "description": "Check ModemManager service status", "expectedOutput": "ModemManager status reported" }, { "command": "sudo health-control offline-modem-manager --action enable", "description": "Enable ModemManager service", "expectedOutput": "ModemManager enabled" }, { "command": "sudo health-control offline-modem-manager --action disable", "description": "Disable ModemManager service", "expectedOutput": "ModemManager disabled" }, { "command": "sudo health-control offline-ssh --action check", "description": "Check SSH service status", "expectedOutput": "SSH status reported" }, { "command": "sudo health-control offline-ssh --action enable", "description": "Enable SSH service", "expectedOutput": "SSH service enabled" }, { "command": "sudo health-control offline-ssh --action disable", "description": "Disable SSH service", "expectedOutput": "SSH service disabled" }, { "command": "sudo health-control offline-apache --action check", "description": "Check Apache web server status", "expectedOutput": "Apache status reported" }, { "command": "sudo health-control offline-apache --action enable", "description": "Enable Apache web server", "expectedOutput": "Apache web server enabled" }, { "command": "sudo health-control offline-apache --action disable", "description": "Disable Apache web server", "expectedOutput": "Apache web server disabled" }, { "command": "sudo health-control offline-nginx --action check", "description": "Check Nginx web server status", "expectedOutput": "Nginx status reported" }, { "command": "sudo health-control offline-nginx --action enable", "description": "Enable Nginx web server", "expectedOutput": "Nginx web server enabled" }, { "command": "sudo health-control offline-nginx --action disable", "description": "Disable Nginx web server", "expectedOutput": "Nginx web server disabled" }, { "command": "sudo health-control offline-docker --action check", "description": "Check Docker service status", "expectedOutput": "Docker status reported" }, { "command": "sudo health-control offline-docker --action enable", "description": "Enable Docker service", "expectedOutput": "Docker service enabled" }, { "command": "sudo health-control offline-docker --action disable", "description": "Disable Docker service", "expectedOutput": "Docker service disabled" }, { "command": "sudo health-control offline-mysql --action check", "description": "Check MySQL database service status", "expectedOutput": "MySQL status reported" }, { "command": "sudo health-control offline-mysql --action enable", "description": "Enable MySQL database service", "expectedOutput": "MySQL service enabled" }, { "command": "sudo health-control offline-mysql --action disable", "description": "Disable MySQL database service", "expectedOutput": "MySQL service disabled" }, { "command": "sudo health-control offline-postgresql --action check", "description": "Check PostgreSQL database service status", "expectedOutput": "PostgreSQL status reported" }, { "command": "sudo health-control offline-postgresql --action enable", "description": "Enable PostgreSQL database service", "expectedOutput": "PostgreSQL service enabled" }, { "command": "sudo health-control offline-postgresql --action disable", "description": "Disable PostgreSQL database service", "expectedOutput": "PostgreSQL service disabled" }, { "command": "sudo health-control offline-usb-storage --action enable", "description": "Enable USB storage devices", "expectedOutput": "USB storage access enabled" }, { "command": "sudo health-control offline-usb-storage --action disable", "description": "Disable USB storage devices", "expectedOutput": "USB storage access blocked", "notes": "Unloads the USB storage kernel modules, so USB drives stop working entirely until you re-enable them. Anything currently mounted from USB should be unmounted first or you risk data loss." }, { "command": "health-control ping", "description": "Lightweight connectivity ping helper (used by conky panels)", "expectedOutput": "Ping reachability result", "notes": "Takes no arguments. Fast helper for status panels." }, { "command": "health-control process-age --process tor", "description": "Report how long a tracked process has been running", "expectedOutput": "Process age/uptime for the requested service", "notes": "--process is required and must be 'vpn' or 'tor'." } ], "id": "20_system_info_offline", "title": "System Information & Offline Actions" }, { "description": "Generate secure passwords using multiple methods with batch support (auto-detects installed packages)", "examples": [ { "command": "sudo health-control genpass", "description": "Generate one password using all three methods", "expectedOutput": "Three passwords (pass, pwgen, xkcdpass)", "notes": "Automatically uses system packages if available, falls back to native implementations" }, { "command": "sudo health-control genpass --method pwgen --count 10", "description": "Generate 10 random passwords using pwgen method", "expectedOutput": "10 random passwords", "notes": "Use --count for batch generation; max 1000 per method" }, { "command": "sudo health-control genpass --method xkcdpass --count 50", "description": "Generate 50 memorable XKCD-style passphrases", "expectedOutput": "50 word-based passphrases", "notes": "XKCD method creates memorable multi-word passwords" }, { "command": "sudo health-control genpass --count 90", "description": "Generate 90 passwords from each method (270 total)", "expectedOutput": "270 passwords (90 from each of the 3 methods)", "notes": "When using --count without --method, generates specified count from ALL methods" }, { "command": "sudo health-control genpass --method pwgen --count 20 --length 32 --symbols \"@-_!#$\"", "description": "Generate 20 custom passwords with specific length and symbols", "expectedOutput": "20 passwords with 32 characters including specified symbols", "notes": "Customize password generation with --length and --symbols options" }, { "command": "sudo health-control genpass --uppercase --digits --count 15", "description": "Generate 15 passwords with only uppercase letters and digits", "expectedOutput": "15 alphanumeric passwords (uppercase + digits only)" }, { "command": "sudo health-control genpass --count 100 --json", "description": "Generate 100 passwords from each method in JSON format", "expectedOutput": "JSON array with 300 passwords", "notes": "JSON output ideal for scripting and automation" }, { "command": "sudo health-control genpass --force-native --count 25", "description": "Force use of native Rust implementations (skip package detection)", "expectedOutput": "25 passwords from each method using native fallbacks", "notes": "Useful for testing or when system packages are unreliable" } ], "id": "21_password_generation", "title": "Password Generation" }, { "description": "Automatic RAM wiping on shutdown with multiple policies (custom, sdmem, both, auto), installation, configuration, testing, and cold boot attack defenses", "examples": [ { "command": "# WORKFLOW: Setting up RAM wipe on shutdown", "description": "Complete workflow for first-time RAM wipe setup", "expectedOutput": "Step-by-step guide", "notes": "STEP 1: Install hooks (REQUIRED FIRST): sudo health-control wipe-ram-install\nSTEP 2: Configure policy (OPTIONAL): sudo health-control wipe-ram-config --policy sdmem\nSTEP 3: Enable if disabled: sudo health-control ram-wipe-enable\nSTEP 4: Verify status: sudo health-control ram-wipe-status\n\nKEY DIFFERENCES:\nā€¢ wipe-ram-install = FIRST-TIME SETUP (installs systemd shutdown hooks)\nā€¢ ram-wipe-enable = ENABLE/DISABLE (turns functionality on/off, hooks must exist)\nā€¢ wipe-ram-config = UPDATE SETTINGS (change policy, passes, time budget)\nā€¢ wipe-ram = MANUAL EXECUTION (test or emergency wipe NOW, not on shutdown)" }, { "command": "sudo health-control wipe-ram-install", "description": "Install RAM wipe system with default settings (kodachi-wiper policy, 60s timeout)", "expectedOutput": "RAM wipe system installed successfully", "notes": "FIRST-TIME SETUP - Installs systemd hooks, configures policies, detects Kicksecure compatibility. Creates /etc/kodachi-ram-wipe.conf with defaults" }, { "command": "sudo health-control wipe-ram-install --policy kodachi-wiper --time 60", "description": "Install RAM wipe with kodachi-wiper policy and 60 second time budget", "expectedOutput": "Installed with kodachi-wiper policy", "notes": "Fastest installation - Single-pass wipe, suitable for systems with <8GB RAM or frequent reboots" }, { "command": "sudo health-control wipe-ram-install --policy sdmem --passes 3", "description": "Install RAM wipe with sdmem policy using 3 overwrite passes", "expectedOutput": "Installed with sdmem 3-pass policy", "notes": "SECURE INSTALLATION - 3 passes (random, zeros, random). Good balance of security and speed. Recommended for 8-16GB RAM systems" }, { "command": "sudo health-control wipe-ram-install --policy both --time 60", "description": "Install the hybrid policy (kodachi-wiper then sdmem) with a 60 second shutdown time budget", "expectedOutput": "Installed with the \"both\" policy and a 60s time budget", "notes": "HYBRID APPROACH - \"both\" runs kodachi-wiper (fast) and sdmem (thorough) inside the --time budget. The flags are --force, --policy, --time and --passes: there is no --split flag. Recommended budget: 60-90s for desktops and laptops, 120-300s for servers" }, { "command": "sudo health-control wipe-ram-install --force", "description": "Force installation even if Kicksecure/Whonix RAM wipe detected", "expectedOutput": "Force installed, Kicksecure overridden", "notes": "OVERRIDE MODE - Bypasses Kicksecure detection. Use when you want Kodachi's RAM wipe instead of Kicksecure's built-in wipe. May cause conflicts" }, { "command": "sudo health-control ram-wipe-status", "description": "Check RAM wipe configuration and current status", "expectedOutput": "RAM wipe status with memory info and auto-wipe settings", "notes": "Shows: enabled/disabled state, current policy (kodachi-wiper/sdmem/both/auto), time budget, sdmem passes, total RAM size, Kicksecure detection" }, { "command": "sudo health-control ram-wipe-status --json", "description": "RAM wipe status in JSON format for automation", "expectedOutput": "JSON formatted status with all configuration details", "notes": "JSON OUTPUT DEMO - Shows all config fields in machine-readable format for scripts and monitoring systems" }, { "command": "sudo health-control wipe-ram-config --policy auto", "description": "Update existing RAM wipe policy to auto-detection", "expectedOutput": "Policy updated to auto", "notes": "Changes what happens at every shutdown from now on. A larger time budget or more passes means a longer shutdown; too small a budget means RAM is only partially wiped. Check the result with 'sudo health-control ram-wipe-status'." }, { "command": "sudo health-control wipe-ram-config --passes 5 --split 70", "description": "Update sdmem passes to 5 and time split to 70/30", "expectedOutput": "Multiple parameters updated", "notes": "PASS COUNT - More passes = more thorough but slower. 1-3=fast, 4-6=balanced, 7-9=maximum. SPLIT - Higher kodachi-wiper%=speed, higher sdmem%=security" }, { "command": "sudo health-control ram-wipe-enable", "description": "Enable RAM wipe configuration (hooks must be installed first)", "expectedOutput": "RAM wipe configuration enabled + WARNING if hooks not installed", "notes": "IMPORTANT: This only enables the CONFIG. You must run 'wipe-ram-install' FIRST to install systemd hooks. Will show clear warning if hooks are missing." }, { "command": "sudo health-control ram-wipe-disable", "description": "Disable automatic RAM wiping", "expectedOutput": "RAM wipe disabled successfully", "notes": "WARNING - Disabling RAM wipe leaves sensitive data in RAM accessible to physical attacks" }, { "command": "sudo health-control wipe-ram-test", "description": "Test RAM wipe system with dry-run (no actual wiping)", "expectedOutput": "RAM wipe test completed successfully", "notes": "SAFE TESTING - Simulates wipe operation without actually overwriting memory. Tests configuration, timing, and policy execution. Use before first real wipe" }, { "command": "sudo health-control wipe-ram-test --policy kodachi-wiper --time 10", "description": "Test kodachi-wiper policy with 10 second time budget", "expectedOutput": "Kodachi-wiper policy test completed in 10s", "notes": "Quick test - Validates kodachi-wiper policy works correctly. 10s budget ensures fast test completion" }, { "command": "sudo health-control wipe-ram-test --json", "description": "Test RAM wipe with detailed JSON diagnostic metrics", "expectedOutput": "JSON test results with performance data", "notes": "DIAGNOSTIC OUTPUT - Returns timing, memory stats, policy execution details, and potential issues. Essential for troubleshooting" }, { "command": "sudo health-control wipe-ram", "description": "Execute RAM wipe operation manually with configured policy", "expectedOutput": "RAM wiped successfully", "notes": "ADVANCED - Manually trigger RAM wipe using system configuration. Automatically called by shutdown hooks. Use for testing or emergency wipe" }, { "command": "sudo health-control wipe-ram --shutdown-mode", "description": "Execute RAM wipe optimized for shutdown context", "expectedOutput": "RAM wiped in shutdown mode", "notes": "INTERNAL USE - Shutdown-optimized mode disables unnecessary checks and output. Used by systemd shutdown hooks" }, { "command": "sudo health-control wipe-ram --policy kodachi-wiper", "description": "Execute RAM wipe using kodachi-wiper overwrite policy", "expectedOutput": "RAM wiped with kodachi-wiper policy", "notes": "POLICY: Kodachi-wiper fast overwrite algorithm - Single pass with random data. Fastest but least thorough (60-120 seconds for 8GB)" }, { "command": "sudo health-control wipe-ram --policy sdmem", "description": "Execute RAM wipe using sdmem utility (multiple passes)", "expectedOutput": "RAM wiped with sdmem", "notes": "POLICY: sdmem (secure-delete memory) - Multiple passes with patterns. Slower but more thorough (3-7 passes configurable). Government-grade erasure" }, { "command": "sudo health-control wipe-ram --policy both", "description": "Execute RAM wipe using both kodachi-wiper AND sdmem sequentially", "expectedOutput": "RAM wiped with combined policy", "notes": "POLICY: Maximum security - Kodachi-wiper FIRST (fast pass), then sdmem (thorough passes). Best security but longest time. Recommended for high-security environments" }, { "command": "sudo health-control wipe-ram --policy auto", "description": "Execute RAM wipe with automatic policy selection based on available RAM", "expectedOutput": "RAM wiped with auto-detected policy", "notes": "POLICY: Auto-detection - Chooses policy based on RAM size and available time: <4GB=kodachi-wiper, 4-16GB=both, >16GB=sdmem. Balances speed and security" }, { "command": "sudo health-control wipe-ram --time 120", "description": "Execute RAM wipe with 120 second time budget", "expectedOutput": "RAM wiped within time limit", "notes": "TIME BUDGET - Maximum seconds allowed for wipe operation. System will shutdown/reboot when time expires even if wipe incomplete. Critical for automated shutdowns" }, { "command": "sudo health-control ram-wipe-detect-kicksecure", "description": "Detect if Kicksecure/Whonix RAM wipe is installed", "expectedOutput": "Kicksecure detection results", "notes": "COMPATIBILITY CHECK - Detects Kicksecure's ram-wipe-on-boot package. Prevents conflicts between Kodachi and Kicksecure RAM wipe systems" }, { "command": "sudo health-control ram-wipe-update --policy auto --time 150", "description": "Update RAM wipe policy to auto with 150 second time budget", "expectedOutput": "Policy and time budget updated", "notes": "SMART MODE - System automatically selects best policy based on: RAM size, shutdown urgency, battery status (laptops). Recommended for most users" }, { "command": "sudo health-control coldboot-defense-enable", "description": "Enable cold boot attack defense mechanisms", "expectedOutput": "Cold boot defense enabled", "notes": "PHYSICAL SECURITY - Protects against cold boot attacks that recover encryption keys from RAM after power loss. Enables: RAM overwriting on shutdown, memory scrambling, DMA protection" }, { "command": "sudo health-control coldboot-defense-disable", "description": "Disable cold boot attack defense", "expectedOutput": "Cold boot defense disabled", "notes": "WARNING - Disabling leaves encryption keys vulnerable to physical RAM extraction attacks. Only disable if you have alternative physical security" }, { "command": "sudo health-control coldboot-defense-status", "description": "Show current cold boot attack defense status", "expectedOutput": "Cold boot defense status (enabled/disabled) and configuration", "notes": "READ-ONLY: Takes no arguments. Reports the active cold boot protection state." }, { "command": "sudo health-control ram-wipe", "description": "āš ļø Wipe system RAM contents immediately", "expectedOutput": "RAM wipe executed", "notes": "āš ļø DANGEROUS: Overwrites memory contents and takes no arguments. Use ram-wipe-enable/-disable to manage the on-shutdown policy instead." } ], "id": "22_ram_wipe_cold_boot", "title": "RAM Wipe & Cold Boot Protection" }, { "description": "Swap space enable/disable, configuration, encryption with dm-crypt, and performance tuning with swappiness and cache pressure settings", "examples": [ { "command": "sudo health-control swap-enable", "description": "Enable and activate swap space for memory overflow", "expectedOutput": "Swap enabled successfully", "notes": "STABILITY FEATURE - Activates swap partitions/files for memory overflow. Improves system stability under memory pressure but may leak sensitive data to disk" }, { "command": "sudo health-control swap-disable", "description": "Disable and deactivate all swap space", "expectedOutput": "Swap disabled successfully", "notes": "SECURITY FEATURE - Deactivates all swap to prevent disk leakage of sensitive data. May cause out-of-memory errors if RAM insufficient" }, { "command": "sudo health-control swap-status", "description": "Check swap status, devices, size, and usage", "expectedOutput": "Swap devices list with usage statistics", "notes": "Shows: active swap devices, total/used/available size, swap usage percentage, encryption status, swappiness value" }, { "command": "sudo health-control swap-configure --swappiness 10 --cache-pressure 100", "description": "Configure swap parameters for optimal performance", "expectedOutput": "Swap parameters configured", "notes": "PERFORMANCE TUNING - Swappiness (0-100): 0=never swap, 10=minimal, 60=default, 100=aggressive. Cache pressure controls VFS cache retention (default 100)" }, { "command": "sudo health-control swap-encrypt", "description": "Encrypt swap with random key generated on each boot", "expectedOutput": "Swap space encrypted", "notes": "ENCRYPTION SECURITY - Uses dm-crypt with random key per boot. Protects swapped memory from offline disk forensics. Slight performance impact (~5-10%)" }, { "command": "sudo health-control swap-decrypt", "description": "Remove swap encryption and revert to plain swap", "expectedOutput": "Swap decrypted", "notes": "WARNING - Removes encryption protection. Swapped data will be readable from disk in clear text. Only use if encryption causes performance issues" }, { "command": "sudo health-control swap-encrypt-status", "description": "Check swap encryption status and configuration", "expectedOutput": "Encryption status with cipher details", "notes": "Shows: encryption enabled/disabled, cipher type (aes-xts-plain64), key size, whether using random keys, encrypted device mapper name" }, { "command": "sudo health-control enable-swap", "description": "Enable swap (alternative command alias)", "expectedOutput": "Swap enabled" }, { "command": "sudo health-control disable-swap", "description": "Disable swap (alternative command alias)", "expectedOutput": "Swap disabled", "notes": "Disabling swap frees the swap device of any paged-out secrets, but processes that were relying on swap can be OOM-killed on a low-memory machine. Save your work first." } ], "id": "23_swap_management", "title": "Swap Management & Encryption" }, { "description": "Memory usage statistics, cache cleaning, and memory optimization without data loss", "examples": [ { "command": "sudo health-control memory-stats", "description": "Show current memory usage statistics (total, available, used, cached)", "expectedOutput": "Memory usage breakdown with utilization percentages" }, { "command": "sudo health-control memory-stats --json-human", "description": "Memory statistics in human-readable JSON format", "expectedOutput": "Pretty-printed JSON with human-readable sizes (MB/GB)", "notes": "JSON OUTPUT DEMO - Use --json for compact machine-readable format, --json-human for readable format with color and formatting" }, { "command": "sudo health-control memory-clean", "description": "Clean memory caches and buffers (pagecache, dentries, inodes)", "expectedOutput": "Memory cleaned successfully", "notes": "Safe operation - drops caches but does NOT kill processes. Improves available memory without data loss" }, { "command": "sudo health-control memory-force-clean", "description": "Force aggressive memory cleanup (sync + drop_caches=3)", "expectedOutput": "Memory force cleaned", "notes": "ADVANCED - Kills top memory-consuming process + aggressive cache drop. Use with caution in production" } ], "id": "24_memory_stats_cleanup", "title": "Memory Statistics & Cleanup" }, { "description": "Secure process memory wiping before termination and per-process memory limits using cgroups for browsers and applications", "examples": [ { "command": "sudo health-control memory-wipe", "description": "Securely wipe memory contents (anti-forensics)", "expectedOutput": "Memory wiped securely", "notes": "SECURITY FEATURE - Overwrites memory with random data to prevent forensic recovery. Used for sensitive operations" }, { "command": "sudo health-control memory-wipe-process --value firefox", "description": "Securely wipe Firefox process memory before termination", "expectedOutput": "Firefox process memory wiped successfully", "notes": "PRIVACY PROTECTION - Clears sensitive data (passwords, session keys, browsing history) from process memory before kill" }, { "command": "sudo health-control memory-wipe-process --value chrome", "description": "Securely wipe Chrome browser memory", "expectedOutput": "Chrome process memory wiped successfully", "notes": "Clears authentication tokens, cached passwords, and browsing data from Chrome's memory space" }, { "command": "sudo health-control memory-wipe-process --value thunderbird", "description": "Securely wipe Thunderbird email client memory", "expectedOutput": "Thunderbird process memory wiped successfully", "notes": "Erases email content, credentials, and encryption keys from email client memory" }, { "command": "sudo health-control memory-wipe-process --value tor-browser", "description": "Securely wipe Tor Browser memory", "expectedOutput": "Tor Browser process memory wiped successfully", "notes": "Clears Tor circuit keys, browsing session data, and cached .onion addresses from memory" }, { "command": "sudo health-control memory-limits --value firefox --limit-mb 2048", "description": "Set Firefox memory limit to 2048 MB using cgroups", "expectedOutput": "Firefox memory limit set to 2048 MB", "notes": "RESOURCE CONTROL - Uses Linux cgroups to enforce hard memory limits per process. Prevents single process from consuming excessive memory. Process killed if limit exceeded" }, { "command": "sudo health-control memory-limits --value chrome --limit-mb 1024", "description": "Set Chrome memory limit to 1024 MB", "expectedOutput": "Chrome memory limit set to 1024 MB", "notes": "Chrome often consumes excessive memory. Limiting prevents system slowdown. Note: Limit applies to total browser memory across all processes" }, { "command": "sudo health-control memory-limits --value tor-browser --limit-mb 1536", "description": "Set Tor Browser memory limit to 1536 MB", "expectedOutput": "Tor Browser memory limit set to 1536 MB", "notes": "Tor Browser requires more memory than standard browsers due to Tor circuit management and enhanced security features. 1536MB recommended minimum" }, { "command": "sudo health-control memory-limits", "description": "List all configured memory limits (run with no flags to list)", "expectedOutput": "\"Process Memory Limits:\" followed by one \"<process>: <N> MB\" line per configured process", "notes": "Listing is the no-flag form of this command. There is no --list flag: the only flags are --value <PROCESS> and --limit-mb <MB>, which must be given together to SET a limit. Add --json for machine-readable output" } ], "id": "25_process_memory_security", "title": "Process Memory Security" }, { "description": "Hardware keyboard shortcuts for emergency operations via kodachi-session-helper daemon. All commands use LOCAL session tokens (no online auth required). Works fully offline. Session token is read automatically from $XDG_RUNTIME_DIR/kodachi-session-helper/session.token", "examples": [ { "command": "sudo health-control emergency-trigger --plan dashboard --dry-run", "description": "Dry-run dashboard nuke to test without executing destructive actions", "expectedOutput": "DRY RUN: Would execute plan 'dashboard' - no changes made", "notes": "SAFE TESTING - Validates session token and plan without executing. Use for testing shortcut configuration and daemon integration. Session token read from $XDG_RUNTIME_DIR/kodachi-session-helper/session.token" }, { "command": "sudo health-control emergency-trigger --plan dashboard", "description": "Trigger dashboard nuke via emergency shortcut (wipe dashboard data, logs, configs)", "expectedOutput": "Emergency plan 'dashboard' executed successfully", "notes": "KEYBOARD: The session helper uses the shortcut currently configured in the dashboard. Hold the approved combo for roughly 2-3 seconds. The global trigger is silent and does not reopen the dashboard UI." }, { "command": "sudo health-control emergency-trigger --plan luks --device \"${LUKS_DEVICE:?Set LUKS_DEVICE from health-control luks-detect output}\"", "description": "Trigger LUKS nuke via emergency shortcut (destroy encrypted partition headers)", "expectedOutput": "Emergency plan 'luks' executed successfully", "notes": "KEYBOARD: Uses the dashboard-configured approved combo. Hold it for roughly 2-3 seconds. IRREVERSIBLE - destroys LUKS headers making encrypted data unrecoverable. --device is required for luks and both plans." }, { "command": "sudo health-control emergency-trigger --plan both --device \"${LUKS_DEVICE:?Set LUKS_DEVICE from health-control luks-detect output}\"", "description": "Trigger full nuke (dashboard + LUKS combined) via emergency shortcut", "expectedOutput": "Emergency plan 'both' executed successfully", "notes": "KEYBOARD: Uses the dashboard-configured approved combo and should be held for roughly 2-3 seconds. Combines dashboard-nuke and luks-nuke for maximum data destruction. IRREVERSIBLE." }, { "command": "sudo health-control emergency-trigger --plan dashboard --json", "description": "Trigger emergency action with JSON output for automation", "expectedOutput": "JSON result with plan, success status, execution time, and details", "notes": "JSON output includes: plan name, success status, execution duration, affected components. Useful for logging and monitoring." }, { "command": "sudo health-control emergency-trigger --plan luks --device \"${LUKS_DEVICE:?Set LUKS_DEVICE from health-control luks-detect output}\" --dry-run --json", "description": "Dry-run LUKS nuke with JSON output for pre-flight validation", "expectedOutput": "JSON dry-run result showing planned actions without executing", "notes": "Combines --dry-run and --json for safe testing with machine-readable output. Ideal for dashboard integration testing." }, { "command": "sudo health-control emergency-trigger --plan both --device \"${LUKS_DEVICE:?Set LUKS_DEVICE from health-control luks-detect output}\" --force --silent", "description": "Force-trigger full nuke silently (skip readiness checks, suppress output)", "expectedOutput": "(no stdout output - silent mode)", "notes": "DAEMON MODE - Used by kodachi-session-helper daemon. --force skips readiness checks, --silent suppresses stdout. For automated invocation only." }, { "command": "sudo health-control emergency-lockdown --delay 300 --plan dashboard --dry-run", "description": "Dry-run a 5-minute delayed lockdown for dashboard nuke", "expectedOutput": "DRY RUN: Would start 300s countdown for plan 'dashboard'", "notes": "SAFE TESTING - Preview lockdown without starting timer. Validates parameters and session token." }, { "command": "sudo health-control emergency-lockdown --delay 300 --plan dashboard", "description": "Start a 5-minute delayed lockdown that triggers dashboard nuke", "expectedOutput": "Lockdown started: plan 'dashboard' in 300 seconds", "notes": "DELAYED LOCKDOWN - Schedules emergency action after countdown. User can cancel before timer expires with emergency-lockdown-cancel. Useful for dead-man-switch scenarios." }, { "command": "sudo health-control emergency-lockdown --delay 60 --plan luks --device \"${LUKS_DEVICE:?Set LUKS_DEVICE from health-control luks-detect output}\"", "description": "Start a 1-minute delayed lockdown for LUKS nuke", "expectedOutput": "Lockdown started for the selected LUKS device with a 60-second countdown", "notes": "SHORT TIMER - 60 second countdown before LUKS header destruction. Cancel with emergency-lockdown-cancel if needed." }, { "command": "health-control emergency-lockdown-status", "description": "Check if a delayed lockdown is currently active and its remaining time", "expectedOutput": "Lockdown active: plan 'dashboard', 247 seconds remaining", "notes": "READ-ONLY - No session token required. Shows: active status, scheduled plan, remaining seconds, start time. Returns 'No active lockdown' if none pending." }, { "command": "health-control emergency-lockdown-status --json", "description": "Check lockdown status in JSON format for dashboard integration", "expectedOutput": "JSON with active, plan, device, delay_seconds, remaining_seconds, started_at, expires_at", "notes": "JSON output for dashboard polling and monitoring systems. No authentication required for status checks." }, { "command": "sudo health-control emergency-lockdown-cancel", "description": "Cancel an active delayed lockdown before it triggers", "expectedOutput": "Lockdown cancelled successfully", "notes": "Cancels pending lockdown and kills the timer process. Requires valid session token. Returns error if no lockdown is active." }, { "command": "sudo health-control emergency-lockdown-cancel --json", "description": "Cancel lockdown with JSON confirmation output", "expectedOutput": "JSON confirmation with cancelled plan details and timestamp", "notes": "Machine-readable cancellation confirmation for dashboard integration." } ], "id": "26_emergency_shortcuts", "title": "Emergency Shortcuts - Keyboard-Triggered Actions" }, { "description": "Conky, screensaver, DPMS, and session power controls", "examples": [ { "command": "health-control conky-enable", "description": "Start Conky widget", "expectedOutput": "Conky enabled. Running: yes" }, { "command": "health-control conky-disable", "description": "Stop Conky widget", "expectedOutput": "Conky disabled. Running: no" }, { "command": "health-control conky-status --json", "description": "Conky status as JSON", "expectedOutput": "JSON with installed, running, start_on_boot, service_available, autostart_enabled fields" }, { "command": "health-control conky-boot-enable", "description": "Enable Conky autostart on boot", "expectedOutput": "Conky boot enabled. Start on boot: true" }, { "command": "health-control conky-boot-disable", "description": "Disable Conky autostart", "expectedOutput": "Conky boot disabled. Start on boot: false" }, { "command": "health-control screensaver-disable", "description": "Disable XFCE screensaver", "expectedOutput": "Screensaver disabled. Running: no" }, { "command": "health-control screensaver-enable", "description": "Re-enable screensaver", "expectedOutput": "Screensaver enabled. Running: yes" }, { "command": "health-control screensaver-status --json", "description": "Check screensaver state", "expectedOutput": "JSON with screensaver_running, screensaver_autostart_enabled, screensaver_binary_available" }, { "command": "health-control dpms-disable", "description": "Keep display always on", "expectedOutput": "DPMS disabled. Display will stay on." }, { "command": "health-control dpms-enable", "description": "Restore display power saving", "expectedOutput": "DPMS enabled. Display power management active." }, { "command": "health-control dpms-status --json", "description": "Check DPMS timeouts", "expectedOutput": "JSON with dpms_enabled, standby_seconds, suspend_seconds, off_seconds, blanking fields" }, { "command": "health-control lock-screen", "description": "Lock screen immediately", "expectedOutput": "Screen locked via loginctl", "notes": "Multi-fallback: loginctl > xdg-screensaver > xflock4" }, { "command": "health-control session-logout", "description": "End XFCE session", "expectedOutput": "Session logout initiated via xfce4-session-logout", "notes": "Fallback: loginctl terminate-user" }, { "command": "health-control suspend", "description": "Suspend to RAM", "expectedOutput": "Suspend initiated via xfce4-session-logout", "notes": "Fallback: systemctl suspend" }, { "command": "health-control conky-mask-enable", "description": "Mask sensitive info in Conky panels for safe screenshots", "expectedOutput": "Privacy masking enabled. Conky panels will show masked data." }, { "command": "health-control conky-mask-disable", "description": "Unmask Conky panels to show real data", "expectedOutput": "Privacy masking disabled. Conky panels will show real data." }, { "command": "health-control conky-mask-status", "description": "Check if Conky privacy masking is active", "expectedOutput": "Privacy masking: disabled" } ], "id": "30_display_power", "title": "Display & Power" } ], "description": "Usage examples for health-control", "name": "health-control", "quickReference": [ "health-control --help", "health-control --version", "health-control --info --json", "health-control --examples", "health-control security-score # security posture score, read-only", "health-control kill-switch-status # is the kill switch armed", "sudo health-control internet-status # current traffic-block state", "sudo health-control enable --type watch-guard --watch vpn --method nftables # auto kill switch on VPN drop", "sudo health-control watch-guard status # active watch-guards and their config ids", "sudo health-control unblock-internet # restore connectivity after a block" ] }, "errors": [], "metadata": { "executionTime": 29, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:22.555923030Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-learner", "path": "/opt/kodachi/dashboard/hooks/ai-learner", "timestamp": "2026-07-21T01:54:23Z", "file_info": { "size": 24381444, "sha256": "282af9d807bf64f570680947890c7c1eb2d5a5445e1839fd18f2266f9f3a1c1b" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:23.409072156Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-learner", "version": "9.8.4", "author": "Warith Al Maawali <warith@digi77.com>", "description": "AI learning engine for continuous improvement and performance analysis", "copyright": "Ā© 2013-2026 Warith Al Maawali - Kodachi OS", "website": "https://kodachi.cloud", "license": "LicenseRef-Kodachi-SAN-1.1", "features": [ "Feedback aggregation and analysis", "Incremental learning with convergence detection", "Performance tracking and trend analysis", "Multi-format report generation (JSON, Markdown, HTML)" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:23.633092942Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-learner", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:23.928712879Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-learner", "description": "AI learning engine for continuous improvement and performance analysis", "usage": "ai-learner [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Analysis Operations", "commands": [ { "name": "analyze", "description": "Analyze model performance and trends", "usage": "ai-learner analyze [OPTIONS]", "options": [ { "flag": "--period <PERIOD>", "description": "Accuracy and F1 window: last-day, last-7-days, last-30-days, last-year or all-time. Confidence always uses the last 7 days", "default": "last-7-days" }, { "flag": "--metric <METRIC>", "description": "Metric to report: accuracy, confidence, f1-score or all", "default": "all" }, { "flag": "--learning-curve", "description": "Append the all-time learning-run accuracy series to the selected metric summary" }, { "flag": "--json", "description": "Emit the per-intent metrics as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-learner analyze", "ai-learner analyze --period last-7-days", "ai-learner analyze --metric accuracy --json", "ai-learner analyze --learning-curve" ] } ] }, { "category": "Learning Operations", "commands": [ { "name": "learn", "description": "Run learning cycle to improve model based on feedback", "usage": "ai-learner learn [OPTIONS]", "options": [ { "flag": "--incremental", "description": "Only process feedback recorded since the last learning run. Needs a previous full run to have a baseline" }, { "flag": "--learning-rate <RATE>", "description": "Override the learning rate. Must be finite and inside (0.0, 1.0]", "default": "the engine default" }, { "flag": "--min-feedback <COUNT>", "description": "Skip the learning run unless at least this many feedback entries exist" }, { "flag": "--output-policy", "description": "After learning, write and sign results/ai-policy.json (intent thresholds, tool allowlist, risk mode). Overwrites the existing policy" }, { "flag": "--json", "description": "Emit the learning metrics as a JSON envelope" } ], "requires_sudo": false, "examples": [ "sudo ai-learner learn", "sudo ai-learner learn --incremental", "sudo ai-learner learn --learning-rate 0.05 --min-feedback 100", "sudo ai-learner learn --output-policy --json" ] } ] }, { "category": "Reporting Operations", "commands": [ { "name": "report", "description": "Generate comprehensive performance reports", "usage": "ai-learner report [OPTIONS]", "options": [ { "flag": "--format <FORMAT>", "description": "Body of the report: json, markdown or html", "default": "json" }, { "flag": "--output <FILE>", "description": "Write the report to this file. The path is ALREADY relative to the results directory, so pass a bare filename (not results/<name>). Parent (\"..\") components are rejected", "default": "print to stdout" }, { "flag": "--period <PERIOD>", "description": "Window to report on: last-day, last-7-days, last-30-days, last-year or all-time", "default": "last-30-days" }, { "flag": "--json", "description": "Wrap the result in a JSON envelope. Independent of --format, which selects the report body" } ], "requires_sudo": false, "examples": [ "sudo ai-learner report", "sudo ai-learner report --format markdown", "sudo ai-learner report --format html --output learning-report.html", "sudo ai-learner report --period all-time --format markdown --json" ] } ] }, { "category": "Status Operations", "commands": [ { "name": "status", "description": "Show ai-learner status, database health, and activity metrics", "usage": "ai-learner status [OPTIONS]", "options": [ { "flag": "--verbose", "description": "Also report the SQLite statistics: size, pages, freelist and fragmentation percent" }, { "flag": "--json", "description": "Emit initialized, database_path, database_exists, the totals, the last-7-days counts and the last_* timestamps as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-learner status", "ai-learner status --json", "ai-learner status --verbose" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format <FORMAT>", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter <FIELD1,FIELD2>", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields <FIELD_LIST>", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit <NUMBER>", "description": "Limit number of results returned" }, { "flag": "--offset <NUMBER>", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir <PATH>", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port <PORT>", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level <LEVEL>", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config <FILE>", "description": "Use custom configuration file" }, { "flag": "--timeout <SECS>", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "5": "File not found", "4": "Network error", "1": "General error", "0": "Success", "2": "Invalid arguments", "3": "Permission denied" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:24.998935379Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-learner", "description": "Usage examples for ai-learner", "categories": [ { "id": "1_basic_learning", "title": "Basic Learning Operations", "description": "Run a learning cycle over the collected prediction feedback and update the model weights. Every `learn` run is auth-gated and writes into the results directory.", "examples": [ { "command": "sudo ai-learner learn", "description": "Run a full learning cycle over all stored feedback", "expectedOutput": "A learning summary: feedback processed, accuracy before and after, and whether the run converged", "notes": "Requires a prior `online-auth` login (learn is not read-only)." }, { "command": "sudo ai-learner learn --incremental", "description": "Only process feedback that arrived since the last learning run", "expectedOutput": "A shorter summary covering just the new feedback delta", "notes": "Requires a prior `online-auth` login. Incremental only makes sense once a full `learn` has established a baseline; with no previous run there is no delta to apply." }, { "command": "sudo ai-learner learn --json", "description": "Full learning cycle with a machine-readable result", "expectedOutput": "Envelope with the learning metrics for the run", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner learn --learning-rate 0.05", "description": "Slow the convergence down with a smaller learning rate", "expectedOutput": "The same learning summary, computed with the rate you passed", "notes": "Requires a prior `online-auth` login. --learning-rate must be finite and inside (0.0, 1.0]; anything else is rejected." }, { "command": "sudo ai-learner learn --min-feedback 100", "description": "Refuse to learn unless at least 100 feedback entries exist", "expectedOutput": "Either a normal learning run, or a message that learning was skipped for insufficient feedback", "notes": "Requires a prior `online-auth` login. Use this to avoid retraining on a statistically meaningless sample." }, { "command": "sudo ai-learner learn --learning-rate 0.05 --min-feedback 100 --json", "description": "A tuned learning run with both guards and JSON output", "expectedOutput": "Envelope with the metrics of the run, or the skipped reason", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner learn --output-policy", "description": "Learn, then write the signed AI policy file the runtime reads", "expectedOutput": "The learning summary plus results/ai-policy.json written and signed", "notes": "Requires a prior `online-auth` login. The policy holds the intent thresholds, the tool allowlist and the risk mode, and it OVERWRITES results/ai-policy.json." }, { "command": "sudo ai-learner learn --output-policy --json", "description": "Learn and regenerate the policy in one step, machine-readable", "expectedOutput": "Envelope with the learning metrics; after a successful learning run, results/ai-policy.json is also written and signed", "notes": "Requires a prior `online-auth` login. The JSON envelope does not include the policy path or signature. If minimum feedback is not met, learning is skipped and no policy is generated." } ] }, { "id": "2_performance_analysis", "title": "Performance Analysis", "description": "Look at how well the model is doing, per intent and over time. `analyze` is read-only: it needs no authentication and no root.", "examples": [ { "command": "ai-learner analyze", "description": "Analyze every metric over the default window", "expectedOutput": "A per-intent breakdown of accuracy, confidence and F1 score over the last 7 days", "notes": "--period defaults to last-7-days and --metric defaults to all, so bare `analyze` is not an empty query." }, { "command": "ai-learner analyze --period last-7-days", "description": "Analyze performance over the past week", "expectedOutput": "Per-intent accuracy and the trend across the window", "notes": "--period accepts exactly: last-day, last-7-days, last-30-days, last-year, all-time." }, { "command": "ai-learner analyze --metric accuracy --json", "description": "Just the accuracy metric, machine-readable", "expectedOutput": "Envelope with the per-intent accuracy breakdown", "notes": "--metric accepts exactly: accuracy, confidence, f1-score, all (default all)." }, { "command": "ai-learner analyze --metric confidence", "description": "See how certain the model is about its predictions", "expectedOutput": "The confidence score distribution per intent" }, { "command": "ai-learner analyze --metric f1-score --json", "description": "F1 score per intent (precision and recall balanced)", "expectedOutput": "Envelope with the F1 score for each intent" }, { "command": "ai-learner analyze --learning-curve", "description": "Get the accuracy-over-time series so you can spot a plateau", "expectedOutput": "The default metric summary plus the all-time learning-run accuracy series", "notes": "--learning-curve appends the complete learning-run history; --period does not filter the curve." }, { "command": "ai-learner analyze --period all-time --json", "description": "Analyze the entire history, machine-readable", "expectedOutput": "Envelope with all-time accuracy and F1 data plus the confidence report for the last 7 days", "notes": "--period applies to accuracy and F1. Confidence remains a fixed 7-day calibration window." } ] }, { "id": "3_reporting", "title": "Report Generation", "description": "Turn the analysis into a JSON, Markdown or HTML document. `report` can write files, so it is auth-gated and its --output path is confined to the results directory.", "examples": [ { "command": "sudo ai-learner report", "description": "Print a summary report as JSON on stdout", "expectedOutput": "A JSON report covering the last 30 days", "notes": "Requires a prior `online-auth` login (report is auth-gated because --output can write files). --format defaults to json and --period to last-30-days." }, { "command": "sudo ai-learner report --format markdown", "description": "Print the report as Markdown so you can paste it somewhere", "expectedOutput": "A Markdown document with the metric tables", "notes": "Requires a prior `online-auth` login. --format accepts exactly: json, markdown, html." }, { "command": "sudo ai-learner report --period last-7-days", "description": "A weekly report instead of the 30-day default", "expectedOutput": "A JSON report covering the last 7 days", "notes": "Requires a prior `online-auth` login. --period accepts: last-day, last-7-days, last-30-days, last-year, all-time." }, { "command": "sudo ai-learner report --format html --output learning-report.html", "description": "Write an HTML report to a file", "expectedOutput": "The report is written to the results directory as learning-report.html and the path is printed", "notes": "Requires a prior `online-auth` login. --output is ALREADY relative to the results directory: pass a bare filename. Do not prefix it with `results/` or the file lands in results/results/. Parent (\"..\") components are rejected." }, { "command": "sudo ai-learner report --period all-time --format markdown --output learning-report.md", "description": "Write a full-history Markdown report to a file", "expectedOutput": "learning-report.md written inside the results directory", "notes": "Requires a prior `online-auth` login. Overwrites the file if it already exists." }, { "command": "sudo ai-learner report --period all-time --format markdown --json", "description": "Wrap the Markdown report inside a JSON envelope for a pipeline", "expectedOutput": "Envelope whose payload carries the rendered Markdown", "notes": "Requires a prior `online-auth` login. --format selects the REPORT body; --json selects the ENVELOPE. They are independent." } ] }, { "id": "4_status", "title": "Status and Health", "description": "Check what the learner has collected so far. `status` is read-only: no authentication, no root.", "examples": [ { "command": "ai-learner status", "description": "See whether the learner is initialized and what it has stored", "expectedOutput": "Whether the database exists, plus totals for predictions, feedback entries, learning runs, user queries and intents, and the last prediction, feedback and learning-run timestamps" }, { "command": "ai-learner status --json", "description": "The same status as a JSON envelope for the dashboard", "expectedOutput": "Envelope with initialized, database_path, database_exists, the totals map, the last-7-days map and the last_* timestamps" }, { "command": "ai-learner status --verbose", "description": "Add the SQLite database statistics", "expectedOutput": "The status block plus total_size_bytes, total_size_mb, page_count, page_size, freelist_count and fragmentation_percent", "notes": "Use the fragmentation percentage to decide whether the database needs a vacuum." } ] }, { "id": "5_workflow", "title": "Typical Workflow", "description": "The order these commands are normally run in: check what has been collected, look at the trend, then learn and publish a report.", "examples": [ { "command": "ai-learner status --json", "description": "Step 1: is there enough feedback to be worth learning from", "expectedOutput": "Envelope with the feedback and prediction totals" }, { "command": "ai-learner analyze --period last-day --json", "description": "Step 2: has accuracy moved in the last day", "expectedOutput": "Envelope with the per-intent metrics for the last day" }, { "command": "sudo ai-learner learn --incremental", "description": "Step 3: fold the new feedback into the model", "expectedOutput": "An incremental learning summary with the convergence data", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner report --period last-7-days --format markdown --output weekly-review.md", "description": "Step 4: leave a weekly artifact behind for review", "expectedOutput": "weekly-review.md written inside the results directory", "notes": "Requires a prior `online-auth` login. The path is relative to the results directory already." } ] } ], "quickReference": [ "ai-learner --help", "ai-learner --version", "ai-learner --info --json", "ai-learner --examples", "ai-learner status", "ai-learner analyze --period last-7-days", "sudo ai-learner learn", "sudo ai-learner report --format markdown" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "ai-discovery", "path": "/opt/kodachi/dashboard/hooks/ai-discovery", "timestamp": "2026-07-21T01:54:26Z", "file_info": { "size": 1771784, "sha256": "e042d9cbaf3459d31136acd16a5cd19ff1d3847a1f6e17bbe398d61435e3c7c5" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:26.110252153Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-discovery", "version": "9.8.4", "author": "Warith Al Maawali", "description": "Kodachi Auto-Discovery Daemon - Monitors and indexes Rust service binaries", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Binary file watching with inotify", "Automatic command extraction from -e --json", "Live command registry updates", "Daemon process management" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:26.261515403Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-discovery", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:26.391450687Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-discovery", "description": "Kodachi Auto-Discovery Daemon - Monitors and indexes Rust service binaries", "usage": "ai-discovery [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Daemon Control", "commands": [ { "name": "start", "description": "Start the auto-discovery daemon", "usage": "ai-discovery start [OPTIONS]", "options": [ { "flag": "-f, --foreground", "description": "Run the watch loop in this terminal instead of detaching (blocks until Ctrl+C)", "default": "false (daemonize)" }, { "flag": "--json", "description": "Emit status, mode, binaries_watched, commands_indexed, pid and already_running as JSON" } ], "requires_sudo": true, "examples": [ "sudo ai-discovery start", "sudo ai-discovery start --foreground", "sudo ai-discovery start --json" ] }, { "name": "status", "description": "Show daemon status", "usage": "ai-discovery status [OPTIONS]", "options": [ { "flag": "--json", "description": "Emit the status envelope as JSON (running, pid, binaries_watched, watch_paths)" } ], "requires_sudo": false, "examples": [ "ai-discovery status", "ai-discovery status --json" ] } ] }, { "category": "Registry Management", "commands": [ { "name": "reindex", "description": "Force reindex all binaries", "usage": "ai-discovery reindex [OPTIONS]", "options": [ { "flag": "--service <NAME>", "description": "Reindex only this service. NAME is the deployed binary filename and must match exactly", "default": "all watched binaries" }, { "flag": "--json", "description": "Emit status, binaries_scanned, commands_indexed and errors as JSON" } ], "requires_sudo": false, "examples": [ "ai-discovery reindex", "ai-discovery reindex --json", "ai-discovery reindex --service health-control" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format <FORMAT>", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter <FIELD1,FIELD2>", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields <FIELD_LIST>", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit <NUMBER>", "description": "Limit number of results returned" }, { "flag": "--offset <NUMBER>", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir <PATH>", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port <PORT>", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level <LEVEL>", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config <FILE>", "description": "Use custom configuration file" }, { "flag": "--timeout <SECS>", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "3": "Permission denied", "1": "General error", "4": "Network error", "5": "File not found", "2": "Invalid arguments" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:26.657186435Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-discovery", "description": "Usage examples for ai-discovery", "categories": [ { "id": "0_quick_start", "title": "Quick Start", "description": "The three things you will actually run: check the daemon, start it, reindex.", "examples": [ { "command": "ai-discovery status", "description": "Check whether the discovery daemon is running", "expectedOutput": "Running or Stopped, the PID if running, the number of watched paths, and the watch path list" }, { "command": "sudo ai-discovery start", "description": "Start the daemon in the background", "expectedOutput": "Daemon started successfully with mode, binaries watched, commands indexed and PID", "notes": "Needs root: the PID file and daemon log are written under the install directory." }, { "command": "ai-discovery reindex", "description": "Rescan every watched binary and count its commands", "expectedOutput": "Reindexing completed with binaries scanned, commands indexed and error count" } ] }, { "id": "1_daemon_control", "title": "Daemon Control", "description": "Start the auto-discovery daemon and check its state. The daemon watches the deployed Rust service binaries and re-reads their command lists when they change.", "examples": [ { "command": "sudo ai-discovery start", "description": "Start the daemon detached in the background", "expectedOutput": "Mode: Background, plus binaries watched, commands indexed and the PID of the spawned daemon", "notes": "Needs root (writes the PID file and log under the install directory). If a daemon is already running its PID is reused and 'Existing daemon reused' is printed." }, { "command": "sudo ai-discovery start --foreground", "description": "Run the watch loop in this terminal instead of detaching", "expectedOutput": "'Daemon running in foreground. Press Ctrl+C to stop.' then a line per binary create, modify or remove event", "notes": "Blocks until Ctrl+C. -f is the short form of --foreground." }, { "command": "sudo ai-discovery start --json", "description": "Start in the background and get the result as JSON", "expectedOutput": "Envelope with status, mode, binaries_watched, commands_indexed, pid and already_running" }, { "command": "ai-discovery status", "description": "Check daemon liveness and the watch configuration", "expectedOutput": "Status Running or Stopped, PID when running, the count of watched paths, and each watch path", "notes": "Liveness is read from the PID file plus /proc, so a stale PID file still reports Stopped." }, { "command": "ai-discovery status --json", "description": "Machine-readable daemon status for scripts and the dashboard", "expectedOutput": "Envelope with exactly: running, pid, binaries_watched, watch_paths" } ] }, { "id": "2_registry_management", "title": "Registry Management", "description": "Force a rescan of the watched binaries. Each binary is invoked with -e --json and its commands are extracted and deduplicated.", "examples": [ { "command": "ai-discovery reindex", "description": "Reindex every watched Rust service binary", "expectedOutput": "'Indexed N from <path>' per binary, then a summary with binaries scanned, commands indexed and errors", "notes": "Per-binary progress goes to stderr so it does not pollute --json on stdout." }, { "command": "ai-discovery reindex --json", "description": "Reindex everything and capture the totals as JSON", "expectedOutput": "Envelope with status, binaries_scanned, commands_indexed and errors" }, { "command": "ai-discovery reindex --service health-control", "description": "Reindex a single service instead of the whole set", "expectedOutput": "One 'Indexed N from ...' line and a summary with binaries scanned: 1", "notes": "--service takes the deployed binary FILENAME and must match exactly. A name outside the configured indexable set is rejected before scanning." }, { "command": "ai-discovery reindex --service ai-monitor --json", "description": "Targeted reindex of one service with structured output", "expectedOutput": "Envelope with binaries_scanned: 1 and the command count for ai-monitor" } ] } ], "quickReference": [ "ai-discovery --help", "ai-discovery --version", "ai-discovery --info --json", "ai-discovery --examples", "ai-discovery status", "ai-discovery reindex", "sudo ai-discovery start" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "deps-checker", "path": "/opt/kodachi/dashboard/hooks/deps-checker", "timestamp": "2026-07-21T01:54:27Z", "file_info": { "size": 2978592, "sha256": "520722353135c1736ea955de78186d7aea05b60e2386d3e727d79c128046c6f7" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Dependency checker for Kodachi OS Rust binaries - Validates system dependencies and generates installation scripts", "features": [ "Multi-profile dependency checking (minimal/full)", "Automatic missing package installation", "Installation script generation for multiple shells", "Software Bill of Materials (SBOM) generation", "External dependency database support", "Comprehensive JSON output for automation", "Strict mode for CI/CD pipelines", "Dry-run mode for safe previewing" ], "license": "Proprietary", "name": "deps-checker", "securityFeatures": { "authentication": "Secure package repository authentication", "encryption": "TLS for all package downloads", "inputValidation": "All user inputs are validated and sanitized", "rateLimiting": "Built-in rate limiting for package operations" }, "systemRequirements": { "dependencies": [ "apt-get", "dpkg", "curl" ], "os": "Linux (Debian-based, Kodachi OS)", "privileges": "root/sudo required for package installation" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:27.182470123Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "deps-checker", "rustVersion": "rustc 1.97.0 (2d8144b78 2026-07-07)", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:27.318754828Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Dependency Checking", "commands": [ { "description": "Check dependencies for a specific binary (read-only, no root needed)", "examples": [ "deps-checker check dns-switch", "deps-checker check dns-switch --profile minimal", "deps-checker check dns-switch --json", "deps-checker check dns-switch --strict" ], "name": "check", "options": [ { "description": "Kodachi binary whose dependency profile should be checked", "flag": "<BINARY>", "required": true }, { "default": "full", "description": "Dependency profile to use: minimal or full. Any other value is rejected", "flag": "-p, --profile <NAME>", "required": false }, { "description": "Load an external dependency database (JSON) on top of the built-in one", "flag": "--db <PATH>", "required": false }, { "default": "false", "description": "Exit 1 on warnings as well as on missing packages. Use this in CI", "flag": "--strict", "required": false }, { "default": "false", "description": "Emit a CycloneDX JSON Software Bill of Materials instead of the report", "flag": "--sbom", "required": false }, { "description": "Write the report to a file. Relative paths only: the path is resolved inside the execution folder, and an absolute path or one containing '..' is rejected", "flag": "-o, --output <FILE>", "required": false }, { "default": "false", "description": "With --json, also save the JSON to an auto-named file under results/", "flag": "--json-save", "required": false }, { "description": "With --json, save the JSON under the given relative filename (same containment rules as -o)", "flag": "--json-export <FILE>", "required": false } ], "requires_sudo": false, "usage": "deps-checker check [OPTIONS] <BINARY>" }, { "description": "Check dependencies for all 30 known binaries (read-only, no root needed)", "examples": [ "deps-checker check-all", "deps-checker check-all --json", "deps-checker check-all --sbom --json", "deps-checker check-all --strict --quiet" ], "name": "check-all", "options": [ { "default": "full", "description": "Dependency profile to use: minimal or full. Any other value is rejected", "flag": "-p, --profile <NAME>", "required": false }, { "default": "false", "description": "Exit 1 on warnings as well as on missing packages. Use this in CI", "flag": "--strict", "required": false }, { "default": "false", "description": "Emit a CycloneDX JSON Software Bill of Materials instead of the report", "flag": "--sbom", "required": false }, { "description": "Load an external dependency database (JSON) on top of the built-in one", "flag": "--db <PATH>", "required": false }, { "description": "Write the report to a file. Relative paths only, resolved inside the execution folder", "flag": "-o, --output <FILE>", "required": false }, { "default": "false", "description": "With --json, also save the JSON to an auto-named file under results/", "flag": "--json-save", "required": false }, { "description": "With --json, save the JSON under the given relative filename (same containment rules as -o)", "flag": "--json-export <FILE>", "required": false } ], "requires_sudo": false, "usage": "deps-checker check-all [OPTIONS]" } ] }, { "category": "Package Management", "commands": [ { "description": "Install the missing dependency packages with apt-get. Omit BINARY and it covers ALL 30 known binaries ('install-missing all' does the same). Debian-family systems only", "examples": [ "sudo deps-checker install-missing --dry-run", "sudo deps-checker install-missing dns-switch", "sudo deps-checker install-missing all --dry-run" ], "name": "install-missing", "options": [ { "default": "all", "description": "Optional Kodachi binary name, or 'all'. When omitted, all known binaries are covered", "flag": "[BINARY|all]", "required": false }, { "default": "false", "description": "Print the apt-get command that would run, install nothing. Always do this first when no BINARY is given", "flag": "--dry-run", "required": false }, { "default": "full", "description": "Dependency profile to install for: minimal or full", "flag": "-p, --profile <NAME>", "required": false }, { "description": "Load an external dependency database (JSON) on top of the built-in one", "flag": "--db <PATH>", "required": false } ], "requires_sudo": true, "usage": "sudo deps-checker install-missing [BINARY|all] [OPTIONS]" }, { "description": "Turn a JSON check result into an install script. It reads the JSON from STDIN, so it must be on the right-hand side of a pipe: with no pipe it waits for input forever", "examples": [ "deps-checker check-all --json | deps-checker generate-script", "deps-checker check-all --json | deps-checker generate-script --shell fish", "deps-checker check-all --json | sudo deps-checker generate-script --execute" ], "name": "generate-script", "options": [ { "default": "bash", "description": "Shell syntax to emit: bash, zsh or fish", "flag": "--shell <TYPE>", "required": false }, { "default": "false", "description": "Run the generated script instead of printing it. It calls apt-get, so it needs root and it changes the system. Combine with --dry-run to see the script without running it", "flag": "--execute", "required": false }, { "default": "false", "description": "Mark the script as a dry run: with --execute it is printed instead of executed", "flag": "--dry-run", "required": false } ], "requires_sudo": false, "usage": "deps-checker check-all --json | deps-checker generate-script [OPTIONS]" } ] }, { "category": "Information", "commands": [ { "description": "List all known Kodachi binaries", "examples": [ "deps-checker list-binaries", "deps-checker list-binaries --json" ], "name": "list-binaries", "options": [], "requires_sudo": false, "usage": "deps-checker list-binaries" }, { "description": "List the dependency profiles available for one binary. BINARY is required", "examples": [ "deps-checker list-profiles dns-switch", "deps-checker list-profiles dns-switch --json" ], "name": "list-profiles", "options": [ { "description": "Kodachi binary whose available dependency profiles should be listed", "flag": "<BINARY>", "required": true } ], "requires_sudo": false, "usage": "deps-checker list-profiles <BINARY>" } ] } ], "description": "Dependency checker for Kodachi OS Rust binaries", "environmentVariables": [ { "default": "unset", "description": "Print how each package was resolved (which candidate matched, which fell back) to stderr. Set it when a dependency is reported missing and you do not believe it", "name": "DEPS_DEBUG", "values": "set to any value to enable" } ], "exitCodes": { "0": "All required dependencies satisfied (warnings alone still exit 0 unless --strict is passed)", "1": "A required package is missing, a version conflict was found, a warning was found while --strict is set, or the command itself failed (bad binary name, bad profile, rejected output path, non-Debian system for install-missing)" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Output in pretty-printed JSON format", "flag": "--json-pretty" }, { "description": "Output in human-friendly JSON format with colors", "flag": "--json-human" }, { "description": "Save JSON output to an auto-generated results file", "flag": "--json-save" }, { "description": "Export JSON output to a specified file", "flag": "--json-export <FILE>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Dependency profile (minimal/full, default: full)", "flag": "-p, --profile <NAME>" }, { "description": "Shell syntax for generated scripts", "flag": "--shell <TYPE>" }, { "description": "Write output to a file", "flag": "-o, --output <FILE>" }, { "description": "Use an external dependency database", "flag": "--db <FILE>" }, { "description": "Treat warnings as errors", "flag": "--strict" }, { "description": "Show what would happen without executing", "flag": "--dry-run" }, { "description": "Execute a generated installation script after confirmation", "flag": "--execute" }, { "description": "Generate a CycloneDX JSON SBOM", "flag": "--sbom" } ], "name": "deps-checker", "usage": "deps-checker [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:27.449294051Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Find out what a binary needs and whether the system has it. Checking is read-only: do not run it with sudo, or the files it writes under results/ end up owned by root and the next non-root run fails on them.", "examples": [ { "command": "deps-checker check dns-switch", "description": "See which packages dns-switch needs and which are missing", "expectedOutput": "A per-package table (package, required version, installed version, OK or MISSING) and a verdict line" }, { "command": "deps-checker check dns-switch --profile minimal", "description": "Check only the packages dns-switch cannot run without", "expectedOutput": "The same table, restricted to the minimal profile", "notes": "Only 'minimal' and 'full' exist. Any other profile name is rejected with 'Invalid profile'." }, { "command": "deps-checker check-all", "description": "Check every one of the 30 known binaries at once", "expectedOutput": "One status line per binary plus totals for OK, missing and warning" }, { "command": "deps-checker check-all --json -o report.json", "description": "Check everything and write the report to a file", "expectedOutput": "Nothing on the terminal; report.json is written inside the execution folder", "notes": "-o takes a RELATIVE path only. An absolute path, or one containing '..', is rejected: output is confined to the execution folder." }, { "command": "deps-checker list-binaries", "description": "See the names accepted by check and install-missing", "expectedOutput": "The 30 binary names, one per line", "notes": "A name outside this list is rejected, so start here if 'Invalid binary name' surprises you." } ], "id": "1_basic", "title": "BASIC COMMANDS" }, { "description": "Machine-readable JSON output options", "examples": [ { "command": "deps-checker check dns-switch --json", "description": "Compact JSON output", "expectedOutput": "Single-line JSON" }, { "command": "deps-checker check dns-switch --json-pretty", "description": "Pretty-printed JSON output", "expectedOutput": "Indented JSON for readability" }, { "command": "deps-checker check dns-switch --json-human", "description": "Human-friendly colored JSON output", "expectedOutput": "Colored JSON output for terminals" }, { "command": "deps-checker check-all --json --json-save", "description": "Save JSON output to auto-generated file", "expectedOutput": "File saved to results/ directory" } ], "id": "2_json", "title": "JSON OUTPUT" }, { "description": "generate-script turns a JSON check result into an install script. It ALWAYS reads its input from stdin, so it only makes sense on the right-hand side of a pipe. Run it with no pipe and it sits there waiting for input that never comes.", "examples": [ { "command": "deps-checker check-all --json | deps-checker generate-script", "description": "Write out a bash script that installs everything currently missing", "expectedOutput": "A bash script on stdout (apt-get update, then apt-get install of the missing packages). Nothing is installed" }, { "command": "deps-checker check-all --json | deps-checker generate-script --shell fish > install-deps.fish", "description": "Emit the script in fish syntax and save it for review", "expectedOutput": "install-deps.fish written; nothing runs", "notes": "--shell accepts bash (default), zsh and fish. Anything else is rejected." }, { "command": "deps-checker check-all --json | deps-checker generate-script --dry-run", "description": "Produce the script in dry-run form, so that even running it would only print what it intends to install", "expectedOutput": "The script text, marked as a dry run", "notes": "generate-script never installs anything on its own. Only --execute does that." }, { "command": "deps-checker check-all --json | sudo deps-checker generate-script --execute", "description": "Generate the install script and immediately run it", "expectedOutput": "apt-get output as the missing packages are installed", "notes": "CHANGES THE SYSTEM. This runs apt-get as root and installs packages. Preview it first with the same pipeline minus --execute, and pass --execute --dry-run if you want it to print the script instead of running it." } ], "id": "3_script", "title": "SCRIPT GENERATION" }, { "description": "List known binaries and available dependency profiles", "examples": [ { "command": "deps-checker list-binaries", "description": "List all known Kodachi binaries", "expectedOutput": "Names of every binary deps-checker can check" }, { "command": "deps-checker list-binaries --json", "description": "List all known Kodachi binaries as JSON", "expectedOutput": "Machine-readable array of binary names" }, { "command": "deps-checker list-profiles dns-switch", "description": "List available dependency profiles for a binary", "expectedOutput": "Shows profiles such as minimal and full", "notes": "Requires a binary name argument" }, { "command": "deps-checker list-profiles dns-switch --json", "description": "List dependency profiles for a binary as JSON", "expectedOutput": "Machine-readable profiles for the given binary" } ], "id": "4_information", "title": "INFORMATION" }, { "description": "install-missing is the only command here that changes the system. It runs apt-get, so it needs root and it only works on Debian-family distributions. Everything else in this tool is read-only.", "examples": [ { "command": "sudo deps-checker install-missing --dry-run", "description": "See exactly what a full install would do, before doing it", "expectedOutput": "The planned command, for example: apt-get update && apt-get install -y <packages>. Nothing is installed", "notes": "With no BINARY, install-missing covers ALL 30 binaries, which is the widest thing this tool can do. Always dry-run this form first." }, { "command": "sudo deps-checker install-missing dns-leak", "description": "Install only the packages that dns-leak is missing", "expectedOutput": "apt-get installs the missing packages for dns-leak, then a summary", "notes": "CHANGES THE SYSTEM: installs Debian packages as root." }, { "command": "sudo deps-checker install-missing all --dry-run", "description": "Same as install-missing with no binary name: 'all' is an accepted alias for every known binary", "expectedOutput": "The planned apt-get command covering the union of all missing packages" }, { "command": "sudo deps-checker install-missing dns-switch --profile minimal", "description": "Install only what dns-switch strictly needs, skipping optional packages", "expectedOutput": "A shorter package list than the default full profile", "notes": "CHANGES THE SYSTEM. Drop --profile and you get the full set." } ], "id": "5_installing", "title": "INSTALLING MISSING PACKAGES" }, { "description": "Exit codes and machine-readable artifacts. deps-checker exits 1 when a required package is missing; add --strict and it also exits 1 on warnings, which is usually what a pipeline wants.", "examples": [ { "command": "deps-checker check-all --strict --quiet", "description": "Fail a build on missing packages AND on warnings", "expectedOutput": "No output on success (exit 0); exit 1 if anything is missing or any warning was raised", "notes": "Without --strict, warnings still exit 0. That difference is the whole point of the flag." }, { "command": "deps-checker check-all --sbom --json --json-export sbom.json", "description": "Produce a CycloneDX Software Bill of Materials for every binary and keep it", "expectedOutput": "CycloneDX JSON on stdout and in sbom.json inside the execution folder", "notes": "--json-export takes a relative filename only, resolved inside the execution folder (absolute paths and '..' are rejected). --json-save does the same with an auto-generated name under results/." }, { "command": "deps-checker check dns-switch --db custom-deps.json --json", "description": "Check against an external dependency database layered on top of the built-in one", "expectedOutput": "The usual JSON report, resolved using the extra package definitions from custom-deps.json" }, { "command": "DEPS_DEBUG=1 deps-checker check dns-switch", "description": "Show how each package was resolved when a result looks wrong", "expectedOutput": "The normal report, plus resolution tracing on stderr (which candidate matched, which fallback was used)" } ], "id": "6_ci_automation", "title": "CI AND AUTOMATION" } ], "description": "Dependency checker for Kodachi OS Rust binaries", "name": "deps-checker", "quickReference": [ "deps-checker -h", "deps-checker -e", "deps-checker list-binaries", "deps-checker check dns-switch", "deps-checker check-all --json", "deps-checker list-profiles dns-switch", "sudo deps-checker install-missing --dry-run", "deps-checker check-all --json | deps-checker generate-script" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:27.694469381Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "integrity-check", "path": "/opt/kodachi/dashboard/hooks/integrity-check", "timestamp": "2026-07-21T01:54:28Z", "file_info": { "size": 3851168, "sha256": "d4f0ae3cfaeba5ec902650684891b6dfb134f9956ff7a8b8dc683aabe492400e" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "A system integrity checker for verifying script and configuration files", "features": [ "File integrity verification using SHA-256 hashes", "Cryptographic signature verification", "Version checking against remote repositories", "Configuration file validation", "Offline mode support", "Comprehensive logging and reporting" ], "license": "Proprietary", "name": "integrity-check", "securityFeatures": { "authentication": "Certificate pinning for secure connections", "encryption": "TLS 1.3 for all network communications", "inputValidation": "All inputs validated and sanitized", "rateLimiting": "Maximum 3 retries with configurable timeouts" }, "systemRequirements": { "dependencies": [ "OpenSSL", "curl" ], "os": "Linux (Debian-based)", "privileges": "sudo for 'generate', 'check-signatures' and 'check-all'. The read-only checks run as your normal user, but anything that writes into the install directory (the generated and remote hash manifests) needs write access to it" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:28.159813459Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "integrity-check", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:28.259742539Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Integrity Operations", "commands": [ { "description": "Verify file integrity for scripts, binaries, and configs", "examples": [ "integrity-check check-integrity", "integrity-check check-integrity --json" ], "name": "check-integrity", "options": [ { "description": "Run against a different install root instead of the detected one", "flag": "--base-dir <DIR>" }, { "description": "Offline mode: compare against the cached local manifest, no remote fetch", "flag": "--no-network" }, { "description": "Also fail on local-only files that are absent from the remote manifest", "flag": "--strict" }, { "description": "Network timeout for fetching the remote manifest [default: 30]", "flag": "--timeout <SECS>" }, { "description": "Retry attempts for the remote fetch, 1-20 [default: 3]", "flag": "--retry <COUNT>" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": false, "usage": "integrity-check check-integrity [OPTIONS]" }, { "description": "Generate new hash file for all tracked files", "examples": [ "integrity-check generate", "integrity-check generate --json" ], "name": "generate", "options": [ { "description": "Run against a different install root instead of the detected one", "flag": "--base-dir <DIR>" }, { "description": "Offline mode: hash local files only, do not contact the server", "flag": "--no-network" }, { "description": "Enable strict validation while hashing", "flag": "--strict" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": true, "usage": "integrity-check generate [OPTIONS]" }, { "description": "Verify cryptographic signatures of tracked files", "examples": [ "integrity-check check-signatures", "integrity-check check-signatures --json" ], "name": "check-signatures", "options": [ { "description": "Run against a different install root instead of the detected one", "flag": "--base-dir <DIR>" }, { "description": "Fail on any signature mismatch instead of only reporting it", "flag": "--strict" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": true, "usage": "integrity-check check-signatures [OPTIONS]" } ] }, { "category": "Verification Operations", "commands": [ { "description": "Compare local package versions against remote repositories", "examples": [ "integrity-check check-version", "integrity-check check-version --json" ], "name": "check-version", "options": [ { "description": "Offline mode. Version checking needs the network, so this leaves nothing to compare", "flag": "--no-network" }, { "description": "Network timeout for the remote version lookup [default: 30]", "flag": "--timeout <SECS>" }, { "description": "Retry attempts for the remote lookup, 1-20 [default: 3]", "flag": "--retry <COUNT>" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": false, "usage": "integrity-check check-version [OPTIONS]" }, { "description": "Verify the integrity and format of configuration files", "examples": [ "integrity-check check-config", "integrity-check check-config --json" ], "name": "check-config", "options": [ { "description": "Run against a different install root instead of the detected one", "flag": "--base-dir <DIR>" }, { "description": "Enable strict validation of the configuration files", "flag": "--strict" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": false, "usage": "integrity-check check-config [OPTIONS]" }, { "description": "Perform comprehensive check including integrity, versions, and signatures", "examples": [ "integrity-check check-all", "integrity-check check-all --json" ], "name": "check-all", "options": [ { "description": "Run against a different install root instead of the detected one", "flag": "--base-dir <DIR>" }, { "description": "Offline mode: run the local integrity pass only, skip the remote manifest", "flag": "--no-network" }, { "description": "Also fail on local-only files that are absent from the remote manifest", "flag": "--strict" }, { "description": "Network timeout, raise it for a slow link [default: 30]", "flag": "--timeout <SECS>" }, { "description": "Retry attempts for the remote fetch, 1-20 [default: 3]", "flag": "--retry <COUNT>" }, { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" } ], "requires_sudo": true, "usage": "integrity-check check-all [OPTIONS]" } ] }, { "category": "Utility Operations", "commands": [ { "description": "Display the most recent integrity check logs", "examples": [ "integrity-check view-logs", "integrity-check view-logs --json" ], "name": "view-logs", "options": [ { "description": "Detail level 0-3 [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Machine readable output for scripting or the dashboard", "flag": "--json / --json-pretty / --json-human" }, { "description": "Show at most N log records", "flag": "--limit <N>" } ], "requires_sudo": false, "usage": "integrity-check view-logs [OPTIONS]" } ] } ], "description": "A system integrity checker for verifying script and configuration files", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "HTTP proxy for network requests", "name": "HTTP_PROXY", "values": "http://proxy:port" }, { "default": "unset", "description": "HTTPS proxy for secure requests", "name": "HTTPS_PROXY", "values": "https://proxy:port" } ], "exitCodes": { "0": "Success", "1": "General error", "10": "Check failure - integrity/version issues found", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Timeout error", "7": "Authentication error", "8": "Internal error", "9": "Validation error" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Filter JSON output fields", "flag": "--json-filter <FIELDS>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config <FILE>" }, { "description": "Set timeout (default: 30)", "flag": "--timeout <SECS>" }, { "description": "Retry attempts, 1-20 [default: 3]. This is the flag that actually sets the retry count", "flag": "--retry <COUNT>" }, { "description": "Colorized, jq-style JSON output", "flag": "--json-human" }, { "description": "Select which fields to keep in JSON output", "flag": "--fields <FIELDS>" }, { "description": "Limit the number of records in JSON output", "flag": "--limit <N>" }, { "description": "Skip the first N records in JSON output", "flag": "--offset <N>" }, { "description": "Output format (text|json) [default: text]", "flag": "-o, --output-format <FORMAT>" }, { "description": "Base directory for the application. Rejects '..', shell metacharacters and the system prefixes /etc, /sys, /proc, /dev, /root", "flag": "--base-dir <DIR>" }, { "description": "Working directory for the process", "flag": "-d, --work-dir <DIR>" }, { "description": "Override the network port used for remote lookups", "flag": "--port <PORT>" }, { "description": "Verbosity level (0-3) [default: 1]", "flag": "-V, --verbosity <LEVEL>" }, { "description": "Logging level (error|warn|info|debug|trace)", "flag": "--log-level <LEVEL>" }, { "description": "Offline mode: skip every remote call, verify against the local manifest only", "flag": "--no-network" }, { "description": "Strict validation: local-only files missing from the remote manifest also fail the check", "flag": "--strict" } ], "name": "integrity-check", "usage": "integrity-check [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:28.361728370Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Core integrity checking operations. check-integrity compares every tracked file against the hash manifest and reports what changed.", "examples": [ { "command": "integrity-check check-integrity", "description": "Verify integrity of all tracked files", "expectedOutput": "A per-file pass/fail list, then a summary of hash mismatches and missing files. Exit code 10 if anything failed", "notes": "This refreshes the cached remote manifest inside the install directory, so on a root-owned install (for example /opt) prefix it with sudo or pass --no-network." }, { "command": "integrity-check check-integrity --json", "description": "Integrity check with JSON output", "expectedOutput": "A JSON envelope whose data holds the mismatch, missing-local and missing-remote lists" }, { "command": "integrity-check check-integrity --base-dir /opt/kodachi/dashboard/hooks", "description": "Check a second Kodachi install instead of the detected one", "expectedOutput": "Integrity results for the files under that directory", "notes": "--base-dir is validated: '..', shell metacharacters (* ? { } ( ) ; | & $ ` < >) and the system prefixes /etc, /sys, /proc, /dev and /root are all rejected." }, { "command": "integrity-check check-integrity --base-dir /opt/kodachi/dashboard/hooks --json", "description": "Same check against a custom install root, as JSON", "expectedOutput": "JSON envelope with the results for that directory" } ], "id": "1_basic_usage", "title": "Basic Usage" }, { "description": "check-all runs the file integrity pass and the package version comparison together, and writes the refreshed remote manifest into the install directory, which is why it wants root.", "examples": [ { "command": "sudo integrity-check check-all", "description": "Complete system verification", "expectedOutput": "Integrity results followed by the version comparison, then a combined pass/fail summary", "notes": "Needs root because it rewrites the cached manifest inside a root-owned install directory." }, { "command": "sudo integrity-check check-all --timeout 300", "description": "Full system verification over a slow or Tor-routed link", "expectedOutput": "The same report, with up to 300 seconds allowed per network call", "notes": "--timeout accepts 1 to 300 seconds. The default of 30 is often too short over Tor." }, { "command": "sudo integrity-check check-all --strict --json", "description": "Fail the run if any local file is absent from the remote manifest", "expectedOutput": "JSON envelope, with a failing status if the missing-remote list is not empty", "notes": "Without --strict, local-only files are reported but do not fail the check." } ], "id": "2_comprehensive_checks", "title": "Comprehensive System Checks" }, { "description": "Creating and managing file integrity hashes", "examples": [ { "command": "sudo integrity-check generate", "description": "Create a new hash manifest covering all tracked files", "expectedOutput": "The generated hash manifest is written into the install directory, replacing the previous one", "notes": "Needs root. This OVERWRITES the existing manifest: whatever is on disk right now becomes the new baseline, so only run it when you trust the current state of the system. Running it on a tampered system makes the tampering the reference." }, { "command": "sudo integrity-check generate --json", "description": "Hash generation with JSON output for automation", "expectedOutput": "JSON envelope reporting how many files were hashed and where the manifest was written" } ], "id": "3_hash_generation", "title": "Hash Generation" }, { "description": "Package version verification against remote repositories", "examples": [ { "command": "integrity-check check-version", "description": "Compare local package versions against remote repositories", "expectedOutput": "A per-package comparison of the local version against the remote one, and a list of any mismatches", "notes": "Needs network access. With --no-network there is nothing to compare against." }, { "command": "integrity-check check-version --json", "description": "Version check with JSON output for scripting", "expectedOutput": "JSON envelope with the local and remote version of each tracked package" } ], "id": "4_version_checking", "title": "Version Checking" }, { "description": "Configuration file verification and validation", "examples": [ { "command": "integrity-check check-config", "description": "Verify the integrity and format of configuration files", "expectedOutput": "A pass/fail line per configuration file, with the parse error shown for any file that is malformed" }, { "command": "integrity-check check-config --json", "description": "Configuration check with JSON output", "expectedOutput": "JSON envelope listing each configuration file and whether it validated" } ], "id": "5_configuration_management", "title": "Configuration Management" }, { "description": "Cryptographic signature validation", "examples": [ { "command": "sudo integrity-check check-signatures", "description": "Verify cryptographic signatures of tracked files", "expectedOutput": "A verified/failed line per signed file, checked against the bundled public key", "notes": "Needs root to read the protected signature material in the install directory." }, { "command": "sudo integrity-check check-signatures --json", "description": "Signature verification with JSON output", "expectedOutput": "JSON envelope with the signature status of every signed file" }, { "command": "sudo integrity-check check-signatures --strict", "description": "Strict signature verification", "expectedOutput": "The same report, but the command exits non-zero on the first signature that does not verify", "notes": "Use this in automation: without --strict a mismatch is reported but does not fail the run." } ], "id": "6_signature_verification", "title": "Signature Verification" }, { "description": "Viewing and managing integrity check logs", "examples": [ { "command": "integrity-check view-logs", "description": "Display the most recent integrity check logs", "expectedOutput": "The most recent log entries, newest last" }, { "command": "integrity-check view-logs --json", "description": "View logs in JSON format for parsing", "expectedOutput": "JSON envelope with one object per log record", "notes": "Useful for log analysis tools" } ], "id": "7_log_management", "title": "Log Management" }, { "description": "--no-network is the headline offline mode: it skips every remote call so the check runs entirely against the local manifest, which is what you want on an air-gapped machine or when you do not want the box reaching out at all. --strict tightens what counts as a failure, and --verbosity controls how much detail is printed.", "examples": [ { "command": "integrity-check check-integrity --no-network", "description": "Verify files offline, against the manifest already on disk", "expectedOutput": "The usual pass/fail list, with no remote fetch and no manifest rewrite", "notes": "Nothing leaves the machine. The cached remote manifest is not refreshed, so results are only as current as the last online run." }, { "command": "sudo integrity-check generate --no-network --strict", "description": "Rebuild the hash manifest from local files only", "expectedOutput": "A regenerated hash file covering every tracked file", "notes": "Needs root: it writes the manifest into the install directory. Run it after a deliberate system update, otherwise a later check-integrity will report your own changes as tampering." }, { "command": "integrity-check check-integrity --verbosity 2", "description": "Show more detail about each file as it is checked", "expectedOutput": "Per-file progress lines in addition to the summary", "notes": "Levels are 0 (quiet) to 3 (most detail). Default is 1." }, { "command": "sudo integrity-check check-all --output-format json --timeout 60 --retry 5", "description": "Automation-friendly run with an explicit retry budget", "expectedOutput": "A single JSON envelope, retrying each failed network call up to 5 times", "notes": "--retry accepts 1 to 20. The older --max-retries flag is deprecated and ignored: only --retry changes the retry count." } ], "id": "8_offline_and_hardened", "title": "Offline and Hardened Operation" } ], "description": "Usage examples for integrity-check", "name": "integrity-check", "quickReference": [ "integrity-check check-integrity", "sudo integrity-check check-all", "sudo integrity-check generate", "integrity-check check-version", "integrity-check check-config", "sudo integrity-check check-signatures", "integrity-check view-logs", "integrity-check --help", "integrity-check --version", "integrity-check --info", "integrity-check --examples" ] }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:28.640473534Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "kodachi-soc", "path": "/opt/kodachi/dashboard/hooks/kodachi-soc", "timestamp": "2026-07-21T01:54:29Z", "file_info": { "size": 6868752, "sha256": "103106956433f91ac76f1252ec0a7654979096615f1dc01676322df26b7c3310" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Kodachi SOC host-security monitor: full telemetry collector with MITRE ATT&CK annotations", "features": [ "Default-disabled watcher service activation requiring explicit release authorization and exact signed target qualification", "Always-on metadata-only host exposure watcher on qualified targets", "All visible TCP listeners and established flows, UDP binds and connected endpoints, and Unix-domain listeners across discovered namespaces", "Behavior-first reverse and bind shell, SSH, FTP, VNC, web, netcat-style, SOCKS, relay, reverse-proxy, and local-exposure findings", "PTY evidence only after a proven socket-to-stdio bridge, with higher confidence for deleted or memfd-backed execution", "Fail-visible package-ownership and authentication evidence tied to fixed process and endpoint identity", "Bare outbound flows remain bounded correlation context until higher-signal evidence promotes them", "One authoritative watcher engine; snapshot consumes summaries or uses labeled snapshot_only input", "Explicit approvals with digest, UID, parent or unit, namespace, protocol, address, port, expiry, and revocation", "Fail-visible healthy, degraded, untrusted, and unsupported coverage states", "Bounded finding-time policy and sensor-health observations retained for investigation", "Readiness only after backend selection, capability drop, journal restoration, and initial reconciliation", "Installed 25 MiB and live 4 MiB bounded local retention with no payload capture or telemetry", "Investigation and acknowledgement only; no terminate, block, isolate, routing, or firewall action", "Separately signed unprivileged session notifier for dashboard-independent visual alerts without a second scoring engine" ], "license": "Proprietary", "name": "kodachi-soc", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 15, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.200801265Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "kodachi-soc", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 13, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.389536915Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Cache", "commands": [ { "description": "Run all expensive background scans and populate the cache", "examples": [ "sudo kodachi-soc refresh", "sudo kodachi-soc refresh && sudo kodachi-soc snapshot" ], "name": "refresh", "options": [ { "description": "refresh takes no flags. It runs the expensive scans and writes the cache, then exits", "flag": "(no options)" } ], "requires_sudo": true, "usage": "kodachi-soc refresh" } ] }, { "category": "Host Exposure", "commands": [ { "description": "Run the service-owned always-on host exposure watcher", "examples": [ "sudo kodachi-soc watch" ], "name": "watch", "options": [ { "description": "watch is service-owned and takes no command-specific flags. systemd owns restart, resource limits, runtime and state directories, and target-specific enablement", "flag": "(no options)" }, { "description": "The system service owns backend selection, signed target qualification, storage profile, reconciliation, and resource limits. Production watcher service activation and default enablement are disabled pending release approval; an authorized rollout must explicitly set KODACHI_HOST_EXPOSURE_WATCHER_ENABLED=1 during installation, and invalid flag values fail closed. Enabling the unit does not bypass qualification: a target that lacks an exact signed qualification remains visibly unsupported and continuous capture stays disabled. A qualified target must match an approved kernel, architecture, boot and storage profile, provide BTF and cgroup v2, keep io_uring disabled, and provide CAP_BPF, CAP_PERFMON, CAP_NET_ADMIN, and CAP_SYS_ADMIN. The installer persists kernel.io_uring_disabled=2 before watcher activation; inability to apply it leaves coverage visibly unsupported. The unit enforces MemoryHigh=48M, MemoryMax=64M, CPUQuota=10%, OOMScoreAdjust=500, TasksMax=64, LimitNOFILE=4096, and an 8192-record or 8 MiB userspace queue. Active deduplication state retains at most 384 noncritical and 128 critical finding contexts or 4 MiB, restores that bounded state from the journal after restart, prefers critical contexts under pressure, and reports any eviction as degraded evidence without deleting journal history. systemd readiness is announced only after target qualification, backend attachment or honest unsupported selection, runtime capability drop, bounded journal restoration, and initial reconciliation complete. Healthy means the qualified metadata backend and reconciliation are current with no loss. Degraded means qualified coverage lost events or a recoverable backend input. Untrusted means policy, sensor, journal, permission, or evidence integrity failed. Unsupported means the target never qualified and continuous capture is disabled. All visible TCP listeners and established inbound or outbound TCP flows, UDP binds and connected endpoints, and Unix-domain listeners are normalized across discovered network namespaces. Behavior-first rules cover reverse and bind shells, SSH and SFTP forwarding, FTP and FTPS control plus passive or data relationships, VNC and RFB, arbitrary web servers, renamed or random-port netcat-style listeners, SOCKS, relays, reverse proxies, and local-exposure tunnels without relying on a product name or famous port. A PTY contributes to shell confidence only after a stable socket-to-stdio descriptor bridge is proven. Deleted or memfd-backed execution raises shell confidence and remains in bounded evidence. Package ownership and authentication evidence are tied to fixed process and endpoint identity; missing, duplicated, stale, incompatible, or ambiguous evidence remains unknown or unavailable and degrades health visibly. Bare outbound flows stay bounded in-memory correlation context unless proven shell, relay, forwarding, fan-out, authentication, persistence, service, or risky-executable evidence promotes them. The command writes schema-versioned local health and findings and does not stream raw events or read socket payloads. Unsupported targets fail visibly and do not start reconciliation as a substitute for continuous coverage. The separately signed, unprivileged kodachi-soc-notifier consumes only the bounded local summary and delivers visual warning, critical, degraded, untrusted, and unsupported alerts while the dashboard is closed; it never scores or acknowledges findings. Host-only metadata cannot prove absence of kernel compromise or a tunnel hidden inside an approved process.", "flag": "(coverage contract)" } ], "requires_sudo": true, "usage": "kodachi-soc watch" }, { "description": "Read host exposure findings, qualification, and acknowledgement state", "examples": [ "kodachi-soc exposure summary --json", "sudo kodachi-soc exposure history --limit 32 --json", "sudo kodachi-soc exposure history --limit 32 --before-sequence 18446744073709551615 --before-finding-id FINDING_ID --json", "kodachi-soc exposure qualification --json", "kodachi-soc exposure summary --cursor RECORD_ID --json", "sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json" ], "name": "exposure", "options": [ { "description": "Read the bounded critical-first live window, full aggregate counts, health, and advisory polling cursor", "flag": "summary [--cursor RECORD_ID]" }, { "description": "Read one bounded reverse page of up to 32 retained findings; the optional paired cursor reads older records without skipping findings that share an event sequence", "flag": "history --limit COUNT [--before-sequence SEQUENCE --before-finding-id FINDING_ID]", "required": true }, { "description": "Read the exact signed target match for kernel, architecture, boot, storage, hardening, and BTF evidence without changing state", "flag": "qualification" }, { "description": "Mark one finding acknowledged without changing authorization or deleting evidence", "flag": "acknowledge --finding-id FINDING_ID", "required": true } ], "requires_sudo": false, "usage": "kodachi-soc exposure <summary|history|qualification|acknowledge> [options]" }, { "description": "Review, approve, revoke, list, and explain host exposure policy", "examples": [ "sudo kodachi-soc policy list --json", "sudo kodachi-soc policy approve --finding FINDING_ID --expires-hours 24 --confirm", "sudo kodachi-soc policy revoke --approval APPROVAL_ID --confirm", "sudo kodachi-soc policy renew --approval APPROVAL_ID --expires-hours 24 --confirm", "sudo kodachi-soc policy explain --finding FINDING_ID --json" ], "name": "policy", "options": [ { "description": "List reviewed defaults and explicit approvals without changing policy", "flag": "list" }, { "description": "Authorize only the persisted finding's exact executable and network scope", "flag": "approve --finding FINDING_ID [--expires-hours HOURS] --confirm", "required": true }, { "description": "Revoke one explicit approval without deleting audit history", "flag": "revoke --approval APPROVAL_ID --confirm", "required": true }, { "description": "Revoke the old record and create a renewed record with a new expiry", "flag": "renew --approval APPROVAL_ID --expires-hours HOURS --confirm", "required": true }, { "description": "Show the exact current approval decision and scope mismatches", "flag": "explain --finding FINDING_ID" } ], "requires_sudo": true, "usage": "kodachi-soc policy <list|approve|revoke|renew|explain> [options]" } ] }, { "category": "Telemetry", "commands": [ { "description": "Collect all SOC telemetry and emit DATA JSON", "examples": [ "sudo kodachi-soc snapshot", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc snapshot --json-pretty", "sudo kodachi-soc snapshot --json-human" ], "name": "snapshot", "options": [ { "description": "Default. Emits the DATA JSON pretty-printed. snapshot ALWAYS emits JSON, there is no plain-text mode", "flag": "(no flag)" }, { "description": "Compact single-line DATA JSON, for piping into jq or the dashboard", "flag": "--json" }, { "description": "Indented DATA JSON", "flag": "--json-pretty" }, { "description": "jq-style colorized DATA JSON for reading in a terminal", "flag": "--json-human" }, { "description": "The additive watcher field contains schema_version, generated_at_epoch_ms, health, finding_count, unread_count, critical_unread_count, findings, and cursor when authoritative host-exposure evidence is available. findings is a critical-first live window bounded to at most 512 records; finding_count, unread_count, and critical_unread_count describe the full retained journal rather than only that window. Each finding carries bounded policy_observations and health_observations from evaluation time; unavailable evidence remains explicit and later state changes do not rewrite historical context. The protected exposure history --limit 32 --json command reads the first retained reverse page; older pages require both --before-sequence <exclusive> and --before-finding-id <exclusive> and remain bounded to 32 without changing state. When the watcher is healthy, snapshot consumes its authoritative host-exposure summaries and does not rescore listeners, inbound flows, relays, shells, remote access, proxies, or tunnels. Bare outbound flows remain bounded correlation context unless promoted by higher-signal metadata. If continuous monitoring is unsupported or unavailable, one-shot reconciliation feeds the same engine and reports snapshot_only coverage. Snapshot-only inspection cannot prove capture of short-lived activity, socket payload classification, kernel compromise, or a tunnel hidden inside an approved process.", "flag": "(host exposure)" } ], "requires_sudo": true, "usage": "kodachi-soc snapshot [--json | --json-pretty | --json-human]" } ] } ], "description": "Kodachi SOC host-security monitor: full telemetry collector with MITRE ATT&CK annotations", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" } ], "name": "kodachi-soc", "usage": "kodachi-soc [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 20, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.533156929Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "snapshot is the whole point of this binary: it runs every SOC collector (vitals, network, connections, processes, threats, auth, privacy posture, system health) and prints the DATA JSON the dashboard consumes. It ALWAYS emits JSON. The four forms below differ only in how that JSON is formatted.", "examples": [ { "command": "sudo kodachi-soc snapshot", "description": "Collect the full SOC telemetry set and print it", "expectedOutput": "A pretty-printed DATA JSON object with host, generated, overall, counts, load, score, findings, posture and clusters", "notes": "Needs root: the collectors read /proc, auth logs, SUID bits and file hashes that an unprivileged user cannot see. Without sudo the scan runs but the threat sections come back empty or incomplete. On a cold cache the first call returns placeholder values and kicks off a background refresh, so run 'refresh' first if you need complete data on the first shot." }, { "command": "sudo kodachi-soc snapshot --json", "description": "Same data as one compact line, for a script or the dashboard", "expectedOutput": "The same DATA JSON on a single line, no indentation" }, { "command": "sudo kodachi-soc snapshot --json-pretty", "description": "Explicitly indented JSON", "expectedOutput": "The DATA JSON indented. Same content as the default form" }, { "command": "sudo kodachi-soc snapshot --json-human", "description": "Colorized, jq-style JSON for reading in a terminal", "expectedOutput": "Syntax-highlighted DATA JSON" } ], "id": "0_telemetry_snapshot", "title": "Telemetry Snapshot" }, { "description": "The expensive scans (file integrity hashing, SUID drift, persistence sweeps) run in the background and land in a cache. snapshot spawns a refresh automatically when it finds the cache cold, but that snapshot itself returns placeholders. Warm the cache first when you want the first read to be complete.", "examples": [ { "command": "sudo kodachi-soc refresh", "description": "Run the expensive scans now and populate the cache", "expectedOutput": "Runs to completion, then exits. The cache under the SOC state directory is rewritten", "notes": "Needs root. This is the slow path: it is exactly the work snapshot avoids doing inline. A refresh spawned in the last 30 seconds is deduplicated by a lock file, so back to back calls will not stack up." }, { "command": "sudo kodachi-soc refresh && sudo kodachi-soc snapshot", "description": "Pre-warm the cache, then take a fully populated snapshot", "expectedOutput": "The scans run first, then a DATA JSON with real threat findings rather than cold-cache placeholders", "notes": "This is the sequence to use before the first dashboard open, or in a boot script." } ], "id": "1_cache_warming", "title": "Cache Warming" }, { "description": "snapshot --json is designed to be piped. The dashboard calls exactly this and reads the same fields you can read from the shell.", "examples": [ { "command": "sudo kodachi-soc snapshot --json | jq '.overall'", "description": "Pull just the overall security verdict out of the snapshot", "expectedOutput": "The overall posture value from the DATA JSON", "notes": "Requires jq. Use --json (not the default form) when piping, so the payload is a single line." }, { "command": "sudo kodachi-soc snapshot --json | jq '.findings'", "description": "List every threat finding the collectors raised", "expectedOutput": "The findings array, each entry carrying its MITRE ATT&CK annotation" }, { "command": "sudo kodachi-soc snapshot --json > soc-baseline.json", "description": "Save a snapshot to disk so a later run can be diffed against it", "expectedOutput": "A file holding the full DATA JSON for this moment in time" } ], "id": "2_automation", "title": "Automation and Dashboard Integration" }, { "description": "Approvals are explicit local authorization, never a first-run baseline. They bind the finding's executable digest, effective UID, parent or unit, namespace class, protocol, address scope, and port scope. Acknowledging a finding does not approve it. Changed, expired, revoked, corrupt, or incomplete identities fail closed.", "examples": [ { "command": "sudo kodachi-soc policy list --json", "description": "List reviewed defaults, explicit approvals, expiry, and revocation state", "expectedOutput": "A JSON policy summary with no automatically trusted observations", "notes": "Unknown or incomplete identity is never rendered as approved." }, { "command": "sudo kodachi-soc policy approve --finding FINDING_ID --expires-hours 24 --confirm", "description": "Create a narrow approval from one persisted finding", "expectedOutput": "A JSON approval bound to the finding's exact process and network scope", "notes": "This is authorization. The separate acknowledge action is not authorization." }, { "command": "sudo kodachi-soc policy revoke --approval APPROVAL_ID --confirm", "description": "Revoke an approval without deleting its audit history", "expectedOutput": "A JSON revocation record and updated policy version" }, { "command": "sudo kodachi-soc policy renew --approval APPROVAL_ID --expires-hours 24 --confirm", "description": "Renew an active approval while retaining the old audit record", "expectedOutput": "A new approval ID and expiry; the previous record is revoked", "notes": "A revoked approval cannot be renewed." }, { "command": "sudo kodachi-soc policy explain --finding FINDING_ID --json", "description": "Explain the policy decision and every scope mismatch for a finding", "expectedOutput": "A JSON PolicyDecision with approval, mismatch, expiry, or revocation reason" } ], "id": "3_host_exposure_policy", "title": "Host Exposure Policy" }, { "description": "summary is a read-only local consumer of the schema-valid critical-first live window, bounded to at most 512 findings, plus full finding_count, unread_count, and critical_unread_count aggregates. Each finding retains bounded policy_observations and health_observations captured when it was evaluated, so later policy or sensor changes do not erase the investigation explanation. Root-authorized exposure history --limit 32 --json reads the first retained page. Older pages require the symmetric --before-sequence <exclusive> and --before-finding-id <exclusive> cursor pair and return at most 32 findings without changing state. acknowledge marks one finding as reviewed but does not approve future behavior, delete evidence, terminate a process, block an endpoint, isolate networking, or alter firewall rules. Missing, stale, corrupt, or unreadable watcher evidence fails visibly.", "examples": [ { "command": "kodachi-soc exposure summary --json", "description": "Read current watcher health, bounded findings, full counts, and cursor", "expectedOutput": "A schema-versioned WatcherSummary with at most 512 critical-first findings", "notes": "Unavailable, corrupt, stale, untrusted, or unsupported evidence never renders as clean." }, { "command": "kodachi-soc exposure qualification --json", "description": "Read the signed exact-target qualification decision", "expectedOutput": "A qualified or unsupported decision with exact local evidence", "notes": "Generic BTF or capability availability alone never qualifies continuous coverage." }, { "command": "sudo kodachi-soc exposure history --limit 32 --json", "description": "Read the first bounded reverse page of retained findings", "expectedOutput": "A FindingHistoryPage with up to 32 findings and a symmetric next cursor", "notes": "History is read-only. It cannot acknowledge, approve, delete, or contain a finding." }, { "command": "sudo kodachi-soc exposure history --before-sequence 4242 --before-finding-id finding-0000000000000000000000000000000000000000000000000000000000000000 --limit 32 --json", "description": "Read the next page using both exclusive cursor components", "expectedOutput": "A FindingHistoryPage with up to 32 older findings and a symmetric next cursor", "notes": "History is read-only. It cannot acknowledge, approve, delete, or contain a finding." }, { "command": "sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json", "description": "Mark one finding reviewed while retaining its evidence", "expectedOutput": "The updated WatcherSummary with the finding acknowledged", "notes": "Acknowledgement is not authorization and never creates a policy approval." } ], "id": "4_host_exposure_investigation", "title": "Host Exposure Investigation" } ], "description": "Usage examples for kodachi-soc", "name": "kodachi-soc", "quickReference": [ "sudo kodachi-soc snapshot", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc refresh", "kodachi-soc --help", "kodachi-soc --version", "kodachi-soc --info --json", "kodachi-soc --examples", "sudo kodachi-soc watch", "sudo kodachi-soc snapshot --json", "sudo kodachi-soc policy list --json", "sudo kodachi-soc policy explain --finding FINDING_ID --json", "kodachi-soc exposure summary --json", "sudo kodachi-soc exposure history --limit 32 --json", "kodachi-soc exposure qualification --json", "sudo kodachi-soc exposure acknowledge --finding-id FINDING_ID --json", "kodachi-soc watch --help", "kodachi-soc policy --help" ] }, "errors": [], "metadata": { "executionTime": 14, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:29.815382278Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-scheduler", "path": "/opt/kodachi/dashboard/hooks/ai-scheduler", "timestamp": "2026-07-21T01:54:30Z", "file_info": { "size": 5784784, "sha256": "000394a8c271863dd308c1d70dc25e1aa45602b6e08a23c31edd61aae5e7bc0d" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:30.419300409Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-scheduler", "version": "9.8.4", "author": "Warith Al Maawali", "description": "Kodachi Scheduler Daemon - Cron-based command scheduling with security whitelist", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Cron expression parsing, 6 fields: second minute hour day month weekday (\"0 0 * * * *\" = hourly)", "Event-driven triggers", "Command whitelist validation", "Execution history tracking" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:30.609774958Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-scheduler", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:30.784231581Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-scheduler", "description": "Kodachi Scheduler Daemon - Cron-based command scheduling with security whitelist", "usage": "ai-scheduler [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Daemon Control", "commands": [ { "name": "start", "description": "Start the scheduler daemon", "usage": "ai-scheduler start [OPTIONS]", "options": [ { "flag": "-f, --foreground", "description": "Run the scheduler loop in this terminal instead of detaching (blocks until Ctrl+C)", "default": "false (daemonize)" }, { "flag": "--json", "description": "Emit status, mode, schedules_loaded, executions, pid and already_running as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-scheduler start", "sudo ai-scheduler start --foreground", "sudo ai-scheduler start --json" ] } ] }, { "category": "Schedule Management", "commands": [ { "name": "add", "description": "Add a new scheduled task", "usage": "ai-scheduler add [OPTIONS]", "options": [ { "flag": "--name <NAME>", "description": "Unique name for the schedule", "required": true }, { "flag": "--command <COMMAND>", "description": "Command to execute. The binary must be whitelisted, a subcommand is required, and the subcommand plus arguments must pass the shared gateway policy validator", "required": true }, { "flag": "--cron <EXPRESSION>", "description": "Six mandatory fields: second minute hour day-of-month month day-of-week (optional 7th field is the year). Weekday ordinals are 1=Sunday through 7=Saturday. A five-field crontab string does not parse", "required": true }, { "flag": "--json", "description": "Emit schedule_id, name, command, cron_expression and schedule_description as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-scheduler add --name \"hourly-tor\" --command \"tor-switch tor-status\" --cron \"0 0 * * * *\"", "ai-scheduler add --name \"dns-check\" --command \"dns-leak test\" --cron \"0 */30 * * * *\"", "ai-scheduler add --name \"daily-check\" --command \"health-control net-check\" --cron \"0 0 8 * * *\" --json", "ai-scheduler add --name \"weekly-memory-clean\" --command \"health-control memory-clean\" --cron \"0 0 2 * * 1\"" ] }, { "name": "list", "description": "List all scheduled tasks", "usage": "ai-scheduler list [OPTIONS]", "options": [ { "flag": "--json", "description": "Emit count and the schedules array as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-scheduler list", "ai-scheduler list --json" ] }, { "name": "remove", "description": "Remove a scheduled task", "usage": "ai-scheduler remove [OPTIONS]", "options": [ { "flag": "<ID>", "description": "Numeric schedule ID to delete, as shown by `ai-scheduler list`. Irreversible", "required": true }, { "flag": "--json", "description": "Emit status, schedule_id and deleted as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-scheduler remove 1", "ai-scheduler remove 2 --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format <FORMAT>", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter <FIELD1,FIELD2>", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields <FIELD_LIST>", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit <NUMBER>", "description": "Limit number of results returned" }, { "flag": "--offset <NUMBER>", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir <PATH>", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port <PORT>", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level <LEVEL>", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config <FILE>", "description": "Use custom configuration file" }, { "flag": "--timeout <SECS>", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "3": "Permission denied", "2": "Invalid arguments", "1": "General error", "4": "Network error", "5": "File not found", "0": "Success" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:31.100099553Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-scheduler", "description": "Usage examples for ai-scheduler", "categories": [ { "id": "0_cron_syntax", "title": "Cron Syntax (read this first)", "description": "Every --cron expression takes SIX mandatory fields: second minute hour day-of-month month day-of-week (an optional seventh field is the year). A five-field crontab-style string does not parse. Weekday ordinals run 1 to 7 where 1 is Sunday and 7 is Saturday, and the names Sun through Sat are also accepted. `add` validates the expression before it writes anything, so a bad expression is rejected up front.", "examples": [ { "command": "ai-scheduler add --name \"hourly-tor\" --command \"tor-switch tor-status\" --cron \"0 0 * * * *\"", "description": "Every hour, on the hour", "expectedOutput": "Schedule added successfully, with its ID, name, command, cron string and the next run times", "notes": "Requires a prior `online-auth` login. \"0 0 * * * *\" is second 0, minute 0, every hour." }, { "command": "ai-scheduler add --name \"dns-check\" --command \"dns-leak test\" --cron \"0 */30 * * * *\"", "description": "Every 30 minutes", "expectedOutput": "Schedule added successfully with the next run time roughly 30 minutes out", "notes": "Requires a prior `online-auth` login." }, { "command": "ai-scheduler add --name \"daily-check\" --command \"health-control net-check\" --cron \"0 0 8 * * *\"", "description": "Once a day at 08:00", "expectedOutput": "Schedule added successfully with tomorrow 08:00 as the next run", "notes": "Requires a prior `online-auth` login. Times are evaluated in UTC." }, { "command": "ai-scheduler add --name \"weekly-memory-clean\" --command \"health-control memory-clean\" --cron \"0 0 2 * * 1\"", "description": "Once a week, Sunday at 02:00", "expectedOutput": "Schedule added successfully with the coming Sunday 02:00 as the next run", "notes": "Requires a prior `online-auth` login. Weekday 1 IS Sunday in this cron dialect (1 to 7, Sunday through Saturday). Ordinal 0 is out of range and is rejected." } ] }, { "id": "1_daemon_control", "title": "Daemon Control", "description": "Run the scheduler loop that actually fires the tasks. Nothing you add with `add` runs until the daemon is running.", "examples": [ { "command": "sudo ai-scheduler start", "description": "Start the scheduler in the background", "expectedOutput": "Scheduler daemon started successfully, with mode Background, schedules loaded, executions and the PID", "notes": "Requires a prior `online-auth` login (start is not on the read-only exempt list). Needs root: the PID file is written under the install directory." }, { "command": "sudo ai-scheduler start --foreground", "description": "Run the scheduler loop in this terminal so you can watch tasks fire", "expectedOutput": "The scheduler stays attached and prints each execution as it happens", "notes": "Requires a prior `online-auth` login. Blocks until Ctrl+C. -f is the short form." }, { "command": "sudo ai-scheduler start --json", "description": "Start in the background and capture the result as JSON", "expectedOutput": "Envelope with status, mode, schedules_loaded, executions, pid and already_running", "notes": "Requires a prior `online-auth` login." } ] }, { "id": "2_schedule_management", "title": "Schedule Management", "description": "Add, list and remove scheduled tasks. --name, --command and --cron are all required on `add`.", "examples": [ { "command": "ai-scheduler add --name \"dns-check\" --command \"dns-leak test\" --cron \"0 */30 * * * *\" --json", "description": "Schedule a DNS leak test every 30 minutes and get the task ID back as JSON", "expectedOutput": "Envelope with schedule_id, name, command, cron_expression and schedule_description", "notes": "Requires a prior `online-auth` login." }, { "command": "ai-scheduler list", "description": "See every scheduled task and when it next runs", "expectedOutput": "One block per task: [ID] name, command, cron, next run, last run and execution count. 'No scheduled tasks found.' when the table is empty" }, { "command": "ai-scheduler list --json", "description": "Machine-readable task list for the dashboard", "expectedOutput": "Envelope with count and the schedules array" }, { "command": "ai-scheduler remove 1", "description": "Delete the task with ID 1", "expectedOutput": "'Schedule 1 removed successfully', or 'Schedule 1 not found' if the ID does not exist", "notes": "Requires a prior `online-auth` login. Irreversible: the schedule row is deleted. Get the ID from `ai-scheduler list`." }, { "command": "ai-scheduler remove 2 --json", "description": "Delete a task and confirm the result in JSON", "expectedOutput": "Envelope with status, schedule_id and deleted (true or false)", "notes": "Requires a prior `online-auth` login. Irreversible." } ] }, { "id": "3_command_whitelist", "title": "Command Whitelist", "description": "A scheduled command must name an allowlisted Kodachi service, include a subcommand, pass argument sanitization, and be allowed by the shared ai-gateway policy before the schedule is written.", "examples": [ { "command": "ai-scheduler add --name \"tor-health\" --command \"tor-switch tor-status\" --cron \"0 */15 * * * *\" --json", "description": "An allowlisted service and policy-approved subcommand are accepted", "expectedOutput": "Envelope with the new schedule_id", "notes": "Requires a prior `online-auth` login. Unknown or policy-blocked subcommands are rejected before the schedule is saved." }, { "command": "ai-scheduler add --name \"blocked-test\" --command \"malicious-binary run\" --cron \"0 0 * * * *\" --json", "description": "A binary that is not on the whitelist is refused before anything is written", "expectedOutput": "An error envelope saying the command is not whitelisted, and no schedule is created", "notes": "Requires a prior `online-auth` login." } ] } ], "quickReference": [ "ai-scheduler --help", "ai-scheduler --version", "ai-scheduler --info --json", "ai-scheduler --examples", "ai-scheduler list", "ai-scheduler add --name <NAME> --command <COMMAND> --cron <EXPRESSION>", "ai-scheduler remove <ID>", "sudo ai-scheduler start" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "ip-fetch", "path": "/opt/kodachi/dashboard/hooks/ip-fetch", "timestamp": "2026-07-21T01:54:31Z", "file_info": { "size": 4728256, "sha256": "f2df2cc401eb56633be9be81ec0f71a9440378e335fcfe722a0a99a79816a7b3" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "IP Geolocation data fetcher for Kodachi OS - Fetches and displays IP address information including geolocation, ISP, and network details", "features": [ "Multi-source IP geolocation with fallback support", "IPv4 and IPv6 dual-stack support", "Bulk IP lookup with optimized performance", "Offline mode with cached data", "VPN and proxy detection", "ISP and organization information", "Secure API communication with certificate pinning", "Rate limiting and retry logic", "Comprehensive error handling" ], "license": "Proprietary", "name": "ip-fetch", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:31.577658500Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "ip-fetch", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 3, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:31.689677471Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Basic Operations", "commands": [ { "description": "Simple plain text IP address retrieval", "examples": [ "ip-fetch plain-ip --ipv4", "ip-fetch plain-ip --ipv6", "ip-fetch plain-ip --ipv4 --server-index 5" ], "name": "plain-ip", "options": [ { "description": "Return the IPv4 address (default)", "flag": "-4, --ipv4" }, { "description": "Return the IPv6 address", "flag": "-6, --ipv6" }, { "description": "Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead", "flag": "--both" }, { "description": "Use one specific plain-text server by its index instead of the default", "flag": "--server-index <INDEX>" } ], "requires_sudo": false, "usage": "ip-fetch plain-ip [OPTIONS]" } ] }, { "category": "Cache Management", "commands": [ { "description": "Manage IP cache for improved performance", "examples": [ "ip-fetch cache status", "ip-fetch cache list", "ip-fetch cache clear 208.67.222.222", "ip-fetch cache clear", "ip-fetch cache set-ttl 24h" ], "name": "cache", "options": [ { "description": "Show cache statistics and status (subcommand)", "flag": "status" }, { "description": "List every cached IP address (subcommand)", "flag": "list" }, { "description": "Clear the whole cache, or only the given IP (subcommand)", "flag": "clear [IP]" }, { "description": "Set the default cache TTL, e.g. 24h, 7d, 1w (subcommand)", "flag": "set-ttl <TTL>" } ], "requires_sudo": false, "usage": "ip-fetch cache [OPTIONS]" } ] }, { "category": "Comprehensive Testing", "commands": [ { "description": "Complete test suites for all functionality", "examples": [ "ip-fetch test-all", "ip-fetch test-all --verbose", "ip-fetch test-all --include-tor", "ip-fetch test-all --include-tor --socks-port 10000 --json" ], "name": "test-all", "options": [ { "description": "Also run the Tor SOCKS proxy tests", "flag": "--include-tor" }, { "description": "Force the Tor SOCKS port used by --include-tor instead of auto-probing", "flag": "--socks-port <PORT>" }, { "description": "Show per-source detail instead of the summary (cli-core global flag)", "flag": "--verbose" } ], "requires_sudo": false, "usage": "ip-fetch test-all [OPTIONS]" } ] }, { "category": "DNS Operations", "commands": [ { "description": "DNS-based IP resolution and testing", "examples": [ "ip-fetch dns --ipv4", "ip-fetch dns --ipv4 --query-index 0", "ip-fetch dns --ipv6 --query-index all --json" ], "name": "dns", "options": [ { "description": "Resolve over IPv4 DNS queries (default)", "flag": "-4, --ipv4" }, { "description": "Resolve over IPv6 DNS queries", "flag": "-6, --ipv6" }, { "description": "Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead", "flag": "--both" }, { "description": "Run one specific DNS query by index, or 'all' for every query", "flag": "--query-index <INDEX>" } ], "requires_sudo": false, "usage": "ip-fetch dns [OPTIONS]" } ] }, { "category": "Geolocation Services", "commands": [ { "description": "Geolocation API testing with various IPs", "examples": [ "ip-fetch geo", "ip-fetch geo --ip 208.67.222.222", "ip-fetch geo --ip 1.1.1.1 --json" ], "name": "geo", "options": [ { "description": "IP address to geolocate. Omit to use your current IP", "flag": "--ip <IP>" } ], "requires_sudo": false, "usage": "ip-fetch geo [OPTIONS]" } ] }, { "category": "IP Operations", "commands": [ { "description": "Fetch IP geolocation information (default command)", "examples": [ "ip-fetch", "ip-fetch fetch", "ip-fetch 208.67.222.222 --json", "ip-fetch --both", "ip-fetch --no-cache", "ip-fetch --cache-only 208.67.222.222", "ip-fetch --nohistory", "ip-fetch --bulk 1.1.1.1 9.9.9.9 208.67.222.222" ], "name": "fetch", "options": [ { "description": "IP addresses to look up. Omit to look up your own public IP", "flag": "<IP>..." }, { "description": "Request IPv4 only (default behavior)", "flag": "-4, --ipv4" }, { "description": "Request IPv6 only", "flag": "-6, --ipv6" }, { "description": "Request both IPv4 and IPv6 in one call", "flag": "--both" }, { "description": "Force bulk mode. Requires online-auth authentication", "flag": "--bulk" }, { "description": "Disable bulk mode, look each IP up individually", "flag": "--nobulk" }, { "description": "Use a custom server URL for the lookup", "flag": "--server <URL>" }, { "description": "Do not save this lookup to the IP history", "flag": "--nohistory" }, { "description": "Bypass the cache and fetch fresh data", "flag": "--no-cache" }, { "description": "Serve from cache only, fail if the IP is not cached", "flag": "--cache-only" }, { "description": "Refresh the cache even if it is still valid", "flag": "--refresh-cache" } ], "requires_sudo": false, "usage": "ip-fetch fetch [OPTIONS]" } ] }, { "category": "Network Testing", "commands": [ { "description": "Test IP lookup through Tor SOCKS proxy", "examples": [ "ip-fetch tor", "ip-fetch tor --ipv4", "ip-fetch tor --ipv4 all --torsafe", "ip-fetch tor --ipv4 --socks-port 9150", "ip-fetch tor --ipv6 all --json" ], "name": "tor", "options": [ { "description": "Pass 'all' to query every source (positional). Default is one random source", "flag": "<SCOPE>" }, { "description": "Request IPv4 only (default)", "flag": "-4, --ipv4" }, { "description": "Request IPv6 only", "flag": "-6, --ipv6" }, { "description": "Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead", "flag": "--both" }, { "description": "Force a SOCKS port. Without it, 9050, 9150 and the Kodachi pool 10000-10019 are auto-probed", "flag": "--socks-port <PORT>" }, { "description": "Use only the 14 Tor-safe IPv4 URLs instead of all 19", "flag": "--torsafe" } ], "requires_sudo": false, "usage": "ip-fetch tor [OPTIONS]" }, { "description": "Check if connection is using Tor network", "examples": [ "ip-fetch check-tor", "ip-fetch check-tor --status-only", "ip-fetch check-tor --ip-only", "ip-fetch check-tor --json" ], "name": "check-tor", "options": [ { "description": "Print only the IP address (mutually exclusive with --status-only)", "flag": "--ip-only" }, { "description": "Print only the Tor status, true or false (mutually exclusive with --ip-only)", "flag": "--status-only" } ], "requires_sudo": false, "usage": "ip-fetch check-tor [OPTIONS]" } ] }, { "category": "Testing Operations", "commands": [ { "description": "Test fallback mechanisms and multiple source verification", "examples": [ "ip-fetch test-fallback --ipv4 json", "ip-fetch test-fallback --ipv4 plain", "ip-fetch test-fallback --ipv6 json --json" ], "name": "test-fallback", "options": [ { "default": "plain", "description": "Source format to exercise: 'json' or 'plain' (positional)", "flag": "<FORMAT>" }, { "description": "Test IPv4 sources (default)", "flag": "-4, --ipv4" }, { "description": "Test IPv6 sources", "flag": "-6, --ipv6" }, { "description": "Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead", "flag": "--both" } ], "requires_sudo": false, "usage": "ip-fetch test-fallback [OPTIONS]" }, { "description": "Verify multiple sources", "examples": [ "ip-fetch verify-multi --ipv4", "ip-fetch verify-multi --ipv4 --verbose", "ip-fetch verify-multi --ipv6 --json" ], "name": "verify-multi", "options": [ { "description": "Verify across all IPv4 sources (default)", "flag": "-4, --ipv4" }, { "description": "Verify across all IPv6 sources", "flag": "-6, --ipv6" }, { "description": "Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead", "flag": "--both" }, { "description": "Show each source's raw response (cli-core global flag)", "flag": "--verbose" } ], "requires_sudo": false, "usage": "ip-fetch verify-multi [OPTIONS]" }, { "description": "Test random server selection functionality", "examples": [ "ip-fetch random --type plain --ipv4", "ip-fetch random --type json --ipv4 --json", "ip-fetch random --type dns --ipv6 --json" ], "name": "random", "options": [ { "default": "plain", "description": "Source type: plain, json or dns", "flag": "--type <TYPE>" }, { "description": "Pick a random IPv4 source (default)", "flag": "-4, --ipv4" }, { "description": "Pick a random IPv6 source", "flag": "-6, --ipv6" } ], "requires_sudo": false, "usage": "ip-fetch random [OPTIONS]" } ] } ], "description": "IP Geolocation data fetcher for Kodachi OS - Fetches and displays IP address information including geolocation, ISP, and network details", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir <PATH>" }, { "description": "Set custom port number (1024-65535)", "flag": "--port <PORT>" }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level <LEVEL>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config <FILE>" }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout <SECS>" } ], "name": "ip-fetch", "usage": "ip-fetch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 3, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:31.812146400Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Common usage patterns for ip-fetch", "examples": [ { "command": "ip-fetch", "description": "Get your current public IP", "expectedOutput": "Current IP with geolocation data" }, { "command": "ip-fetch fetch", "description": "Run the default fetch command explicitly", "expectedOutput": "Current IP with geolocation data", "notes": "Equivalent to the bare ip-fetch command" }, { "command": "ip-fetch --examples", "description": "Show usage examples", "expectedOutput": "Display all usage patterns" } ], "id": "0_quick_start", "title": "Usage Examples" }, { "description": "Common IP lookup operations", "examples": [ { "command": "ip-fetch", "description": "Get your current public IP from Kodachi Cloud (primary) with automatic fallback", "expectedOutput": "Current IP with geolocation data" }, { "command": "ip-fetch 208.67.222.222", "description": "Look up specific IP address", "expectedOutput": "Geolocation data for 208.67.222.222" }, { "command": "ip-fetch 208.67.222.222 1.1.1.1", "description": "Look up multiple IP addresses", "expectedOutput": "Bulk lookup results", "notes": "Automatically uses bulk mode for better performance" }, { "command": "ip-fetch --refresh-cache", "description": "Force refresh cache and get latest IP data", "expectedOutput": "Fresh IP data bypassing cache" } ], "id": "1_basic_usage", "title": "Basic Usage" }, { "description": "Different ways to format output", "examples": [ { "command": "ip-fetch --json", "description": "Get your current IP in JSON format from primary source with fallback", "expectedOutput": "JSON object with complete IP information" }, { "command": "ip-fetch --json-pretty", "description": "Formatted JSON with indentation", "expectedOutput": "Pretty-printed JSON output" }, { "command": "ip-fetch --json-human", "description": "Enhanced human-readable JSON output with colors (like jq)", "expectedOutput": "Colorized JSON output for better readability" } ], "id": "2_output_formats", "title": "Output Formats" }, { "description": "Own IP lookup and single IP lookup operations", "examples": [ { "command": "ip-fetch --ipv4", "description": "Explicitly request IPv4 from primary source with fallback", "expectedOutput": "Shows your IPv4 address with geolocation data" }, { "command": "ip-fetch --ipv6", "description": "Get your current public IPv6 from Kodachi Cloud (primary) with automatic fallback", "expectedOutput": "Shows your IPv6 address with geolocation data" }, { "command": "ip-fetch --ipv6 --json", "description": "Get your IPv6 in JSON format from primary source with fallback", "expectedOutput": "JSON object with IPv6 geolocation data" }, { "command": "ip-fetch --both", "description": "Get both IPv4 and IPv6 information from primary sources with fallback", "expectedOutput": "Shows both IPv4 and IPv6 with full details" }, { "command": "ip-fetch --both --json", "description": "Get both IPs in JSON format from primary sources with fallback", "expectedOutput": "JSON object with both IPv4 and IPv6 data" } ], "id": "3_basic_ip_lookups", "title": "Basic IP Lookups" }, { "description": "Exercise the fallback chain (test-fallback walks sources until one answers) and cross-check every source against the others (verify-multi). Both work on one IP family at a time.", "examples": [ { "command": "ip-fetch test-fallback --ipv4 json", "description": "Test IPv4 JSON sources with automatic fallback", "expectedOutput": "IPv4 JSON fallback test results" }, { "command": "ip-fetch test-fallback --ipv6 json --json", "description": "Test IPv6 JSON sources with automatic fallback", "expectedOutput": "IPv6 JSON fallback test results in JSON format" }, { "command": "ip-fetch test-fallback --ipv4 plain", "description": "Test IPv4 plain text sources with automatic fallback", "expectedOutput": "IPv4 plain text fallback results" }, { "command": "ip-fetch test-fallback --ipv6 plain", "description": "Test IPv6 plain text sources with automatic fallback", "expectedOutput": "IPv6 plain text fallback results" }, { "command": "ip-fetch verify-multi --ipv4", "description": "Test ALL IPv4 sources to verify consistency", "expectedOutput": "IPv4 multi-source verification report", "notes": "verify-multi is authentication gated. On an unauthenticated shell it fails with 'Authentication required'. Run 'online-auth authenticate' first." }, { "command": "ip-fetch verify-multi --ipv4 --verbose", "description": "Verify all IPv4 sources and print each source's raw response", "expectedOutput": "Per-source responses followed by the consistency verdict" }, { "command": "ip-fetch verify-multi --ipv6 --json", "description": "Test ALL IPv6 sources with JSON output", "expectedOutput": "JSON IPv6 multi-source verification" } ], "id": "4_fallback_and_multi_source_testing", "title": "Fallback and Multi-Source Testing" }, { "description": "Check if your connection is using Tor", "examples": [ { "command": "ip-fetch check-tor", "description": "Check if connection is using Tor and show IP", "expectedOutput": "Tor status and current IP address" }, { "command": "ip-fetch check-tor --ip-only", "description": "Get just the IP address", "expectedOutput": "Your current IP address" }, { "command": "ip-fetch check-tor --status-only", "description": "Get just the Tor status", "expectedOutput": "true or false" }, { "command": "ip-fetch check-tor --json", "description": "Get Tor status and IP in JSON format", "expectedOutput": "JSON object with IsTor and IP fields" }, { "command": "ip-fetch check-tor --json-pretty", "description": "Pretty-printed JSON output", "expectedOutput": "Formatted JSON with Tor status" }, { "command": "ip-fetch check-tor --json-human", "description": "Colorized JSON output (like jq)", "expectedOutput": "Colored JSON with Tor status" } ], "id": "5_tor_detection", "title": "Tor Detection" }, { "description": "Route the IP lookup through a Tor SOCKS5 proxy. Tor must already be running: without a reachable SOCKS port every source fails. Pass 'all' to query every source instead of one random source. This subcommand handles IPv4 or IPv6, not both at once.", "examples": [ { "command": "ip-fetch tor --ipv4", "description": "Get IPv4 through Tor SOCKS5 proxy from ONE random source", "expectedOutput": "IP address via Tor proxy" }, { "command": "ip-fetch tor --ipv4 all", "description": "Test ALL IPv4 sources through Tor SOCKS5 proxy", "expectedOutput": "Comprehensive Tor IPv4 test results" }, { "command": "ip-fetch tor --ipv6 all --json", "description": "Test ALL IPv6 sources through Tor SOCKS5 proxy with JSON output", "expectedOutput": "JSON array with all Tor IPv6 results" }, { "command": "ip-fetch tor --ipv4 --json", "description": "Get IPv4 JSON response through Tor SOCKS5 proxy", "expectedOutput": "JSON IPv4 data via Tor" }, { "command": "ip-fetch tor", "description": "Default IPv4 source via Tor (auto-detects local SOCKS5: 9050, 9150, or Kodachi pool 10000-10019)", "expectedOutput": "IPv4 IP via Tor; output shows which SOCKS port was picked", "notes": "Pass --socks-port to disable auto-detect." }, { "command": "ip-fetch tor --ipv4 --socks-port 9150", "description": "Force the Tor Browser bundle SOCKS port (9150), one random IPv4 source", "expectedOutput": "IPv4 via Tor Browser bundle" }, { "command": "ip-fetch tor --ipv4 all --socks-port 10000", "description": "Force a Kodachi multi-instance pool port (10000) and query ALL IPv4 sources", "expectedOutput": "All IPv4 sources via Kodachi instance #0" }, { "command": "ip-fetch tor --ipv4 all --torsafe", "description": "Query only the Tor-safe IPv4 sources", "expectedOutput": "Results from the 14 verified Tor-safe URLs instead of all 19", "notes": "Use this when some sources block or rate-limit Tor exit nodes and produce false failures." } ], "id": "6_tor_network_testing", "title": "Tor Network Testing" }, { "description": "DNS-based IP resolution and testing", "examples": [ { "command": "ip-fetch dns --ipv4", "description": "Test DNS-based IPv4 resolution using ONE random DNS query", "expectedOutput": "IPv4 address from DNS query" }, { "command": "ip-fetch dns --ipv6", "description": "Test DNS-based IPv6 resolution using ONE random DNS query", "expectedOutput": "IPv6 address from DNS query" }, { "command": "ip-fetch dns --ipv4 --query-index 0", "description": "Test specific DNS query by index", "expectedOutput": "IPv4 from specific DNS query" }, { "command": "ip-fetch dns --ipv6 --query-index all --json", "description": "Test ALL available IPv6 DNS queries with JSON output", "expectedOutput": "JSON array with all IPv6 DNS results" } ], "id": "7_dns_resolution_testing", "title": "DNS Resolution Testing" }, { "description": "Complete test suites for all functionality", "examples": [ { "command": "ip-fetch test-all", "description": "Complete test suite results", "expectedOutput": "Full functionality test report" }, { "command": "ip-fetch test-all --include-tor", "description": "Complete test suite including Tor tests", "expectedOutput": "Comprehensive test results with Tor" }, { "command": "ip-fetch test-all --include-tor --socks-port 10000 --json", "description": "Complete test suite including Tor tests, forced to Kodachi pool port 10000 (skip auto-detect)", "expectedOutput": "JSON formatted test results with the specified Tor SOCKS port" }, { "command": "ip-fetch test-all --json", "description": "JSON formatted complete test results", "expectedOutput": "Structured test suite results" } ], "id": "8_comprehensive_testing_suite", "title": "Comprehensive Testing Suite" }, { "description": "Test random IP sources for reliability", "examples": [ { "command": "ip-fetch random --type plain --ipv4", "description": "Test ONE random IPv4 plain text source", "expectedOutput": "Random IPv4 source test result" }, { "command": "ip-fetch random --type json --ipv4 --json", "description": "Test ONE random IPv4 JSON source with JSON output", "expectedOutput": "Random IPv4 JSON source test result" }, { "command": "ip-fetch random --type dns --ipv4", "description": "Test ONE random DNS IPv4 query", "expectedOutput": "Random DNS IPv4 query result" }, { "command": "ip-fetch random --type dns --ipv6 --json", "description": "Test ONE random DNS IPv6 query with JSON output", "expectedOutput": "Random DNS IPv6 query result in JSON" } ], "id": "9_random_source_testing", "title": "Random Source Testing" }, { "description": "Test geolocation APIs with various IPs", "examples": [ { "command": "ip-fetch geo", "description": "Test geo APIs with current IP", "expectedOutput": "Geolocation test results for your IP" }, { "command": "ip-fetch geo --ip 208.67.222.222", "description": "Test geo APIs with specific IP", "expectedOutput": "Geolocation test results for 208.67.222.222" }, { "command": "ip-fetch geo --json-pretty", "description": "Compare every geo API side by side as indented JSON", "expectedOutput": "One indented JSON block per geolocation API that answered", "notes": "geo always prints each API's raw response, so there is no separate verbose mode." }, { "command": "ip-fetch geo --ip 1.1.1.1 --json", "description": "Geo data for IP in JSON", "expectedOutput": "JSON geolocation data for 1.1.1.1" } ], "id": "10_geolocation_testing", "title": "Geolocation API Testing" }, { "description": "Get IP addresses in plain text format", "examples": [ { "command": "ip-fetch plain-ip --ipv4", "description": "Get IPv4 plain text", "expectedOutput": "Your IPv4 address as plain text" }, { "command": "ip-fetch plain-ip --ipv6", "description": "Get IPv6 plain text", "expectedOutput": "Your IPv6 address as plain text" }, { "command": "ip-fetch plain-ip --ipv4 --server-index 5", "description": "Use specific server by index", "expectedOutput": "IPv4 from server index 5" } ], "id": "11_plain_text_ip", "title": "Plain Text IP Retrieval" }, { "description": "Look several IPs up in one round trip. Bulk mode turns on automatically for more than one IP. Every bulk lookup is authentication gated: run 'online-auth authenticate' first or the command fails with 'Authentication required'.", "examples": [ { "command": "ip-fetch --bulk 1.1.1.1 9.9.9.9 208.67.222.222", "description": "Efficient bulk lookup of multiple IPs", "expectedOutput": "Bulk results for all IPs", "notes": "Requires an authenticated session. Run 'online-auth authenticate' first." }, { "command": "ip-fetch --bulk 1.1.1.1 9.9.9.9 --json", "description": "Bulk lookup with JSON output", "expectedOutput": "JSON array with all IP data" }, { "command": "ip-fetch --nobulk 1.1.1.1 9.9.9.9", "description": "Disable bulk mode for individual lookups", "expectedOutput": "Individual lookup results" }, { "command": "ip-fetch --bulk --ipv4 1.1.1.1 9.9.9.9", "description": "Bulk IPv4-only lookups", "expectedOutput": "Bulk IPv4 results" }, { "command": "ip-fetch --bulk --nohistory 1.1.1.1 9.9.9.9 208.67.222.222", "description": "Bulk lookup without saving to history", "expectedOutput": "Bulk results (not saved)" } ], "id": "12_bulk_operations", "title": "Bulk Operations" }, { "description": "Inspect and manage the IP cache, and control the cache on a single lookup with --no-cache, --cache-only or --refresh-cache.", "examples": [ { "command": "ip-fetch --no-cache", "description": "Bypass the cache and force a fresh lookup of your own IP", "expectedOutput": "Live IP data fetched from the network, cache untouched", "notes": "Mutually exclusive with --cache-only." }, { "command": "ip-fetch --cache-only 208.67.222.222", "description": "Answer from the cache only, never touch the network", "expectedOutput": "Cached data for 208.67.222.222, or an error if it is not cached", "notes": "Useful offline. Fails rather than falling back to the network. Mutually exclusive with --no-cache." }, { "command": "ip-fetch --refresh-cache", "description": "Fetch fresh data and overwrite the cached entry even if it is still valid", "expectedOutput": "Fresh IP data, cache entry rewritten" }, { "command": "ip-fetch cache status", "description": "Show cache statistics and status", "expectedOutput": "Cache size, entry count and configured TTL" }, { "command": "ip-fetch cache list", "description": "List all cached IP addresses", "expectedOutput": "Every IP address currently held in the cache" }, { "command": "ip-fetch cache clear", "description": "Clear the entire cache", "expectedOutput": "Confirmation that all cached entries were removed", "notes": "Pass an IP to clear only that entry, e.g. 'ip-fetch cache clear 208.67.222.222'" }, { "command": "ip-fetch cache clear 208.67.222.222", "description": "Clear a specific IP from the cache", "expectedOutput": "Confirmation that 208.67.222.222 was removed from the cache" }, { "command": "ip-fetch cache set-ttl 24h", "description": "Set the default cache TTL", "expectedOutput": "Confirmation that the cache TTL was updated", "notes": "Accepts duration strings such as '24h', '7d' or '1w'" } ], "id": "13_cache_management", "title": "Cache Management" }, { "description": "Use custom servers for IP lookup", "examples": [ { "command": "ip-fetch --server https://api.ipify.org", "description": "Use custom server for IP lookup", "expectedOutput": "IP from custom server" }, { "command": "ip-fetch --server https://api.ipify.org --json", "description": "Custom server with JSON output", "expectedOutput": "JSON from custom server" }, { "command": "ip-fetch --server https://ipv4.icanhazip.com --ipv4", "description": "Custom IPv4 server", "expectedOutput": "IPv4 from custom server" }, { "command": "ip-fetch --server https://ipv6.icanhazip.com --ipv6", "description": "Custom IPv6 server", "expectedOutput": "IPv6 from custom server" } ], "id": "14_server_options", "title": "Custom Server Options" }, { "description": "The cli-core output flags below work on every ip-fetch command, not just the default lookup.", "examples": [ { "command": "ip-fetch 208.67.222.222 --json-pretty", "description": "Indented JSON for one IP, readable in a terminal", "expectedOutput": "Multi-line, indented JSON object for 208.67.222.222" }, { "command": "ip-fetch --json-human", "description": "Colorized, jq-style JSON for reading at a glance", "expectedOutput": "Syntax-highlighted JSON of your own IP data" }, { "command": "ip-fetch --no-color", "description": "Strip ANSI colors, for redirecting into a file or a pipe", "expectedOutput": "Plain, uncolored text output" } ], "id": "15_output_options", "title": "Output Formatting Options" }, { "description": "--nohistory belongs to the default lookup (the 'fetch' path) and only suppresses history there. It is NOT a global flag: writing it alongside a subcommand such as 'tor', 'dns' or 'geo' does not suppress anything, because those subcommands never read it. Every form below is a plain lookup, which is the only place the flag has an effect.", "examples": [ { "command": "ip-fetch --nohistory", "description": "Look up your own IP without writing it to the history file", "expectedOutput": "Your current IP with geolocation data, nothing appended to history" }, { "command": "ip-fetch --nohistory 208.67.222.222", "description": "Look up one specific IP without recording it", "expectedOutput": "Geolocation data for 208.67.222.222, nothing appended to history" }, { "command": "ip-fetch --nohistory --ipv6 --json", "description": "Get your IPv6 as JSON without recording it", "expectedOutput": "JSON object with your IPv6 data, nothing appended to history" }, { "command": "ip-fetch --bulk --nohistory 1.1.1.1 9.9.9.9 208.67.222.222", "description": "Bulk lookup of several IPs without recording any of them", "expectedOutput": "Bulk results for all three IPs, nothing appended to history", "notes": "Bulk mode is authentication gated. Run 'online-auth authenticate' first." } ], "id": "16_no_history", "title": "No History Operations" } ], "description": "Usage examples for ip-fetch", "name": "ip-fetch", "quickReference": [ "ip-fetch", "ip-fetch 208.67.222.222 --json", "ip-fetch check-tor", "ip-fetch tor --ipv4", "ip-fetch cache status", "ip-fetch test-all", "ip-fetch --help", "ip-fetch --version", "ip-fetch --info --json", "ip-fetch --examples" ] }, "errors": [], "metadata": { "executionTime": 4, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:32.056287252Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "dns-leak", "path": "/opt/kodachi/dashboard/hooks/dns-leak", "timestamp": "2026-07-21T01:54:32Z", "file_info": { "size": 5653536, "sha256": "82d220f7ef47880a1ba898098733ab2821dd631bbd24cde429a8d32a92fcbb63" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "DNS leak detection and analysis for Kodachi OS", "features": [ "Network interface discovery and validation", "DNS leak detection via challenge-response testing", "Geolocation-based leak analysis", "Multi-interface simultaneous testing", "Detailed test reporting with JSON export", "System resolver configuration analysis" ], "license": "Proprietary", "name": "dns-leak", "securityFeatures": { "authentication": "Secure authentication for sensitive operations", "encryption": "HTTPS for all external API communications", "inputValidation": "All interface names and IDs are sanitized and validated", "rateLimiting": "Built-in retry limits and timeouts for DNS queries" }, "systemRequirements": { "dependencies": [ "Network interfaces", "DNS resolver access", "Internet connectivity for leak testing" ], "os": "Linux (Debian-based, specifically Kodachi OS)", "privileges": "root/sudo for network interface access" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:32.773175849Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "005897c3f3d5956a3211bf723def023febf10b13", "name": "dns-leak", "rustVersion": "1.97.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 3, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:32.932545723Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Network Discovery", "commands": [ { "description": "Discover network interfaces available for testing (no root, no authentication needed)", "examples": [ "dns-leak discover", "dns-leak discover --json", "dns-leak discover -V" ], "name": "discover", "options": [ { "default": "off", "description": "Verbose interface details, repeat (-VV) for more. The global --verbose flag does NOT affect this command", "flag": "-V, --discover-verbose", "required": false } ], "requires_sudo": false, "usage": "dns-leak discover [OPTIONS]" } ] }, { "category": "DNS Leak Testing", "commands": [ { "description": "Run DNS leak test on specified interface or all interfaces (requires prior online-auth authentication; this is also what a bare `dns-leak` runs)", "examples": [ "dns-leak test", "dns-leak test --interface tun0", "dns-leak test --json", "dns-leak test --keep-all" ], "name": "test", "options": [ { "default": "all active non-loopback interfaces", "description": "Specify a network interface to test", "flag": "-i, --interface <INTERFACE>", "required": false }, { "default": "5", "description": "DNS query timeout, 1-60 seconds", "flag": "--dns-timeout <SECONDS>", "required": false }, { "default": "off (IP masked)", "description": "Print and save the unmasked public IP (masked by default)", "flag": "--show-public-ip", "required": false }, { "default": "off (older results pruned)", "description": "Keep every result file (by default older result files are pruned)", "flag": "--keep-all", "required": false } ], "requires_sudo": false, "usage": "dns-leak test [OPTIONS]" } ] }, { "category": "Reporting", "commands": [ { "description": "Generate a detailed report of a previous test (run the test with --keep-all if you want old result files to survive)", "examples": [ "dns-leak report --id dns_leak_results_<TIMESTAMP>", "dns-leak report --id dns_leak_results_<TIMESTAMP> --json" ], "name": "report", "options": [ { "description": "Test ID to generate report for", "flag": "-r, --id <ID>", "required": true } ], "requires_sudo": false, "usage": "dns-leak report -r <ID>" }, { "description": "Display results from a previous DNS leak test (run the test with --keep-all if you want old result files to survive)", "examples": [ "dns-leak results --file test_results.json", "dns-leak results --file test_results.json --json" ], "name": "results", "options": [ { "description": "Path to the results JSON file", "flag": "-f, --file <FILE>", "required": true } ], "requires_sudo": false, "usage": "dns-leak results --file <FILE>" } ] } ], "description": "DNS leak detection and analysis for Kodachi OS", "dnsLeakDetectionMethods": [ "Real DNS resolution (system resolver, unique challenge subdomains per test run)", "External API verification (challenge-response correlation)", "Direct DNS server comparison and geolocation analysis", "Country-based DNS server leak detection", "System resolver configuration analysis" ], "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Authentication required", "7": "DNS leak detected" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Verbose interface details (discover only, repeat -VV for more)", "flag": "-V, --discover-verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 30)", "flag": "--timeout <SECS>" }, { "description": "Retry attempts (default: 3)", "flag": "--retry <COUNT>" }, { "description": "DNS query timeout (default: 5)", "flag": "--dns-timeout <SECS>" }, { "description": "Specify network interface to test", "flag": "-i, --interface <IF>" }, { "description": "Show unmasked public IP in output and saved files (default: masked)", "flag": "--show-public-ip" }, { "description": "Keep all result files (default: older files pruned for privacy)", "flag": "--keep-all" } ], "interfaceSpecifications": { "commonInterfaces": "eth0, ens33, enp2s0, enp2s1, eno1, wlan0, wlx18a6f71995d8, tun0, tailscale0, br0", "notes": [ "If no interface specified, all active interfaces will be tested", "Loopback interface (lo) is automatically excluded from testing", "Supports Predictable Network Interface Names (enp*, ens*, eno*, enx*)", "Includes USB wireless adapters (wlx*) and VPN tunnels (tun*, tailscale*)" ] }, "name": "dns-leak", "outputFormats": { "json": "Machine-readable output suitable for automation (use --json flag)", "standard": "Human-readable text output with colored status indicators" }, "usage": "dns-leak [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 7, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:33.164799055Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "List the interfaces you can test, then test them for DNS leaks. No root is needed for any dns-leak command, but the leak test itself needs an active online-auth session.", "examples": [ { "command": "dns-leak discover", "description": "See which network interfaces can be tested", "expectedOutput": "One block per interface with its name, type, IP addresses, DNS resolution state and configured DNS servers (loopback is excluded)" }, { "command": "dns-leak", "description": "Run the default DNS leak test on every active interface (identical to `dns-leak test`)", "expectedOutput": "Per-interface DNS servers with their country, plus a leak verdict for each interface", "notes": "Needs an authenticated session and internet access. Without a session it exits with 'Authentication required for command: test'; run `online-auth authenticate` first." }, { "command": "dns-leak test --interface tun0", "description": "Check that a VPN tunnel is not leaking DNS to the ISP resolver", "expectedOutput": "DNS servers observed through tun0 and a leak verdict for that interface" }, { "command": "dns-leak test --json", "description": "Run the leak test and emit machine-readable JSON", "expectedOutput": "A result envelope whose data carries the per-interface findings and the potential_leak_detected flag" } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "Find out which interfaces exist before you test one. Loopback (lo) is always excluded. Discovery needs no authentication.", "examples": [ { "command": "dns-leak discover", "description": "List all interfaces available for DNS leak testing", "expectedOutput": "Interface names with type, IP addresses, DNS resolution state and DNS servers, for example eth0, wlan0 and tun0" }, { "command": "dns-leak discover -V", "description": "Same list with the extra per-interface detail", "expectedOutput": "Interface list plus is-up, loopback, interface-type and address-count fields", "notes": "-V is short for --discover-verbose and can be repeated (-VV) for more detail. The global --verbose flag does NOT change discovery output." }, { "command": "dns-leak discover --json", "description": "List interfaces as JSON for automation", "expectedOutput": "JSON envelope with data.interfaces[] and data.total_count" }, { "command": "dns-leak discover --json | jq '.data.interfaces[].name'", "description": "Extract only interface names, ready to loop over in a script", "expectedOutput": "One quoted interface name per line" } ], "id": "1_interface_discovery", "title": "Interface Discovery" }, { "description": "Test every active interface, or one interface by name. Interface names follow the usual Linux schemes: eth0, ens33, enp2s0 and eno1 (wired), wlan0 and wlx<mac> (wireless), tun0 and tailscale0 (VPN), br0 (bridge). Take the exact name from `dns-leak discover`. Every test needs an authenticated session and internet access.", "examples": [ { "command": "dns-leak test", "description": "Test all active non-loopback interfaces for DNS leaks", "expectedOutput": "A block per interface listing the DNS servers that answered, their country, and a leak verdict", "notes": "Needs an active online-auth session and internet access. Exit code 7 signals that a DNS leak was detected." }, { "command": "dns-leak test --interface eth0", "description": "Test a single named interface instead of all of them", "expectedOutput": "DNS leak test result for eth0 only", "notes": "Replace eth0 with any name reported by `dns-leak discover` (wlan0, tun0, enp2s0, tailscale0, br0, ...). Unknown or malformed names are rejected before the test runs." }, { "command": "dns-leak test --interface tun0", "description": "Verify a VPN tunnel: confirm DNS queries leave through the tunnel and not through the ISP resolver", "expectedOutput": "DNS servers seen through tun0 with their country, compared against your visible exit location", "notes": "This is the check worth running right after connecting a VPN or Tor." }, { "command": "dns-leak test --json | jq '.data.potential_leak_detected'", "description": "Reduce a full test to a single true/false for scripting", "expectedOutput": "true or false" } ], "id": "2_leak_testing", "title": "DNS Leak Testing" }, { "description": "By default dns-leak masks your public IP and prunes older result files. Both flags below opt out of that, so reach for them deliberately.", "examples": [ { "command": "dns-leak test --show-public-ip", "description": "Show the real public IP instead of the masked one", "expectedOutput": "The usual leak report, but the public IP is printed in full rather than partially masked", "notes": "PRIVACY: the unmasked IP is also written into the saved JSON result file, which stays on disk. Use it only when you need the exact address, for example when filing a bug, and delete the result file afterwards." }, { "command": "dns-leak test --keep-all", "description": "Keep every result file instead of pruning the older ones", "expectedOutput": "The test runs normally and no previous dns_leak_results_*.json file is removed", "notes": "Without this flag a text-mode test prunes older result files, so the files that `results --file` and `report --id` need can vanish. Kept files record DNS servers and timestamps, so clean them up yourself." }, { "command": "dns-leak test --interface tun0 --keep-all --json", "description": "Keep the result file of a tunnel test so you can report on it later", "expectedOutput": "JSON envelope for tun0, with its dns_leak_results_<TIMESTAMP>.json file left in the results directory" } ], "id": "3_privacy_and_result_files", "title": "Privacy and Result Files" }, { "description": "Re-open a test you already ran. Both commands read the dns_leak_results_*.json files in the results directory, so the test that produced them must have been run with --keep-all if it is not the most recent one.", "examples": [ { "command": "dns-leak results --file dns_leak_results_<TIMESTAMP>.json", "description": "Print a saved test result again, without re-running the test", "expectedOutput": "The same per-interface DNS servers and leak verdict as the original run", "notes": "Replace <TIMESTAMP> with a real filename from a prior run. The file is looked up in the current directory first, then in the results directory, so a bare filename is enough." }, { "command": "dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json", "description": "Re-emit a saved result as JSON", "expectedOutput": "JSON envelope holding the stored test result" }, { "command": "dns-leak report --id dns_leak_results_<TIMESTAMP>", "description": "Build a shareable HTML report from a saved test", "expectedOutput": "Report generated successfully: <results directory>/dns_leak_report_<TIMESTAMP>.html", "notes": "The ID is the result filename without the .json extension. A partial ID also works: the first result file whose name contains it is used." }, { "command": "dns-leak report --id dns_leak_results --json", "description": "Report on the first matching saved test and print the status as JSON", "expectedOutput": "JSON envelope with status success once the HTML report is written", "notes": "This is the partial-ID form: it matches the first dns_leak_results_*.json file in the results directory, so pass a full ID when it matters which." } ], "id": "4_reports_and_saved_results", "title": "Reports and Saved Results" }, { "description": "Slow links, captive portals and Tor exits can need longer waits than the defaults.", "examples": [ { "command": "dns-leak test --timeout=30 --retry=3", "description": "Give the external leak-check calls more time and more attempts", "expectedOutput": "The usual leak report, just slower to give up", "notes": "Timeout range: 1-300 seconds. Retry count: 1-20. This bounds the HTTP calls, not the DNS queries." }, { "command": "dns-leak test --dns-timeout=10", "description": "Wait longer for each individual DNS query to answer", "expectedOutput": "The usual leak report, with slow resolvers given 10 seconds instead of the default", "notes": "DNS timeout range: 1-60 seconds. Separate from --timeout, which bounds the HTTP verification calls." }, { "command": "dns-leak test --interface wlan0 --dns-timeout=15 --timeout=60", "description": "Test one slow wireless link with both waits raised", "expectedOutput": "DNS leak test result for wlan0" } ], "id": "5_timeouts_and_retries", "title": "Timeouts and Retries" }, { "description": "Version, capabilities, help and examples, in text or JSON.", "examples": [ { "command": "dns-leak --version", "description": "Show the version number", "expectedOutput": "dns-leak version <VERSION>" }, { "command": "dns-leak --version --json", "description": "Version with build date, commit and Rust version, as JSON", "expectedOutput": "JSON envelope with name, version, buildDate, gitCommit" }, { "command": "dns-leak --info", "description": "Show what this tool does, its features and its requirements", "expectedOutput": "Program description, feature list, security features and system requirements" }, { "command": "dns-leak --info --json", "description": "The same capability record, machine-readable", "expectedOutput": "JSON envelope with the program info structure" }, { "command": "dns-leak --help", "description": "Show every command, option and exit code", "expectedOutput": "Grouped command list with options and global flags" }, { "command": "dns-leak test --help", "description": "Show the help for a single subcommand", "expectedOutput": "clap help for `test` with its own flags" }, { "command": "dns-leak test --examples", "description": "Show only the examples that apply to one subcommand", "expectedOutput": "The test examples, without the discover/report/results ones" }, { "command": "dns-leak --examples --json", "description": "All examples as JSON, for docs and tooling", "expectedOutput": "JSON envelope with categories[] and quickReference[]" } ], "id": "6_program_information", "title": "Program Information" } ], "description": "Usage examples for dns-leak", "name": "dns-leak", "quickReference": [ "dns-leak discover", "dns-leak test", "dns-leak test --interface tun0", "dns-leak test --json", "dns-leak results --file dns_leak_results_<TIMESTAMP>.json", "dns-leak report --id dns_leak_results_<TIMESTAMP>", "dns-leak --help", "dns-leak --version", "dns-leak --info --json", "dns-leak --examples --json" ] }, "errors": [], "metadata": { "executionTime": 11, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:33.575027082Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "global-launcher", "path": "/opt/kodachi/dashboard/hooks/global-launcher", "timestamp": "2026-07-21T01:54:34Z", "file_info": { "size": 2056992, "sha256": "eb9bea3916defb0252124193b6a86f1284a61167d04bfc5662f9d15f50c9aa6f" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Global launcher for Kodachi dashboard binaries with execution folder containment", "features": [ "Dynamic binary discovery and deployment", "Execution folder containment for security", "Symlink-based global access", "Comprehensive error handling and logging", "Support for both Rust and Gambas binaries", "Deployment verification and rollback", "JSON and text output formats", "Zero hardcoded paths - fully dynamic" ], "license": "Proprietary", "name": "global-launcher", "securityFeatures": { "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", "inputValidation": "All binary names and paths are validated against security rules", "rateLimiting": "Configurable timeouts prevent resource exhaustion" }, "systemRequirements": { "dependencies": [ "cli-core library", "logs-hook service", "symlink support in filesystem" ], "os": "Linux (Debian-based, specifically Kodachi OS)", "privileges": "root/sudo for global deployment" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:34.294728403Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "926929be", "name": "global-launcher", "rustVersion": "rustc 1.97.0 (2d8144b78 2026-07-07)", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:34.414597207Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Management Commands", "commands": [ { "description": "Deploy global symlinks for all dashboard binaries", "examples": [ "sudo ./global-launcher deploy", "sudo ./global-launcher deploy --force", "sudo ./global-launcher deploy --no-verify", "sudo ./global-launcher deploy --save-hashes --json" ], "name": "deploy", "options": [ { "default": "false", "description": "Force deployment even if binaries exist", "flag": "--force" }, { "default": "false", "description": "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", "flag": "--no-verify" }, { "default": "false", "description": "Write results/deployment-hashes.json (SHA256 of each source binary plus the launcher)", "flag": "--save-hashes" } ], "requires_sudo": true, "usage": "global-launcher deploy [OPTIONS]" }, { "description": "Verify deployed symlinks are working", "examples": [ "./global-launcher verify", "./global-launcher verify --detailed", "./global-launcher verify --save-hashes --json" ], "name": "verify", "options": [ { "default": "false", "description": "Show detailed verification info", "flag": "--detailed" }, { "default": "false", "description": "Write results/verification-hashes.json (SHA256 of each source binary plus the launcher)", "flag": "--save-hashes" } ], "requires_sudo": false, "usage": "global-launcher verify [OPTIONS]" }, { "description": "Remove all deployed symlinks", "examples": [ "sudo ./global-launcher cleanup", "sudo ./global-launcher cleanup --json" ], "name": "cleanup", "options": [ { "default": "false", "description": "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", "flag": "--yes" } ], "requires_sudo": true, "usage": "global-launcher cleanup [OPTIONS]" } ] } ], "description": "Global launcher for Kodachi dashboard binaries", "environmentVariables": [ { "default": "900", "description": "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)", "name": "GLOBAL_LAUNCHER_TIMEOUT", "values": "positive integer (seconds)" }, { "default": "/usr/local/bin", "description": "Directory the symlinks are created in and removed from. Overrides the built-in /usr/local/bin target for deploy, verify and cleanup", "name": "GLOBAL_BIN_DIR", "values": "absolute path to a directory on PATH" }, { "default": "auto-detected from the launcher's own location", "description": "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", "name": "KODACHI_BASE_DIR", "values": "absolute path to the hooks directory" }, { "default": "unset", "description": "Disable colored output when set to any value", "name": "NO_COLOR", "values": "any value disables color" } ], "exitCodes": { "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" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved human-readable formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "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)", "flag": "--timeout <SECONDS>" }, { "description": "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", "flag": "--user-override <USERNAME>" }, { "description": "Force output format: text (default) or json. '-o json' is equivalent to --json", "flag": "-o, --output-format <FORMAT>" } ], "name": "global-launcher", "usage": "global-launcher [OPTIONS] [COMMAND]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:34.523832383Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Create the /usr/local/bin symlinks so every hook binary is callable from anywhere. Run these from the hooks directory.", "examples": [ { "command": "sudo ./global-launcher deploy", "description": "Deploy global access for all discovered dashboard binaries", "expectedOutput": "āœ… SUCCESS: Deployed <COUNT> binaries to /usr/local/bin", "notes": "Needs root: it writes symlinks into /usr/local/bin. Set GLOBAL_BIN_DIR to deploy somewhere else." }, { "command": "sudo ./global-launcher deploy --force", "description": "Redeploy over names that already exist in the target directory", "expectedOutput": "āœ… SUCCESS: Deployed <COUNT> binaries to /usr/local/bin", "notes": "Without --force, a name already taken by a real file (not a launcher symlink) is left alone and the deploy is reported as failed." }, { "command": "sudo ./global-launcher deploy --no-verify", "description": "Deploy without the post-deployment symlink check", "expectedOutput": "āœ… SUCCESS: Deployed <COUNT> binaries to /usr/local/bin", "notes": "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." }, { "command": "sudo ./global-launcher deploy --save-hashes --json", "description": "Deploy, write the hash report, and print the machine-readable result", "expectedOutput": "JSON envelope with total_symlinks_created and failed_deployments, plus results/deployment-hashes.json on disk", "notes": "The report lands in the hooks directory under results/, not in the current working directory." } ], "id": "1_deployment", "title": "Deployment Operations" }, { "description": "Check that the deployed symlinks still resolve to the current binaries.", "examples": [ { "command": "./global-launcher verify", "description": "Check every deployed symlink", "expectedOutput": "āœ… SUCCESS: <COUNT> verified, 0 broken", "notes": "No root needed: this only reads. Exits 7 if any symlink is broken." }, { "command": "./global-launcher verify --detailed", "description": "List each symlink with its target path and source hash", "expectedOutput": "One '+ name -> /path/to/hooks/name (hash: ...)' line per verified symlink" }, { "command": "./global-launcher verify --save-hashes --json", "description": "Verify, write results/verification-hashes.json, and print the JSON result", "expectedOutput": "JSON envelope with verified_symlinks[] (each carrying source_binary_hash and launcher_hash) and broken_symlinks[]" } ], "id": "2_verification", "title": "Verification Operations" }, { "description": "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.", "examples": [ { "command": "cat results/verification-hashes.json", "description": "Read the report left by the last 'verify --save-hashes'", "expectedOutput": "JSON with a SHA256 for every source binary plus the launcher hash", "notes": "Path is relative to the hooks directory (or to KODACHI_BASE_DIR when set), which is where the launcher writes it." }, { "command": "cat results/deployment-hashes.json", "description": "Read the report left by the last 'deploy --save-hashes'", "expectedOutput": "Same shape as the verification report, captured at deploy time", "notes": "Each report overwrites the previous one; keep a copy yourself if you want history." }, { "command": "./global-launcher verify --save-hashes --json | jq '.data.verified_symlinks[0] | {name, source_binary_hash, launcher_hash}'", "description": "Pull one binary's hashes straight out of the verification run", "expectedOutput": "{\"name\": \"ip-fetch\", \"source_binary_hash\": \"...\", \"launcher_hash\": \"...\"}" } ], "id": "3_hash_integrity", "title": "Hash Reports and Integrity" }, { "description": "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.", "examples": [ { "command": "health-control internet-status", "description": "Run a hook binary from any working directory", "expectedOutput": "health-control's internet status output, exactly as if you had run it from the hooks directory", "notes": "Every argument is passed through as-is, so the target binary's own flags keep working." }, { "command": "ip-fetch --json", "description": "Run ip-fetch globally with JSON output", "expectedOutput": "ip-fetch's JSON envelope with the current IP information" }, { "command": "dns-switch list", "description": "List DNS servers from anywhere", "expectedOutput": "dns-switch's server list with the current configuration" }, { "command": "GLOBAL_LAUNCHER_TIMEOUT=60 health-control security-score", "description": "Bound how long the launcher will wait for a slow binary", "expectedOutput": "The target binary's normal output, or a timeout error after 60 seconds", "notes": "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." } ], "id": "4_usage", "title": "Execution Mode: Using the Global Binaries" }, { "description": "Remove the global symlinks. Only symlinks the launcher owns are touched; unrelated files in the target directory are left alone.", "examples": [ { "command": "sudo ./global-launcher cleanup", "description": "Remove every deployed symlink", "expectedOutput": "āœ… SUCCESS: Removed <COUNT> symlinks", "notes": "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." }, { "command": "sudo ./global-launcher cleanup --json", "description": "Remove the symlinks and print a machine-readable result", "expectedOutput": "JSON envelope with removed_count and a timestamp", "notes": "--yes is accepted but does nothing: cleanup never prompts, with or without it." } ], "id": "5_cleanup", "title": "Cleanup Operations" }, { "description": "Flags accepted by every management command.", "examples": [ { "command": "./global-launcher -h", "description": "Show the full help: commands, flags, environment variables and exit codes", "expectedOutput": "The help screen. Add --json for the same content as structured data" }, { "command": "./global-launcher -v", "description": "Print the version", "expectedOutput": "global-launcher version <VERSION>" }, { "command": "./global-launcher -n --json", "description": "Print the program information block as JSON (features, security model, requirements)", "expectedOutput": "JSON envelope with the ProgramInfo fields" }, { "command": "./global-launcher verify -o json --json-pretty", "description": "Force JSON output and indent it for reading", "expectedOutput": "Indented JSON verification result", "notes": "'-o json' is the same as --json. --json-human formats it further, jq-style." }, { "command": "./global-launcher verify --quiet --no-color", "description": "Suppress non-essential output and strip ANSI color, for logs and pipes", "expectedOutput": "Plain, uncolored output. NO_COLOR=1 in the environment does the same" } ], "id": "6_core_flags", "title": "Core Flags and Output Formats" }, { "description": "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.", "examples": [ { "command": "./global-launcher verify || (sudo ./global-launcher cleanup && sudo ./global-launcher deploy)", "description": "Repair the deployment whenever verification reports a broken symlink", "expectedOutput": "Either 'āœ… SUCCESS: <COUNT> verified, 0 broken', or a cleanup followed by a fresh deploy", "notes": "verify exits 7 on broken symlinks and deploy exits 7 on a failed deploy, which is what makes this loop work in a script." }, { "command": "GLOBAL_BIN_DIR=\"$HOME/.local/bin\" ./global-launcher deploy", "description": "Deploy into a user-writable directory instead of /usr/local/bin", "expectedOutput": "āœ… SUCCESS: Deployed <COUNT> binaries to /home/<user>/.local/bin", "notes": "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." } ], "id": "7_troubleshooting", "title": "Troubleshooting a Broken Deployment" } ], "description": "global-launcher has two modes. Run directly (./global-launcher deploy|verify|cleanup) it MANAGES the symlinks in /usr/local/bin that make every Kodachi hook binary callable from any directory. Invoked THROUGH one of those symlinks (for example 'ip-fetch --json') it becomes that binary's launcher: it re-enters the hooks directory, forwards your arguments unchanged and runs the real binary there. Management examples below are written to be run from the hooks directory.", "name": "global-launcher", "quickReference": [ "./global-launcher -h", "./global-launcher -e", "./global-launcher -n --json", "sudo ./global-launcher deploy", "./global-launcher verify --detailed", "sudo ./global-launcher cleanup", "ip-fetch --json" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:34.800968473Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "logs-hook", "path": "/opt/kodachi/dashboard/hooks/logs-hook", "timestamp": "2026-07-21T01:54:35Z", "file_info": { "size": 1749696, "sha256": "ce936d4a0b20310be6c0c7e0d3f5aec9631bde236a1439b36d8ab51389b36107" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "A robust, secure, and configurable logging system for Kodachi OS", "features": [ "Centralized logging system", "Log rotation with configurable limits", "Secure log wiping", "Multiple log levels support", "JSON output format", "Embedded configuration system" ], "license": "Proprietary", "name": "logs-hook", "securityFeatures": { "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)", "inputValidation": "Sanitizes script names and messages", "rateLimiting": "Not implemented in this crate (handled externally if required)" }, "systemRequirements": { "dependencies": [ "tokio runtime", "filesystem access" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system logs" }, "version": "9.8.4", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:35.314280647Z", "version": "9.8.4", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "logs-hook", "rustVersion": "1.88.0", "version": "9.8.4" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:35.416934899Z", "version": "9.8.4", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Logging Commands", "commands": [ { "description": "Log a message", "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" ], "name": "log", "options": [ { "description": "Script name for the log entry", "flag": "--script, -s <SCRIPT>", "required": true }, { "default": "info", "description": "Log level (info, warn, error, debug, fatal)", "flag": "--level, -l <LEVEL>", "required": false } ], "requires_sudo": false, "usage": "logs-hook log --script <SCRIPT> --level <LEVEL> <MESSAGE>" } ] }, { "category": "Maintenance Commands", "commands": [ { "description": "Rotate a specific log file (--file is required)", "examples": [ "logs-hook maintenance rotate --file /path/to/log.txt", "logs-hook maintenance rotate --file /path/to/log.txt --json" ], "name": "maintenance rotate", "options": [ { "description": "Log file to rotate (required; rotate-all is not supported)", "flag": "--file, -f <FILE>", "required": true } ], "requires_sudo": false, "usage": "logs-hook maintenance rotate --file <FILE>" }, { "description": "Wipe log files (--all, --file, or --confirm is required)", "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" ], "name": "maintenance wipe", "options": [ { "description": "Wipe all logs", "flag": "--all, -a", "required": false }, { "description": "Specific log file to wipe", "flag": "--file, -f <FILE>", "required": false }, { "description": "Explicitly confirm wipe using the default policy (required when neither --all nor --file is given)", "flag": "--confirm", "required": false } ], "requires_sudo": false, "usage": "logs-hook maintenance wipe (--all | --file <FILE> | --confirm)" } ] }, { "category": "Help Commands", "commands": [ { "description": "Show targeted help for a command path (handled before clap parsing)", "examples": [ "logs-hook help", "logs-hook help log", "logs-hook help maintenance wipe" ], "name": "help", "options": [], "requires_sudo": false, "usage": "logs-hook help [<COMMAND> [<SUBCOMMAND>]]" } ] } ], "description": "A robust, secure, and configurable logging system for Kodachi OS", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "auto-detected", "description": "Base directory for logs", "name": "KODACHI_BASE_DIR", "values": "/path/to/base/dir" }, { "default": "current directory", "description": "Working directory for logging operations", "name": "LOGS_HOOK_WORK_DIR", "values": "/path/to/work/dir" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced, colorized JSON output (jq-style); implies --json", "flag": "--json-human" }, { "description": "Set CLI log level, error|warn|info|debug (parsed globally; not applied by logs-hook, use the log --level flag instead)", "flag": "--log-level <LEVEL>" }, { "description": "Filter JSON output fields (parsed globally; not applied by logs-hook)", "flag": "--json-filter <FIELDS>" }, { "description": "Enable verbose output (parsed globally; not applied by logs-hook)", "flag": "--verbose" }, { "description": "Suppress non-essential output (parsed globally; not applied by logs-hook)", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (parsed globally; not applied by logs-hook)", "flag": "-t, --timeout <SECS>" }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir <PATH>" }, { "description": "Force output format (default: text)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Configuration file path (parsed globally; logs-hook uses embedded config only)", "flag": "--config <FILE>" }, { "description": "Select specific fields to include in output (parsed globally; not applied by logs-hook)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned (parsed globally; not applied by logs-hook)", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results for pagination (parsed globally; not applied by logs-hook)", "flag": "--offset <NUMBER>" } ], "name": "logs-hook", "usage": "logs-hook [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:35.527642485Z", "version": "9.8.4", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "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.", "examples": [ { "command": "logs-hook log --script 'my-script' --level info 'Script started'", "description": "Log an info message from a script", "expectedOutput": "Message logged successfully (appends '2026-07-13 09:14:02 UTC [INFO] | my-script: Script started' to <base_dir>/logs/my-script-log.log)" }, { "command": "logs-hook log -s 'backup' -l warn 'Low disk space'", "description": "Log a warning using the short flags", "expectedOutput": "Message logged successfully (line appended to <base_dir>/logs/backup-log.log)" }, { "command": "logs-hook log --script 'app' --level error 'Connection failed'", "description": "Log an error", "expectedOutput": "Message logged successfully", "notes": "--level accepts info, warn, error, debug or fatal. It defaults to info, and --script plus the message are both required." }, { "command": "logs-hook log --script 'app' --level debug 'Verbose trace'", "description": "Log a debug message", "expectedOutput": "Message logged successfully" }, { "command": "logs-hook log --script 'app' --level fatal 'Unrecoverable failure'", "description": "Log a fatal message", "expectedOutput": "Message logged successfully", "notes": "Fatal is the highest severity; reserve it for unrecoverable conditions" } ], "id": "1_basic_usage", "title": "Basic Usage" }, { "description": "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.", "examples": [ { "command": "logs-hook maintenance rotate --file <BASE_DIR>/logs/app-log.log", "description": "Force-rotate one log file to a numbered backup", "expectedOutput": "Log rotation completed for: \"<BASE_DIR>/logs/app-log.log\"", "notes": "--file is required and the file must exist; rotate-all is not supported. A bare 'maintenance rotate' exits 2." }, { "command": "logs-hook maintenance wipe --all", "description": "Wipe every log file in the log directory", "expectedOutput": "All logs wiped successfully", "notes": "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." }, { "command": "logs-hook maintenance wipe --file <BASE_DIR>/logs/app-log.log", "description": "Wipe one named log file", "expectedOutput": "Log wiped successfully: \"<BASE_DIR>/logs/app-log.log\"", "notes": "DESTRUCTIVE and irreversible for that file. The file must exist and be writable, otherwise the command exits 1 with FILE_NOT_FOUND." }, { "command": "logs-hook maintenance wipe --confirm", "description": "Wipe logs using the configured retention policy", "expectedOutput": "Logs wiped based on configuration", "notes": "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." } ], "id": "2_maintenance", "title": "Maintenance Operations" }, { "description": "Redirecting the log tree and running against a root-owned hooks directory.", "examples": [ { "command": "logs-hook --work-dir /custom/path log --script 'debug' --level info 'Custom directory test'", "description": "Write to a different base directory instead of the auto-detected one", "expectedOutput": "Message logged successfully (line appended to /custom/path/logs/debug-log.log)", "notes": "--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." }, { "command": "sudo logs-hook log --script 'installer' --level info 'Deployed'", "description": "Log into a root-owned base directory (for example the deployed /opt hooks tree)", "expectedOutput": "Message logged successfully", "notes": "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." }, { "command": "KODACHI_BASE_DIR=/opt/kodachi/dashboard/hooks logs-hook log -s 'cron' -l info 'Nightly job done'", "description": "Point logs-hook at a base directory through the environment instead of a flag", "expectedOutput": "Message logged successfully (line appended to /opt/kodachi/dashboard/hooks/logs/cron-log.log)" } ], "id": "3_advanced_usage", "title": "Advanced Usage" }, { "description": "Machine-readable output. Every command returns the standard result envelope (status, command, version, data, duration_ms).", "examples": [ { "command": "logs-hook --json log --script 'app' --level error 'Connection failed'", "description": "Log a message and get the result envelope back as compact JSON", "expectedOutput": "{\"status\":\"success\",\"command\":\"log\",\"data\":{\"success\":true,\"message\":\"Message logged successfully\",\"script\":\"app\",\"level\":\"Error\",\"timestamp\":\"2026-07-13T09:14:02Z\"}, ...}" }, { "command": "logs-hook --json-pretty log -s 'test' -l info 'Test'", "description": "Same envelope, indented for reading", "expectedOutput": "Indented JSON envelope with the log result" }, { "command": "logs-hook --json-human maintenance rotate --file <BASE_DIR>/logs/app-log.log", "description": "Colorized, jq-style JSON for reading at a terminal", "expectedOutput": "Highlighted JSON envelope with operation 'rotate' and the resolved absolute file path", "notes": "--json-human implies JSON mode; do not pipe it to a parser, use --json for that." }, { "command": "logs-hook -v --json", "description": "Version as JSON", "expectedOutput": "JSON envelope carrying name, version and build metadata" }, { "command": "logs-hook -n --json", "description": "Program info (features, security posture, requirements) as JSON", "expectedOutput": "JSON envelope with the program info block" }, { "command": "logs-hook maintenance wipe --all --json", "description": "Wipe every log and capture the outcome for a script", "expectedOutput": "{\"status\":\"success\",\"command\":\"maintenance wipe\",\"data\":{\"operation\":\"wipe_all\",\"message\":\"All logs wiped successfully\"}, ...}", "notes": "DESTRUCTIVE and irreversible: --json only changes the reporting, not the effect." } ], "id": "4_json_output", "title": "JSON Output" }, { "description": "Discovering the exact flags of a subcommand and checking where output is going.", "examples": [ { "command": "logs-hook help maintenance wipe", "description": "Show the full help for one command path without running it", "expectedOutput": "The clap long help for 'maintenance wipe', listing --all, --file and --confirm", "notes": "'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." }, { "command": "logs-hook --no-color --json log --script 'debug' --level debug 'Debug info'", "description": "Log without ANSI colour codes, for capture into a file or a CI log", "expectedOutput": "Plain JSON envelope with no escape sequences" }, { "command": "logs-hook --work-dir /custom/path --json log -s 'pathcheck' -l info 'where did this go'", "description": "Confirm which directory a log actually landed in when the base directory is ambiguous", "expectedOutput": "Success envelope; the line is in /custom/path/logs/pathcheck-log.log", "notes": "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." } ], "id": "5_troubleshooting", "title": "Troubleshooting" } ], "description": "Usage examples for logs-hook", "name": "logs-hook", "quickReference": [ "logs-hook --help", "logs-hook --version", "logs-hook --info --json", "logs-hook --examples --json", "logs-hook help maintenance wipe", "logs-hook log -s 'test' -l info 'message'", "logs-hook maintenance rotate --file <BASE_DIR>/logs/app-log.log", "logs-hook maintenance wipe --all", "logs-hook maintenance wipe --file <BASE_DIR>/logs/app-log.log", "logs-hook maintenance wipe --confirm", "logs-hook --work-dir /custom/path log -s 'test' -l info 'msg'" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:35.764607720Z", "version": "9.8.4", "warnings": [] } }, { "name": "kodachi-soc-notifier", "path": "/opt/kodachi/dashboard/hooks/kodachi-soc-notifier", "timestamp": "2026-07-21T01:54:36Z", "file_info": { "size": 1558048, "sha256": "6d697d8fb8717c149dcb6c9a586f0487963ce67659fdaac175763e136d53e53b" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Copyright 2026 Kodachi OS", "description": "Bounded local user-session notifier for Kodachi host exposure findings", "features": [ "Dashboard-independent visual delivery for unread warning and critical findings", "Fail-visible degraded, untrusted, unsupported, stale, malformed, and unavailable coverage alerts", "Strict schema, freshness, size, path-ownership, and subprocess-timeout validation", "Bounded delivered-ID memory with retry after temporary session-bus failure", "No network client, payload capture, telemetry, approval, or containment actions", "Kodachi-standard help, info, version, examples, and JSON output via cli-core" ], "license": "Proprietary", "name": "kodachi-soc-notifier", "securityFeatures": { "authentication": "Root-owned local kodachi-soc consumer path; no remote authentication", "encryption": "Not applicable; local metadata and session-bus delivery only", "inputValidation": "Schema, size, freshness, path ownership, and local evidence trust validation", "rateLimiting": "One-second bounded polling with critical-first notification burst limits" }, "systemRequirements": { "dependencies": [ "kodachi-soc exposure summary", "notify-send", "graphical D-Bus notification service" ], "os": "Kodachi OS/Linux with a graphical systemd user session", "privileges": "Unprivileged user session; no root or sudo required" }, "version": "9.8.4", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:36.285374060Z", "version": "9.8.4", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "kodachi-soc-notifier", "rustVersion": "1.82.0", "version": "9.8.4" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:36.382005699Z", "version": "9.8.4", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [], "description": "Bounded local user-session notifier for Kodachi host exposure findings", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" } ], "name": "kodachi-soc-notifier", "usage": "kodachi-soc-notifier [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:36.492473468Z", "version": "9.8.4", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "The notifier is an unprivileged graphical-session consumer of the local kodachi-soc exposure summary. It delivers visual warning, critical, degraded, untrusted, and unsupported alerts while the dashboard is closed. It does not inspect traffic, read socket payloads, contact reputation services, acknowledge findings, approve behavior, terminate processes, block endpoints, isolate networking, or alter firewall rules. The watcher remains the sole authority for rule IDs, severity, deduplication, retained evidence, and unread state. The user service is bounded by MemoryHigh=24M, MemoryMax=32M, CPUQuota=5%, OOMScoreAdjust=500, and TasksMax=32.", "examples": [ { "command": "kodachi-soc-notifier -h", "description": "Show the notifier contract, privacy boundary, and resource cage", "expectedOutput": "Kodachi-standard text help generated by cli-core", "notes": "The systemd user service normally starts the notifier." }, { "command": "kodachi-soc-notifier -n --json", "description": "Read machine-readable notifier identity and feature metadata", "expectedOutput": "A schema-versioned cli-core information envelope" }, { "command": "kodachi-soc-notifier -e --json-pretty", "description": "Read the complete notifier example catalog as formatted JSON", "expectedOutput": "A cli-core examples envelope with the session-notifier category" }, { "command": "kodachi-soc-notifier", "description": "Run the foreground notification loop for service-manager use", "expectedOutput": "No normal stdout; visual alerts are delivered through the local session bus", "notes": "Use the installed systemd user unit for normal operation; Ctrl+C stops a foreground diagnostic run." } ], "id": "1_session_notifier", "title": "Session Notifier" } ], "description": "Usage examples for kodachi-soc-notifier", "name": "kodachi-soc-notifier", "quickReference": [ "kodachi-soc-notifier -h", "kodachi-soc-notifier -e", "kodachi-soc-notifier -n --json", "kodachi-soc-notifier -v --json" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:36.672665882Z", "version": "9.8.4", "warnings": [] } }, { "name": "conky-status", "path": "/opt/kodachi/dashboard/hooks/conky-status", "timestamp": "2026-07-21T01:54:37Z", "file_info": { "size": 4215904, "sha256": "ebb46dbb3c23f6df6e1fa9018edf506dcad98c1ed23cd4788e3fec5a26bcd224" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Unified Rust gateway for Kodachi Conky data", "features": [ "Bounded parallel adapter collection", "Unified snapshot cache with lock + atomic writes", "Privacy-first redaction for sensitive identifiers", "Compatibility aliases for legacy Conky scripts", "User-defined Conky command registry via JSON config", "Kodachi-standard CLI flags via cli-core" ], "license": "Proprietary", "name": "conky-status", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.139946466Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "conky-status", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.284999501Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Data", "commands": [ { "description": "Collect and output unified conky-status snapshot", "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" ], "name": "snapshot", "options": [ { "default": "on, unless --cached is passed", "description": "Collect fresh data now, ignoring the cache", "flag": "--refresh", "required": false }, { "default": "false", "description": "Serve the cached snapshot when it is still within --ttl, instead of collecting", "flag": "--cached", "required": false }, { "default": "30", "description": "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", "flag": "--ttl <seconds>", "required": false }, { "default": "2", "description": "How many adapters may run at once. Raising it speeds collection up but spawns more subprocesses; values below 1 are clamped to 1", "flag": "--max-parallel <n>", "required": false }, { "default": "12000", "description": "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", "flag": "--timeout-ms <ms>", "required": false } ], "requires_sudo": false, "usage": "conky-status snapshot [--refresh] [--cached] [--ttl <sec>] [--max-parallel <n>] [--timeout-ms <ms>]" }, { "description": "Get a single key value (snapshot key or user.<name> registry command)", "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" ], "name": "get", "options": [ { "description": "Key path or compatibility key to look up", "flag": "<KEY>", "required": true }, { "description": "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", "flag": "--default <value>", "required": false }, { "default": "false", "description": "Collect a fresh snapshot before the lookup instead of reading the cache", "flag": "--refresh", "required": false }, { "default": "30", "description": "How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection", "flag": "--ttl <seconds>", "required": false }, { "default": "2", "description": "Adapter concurrency used if this lookup has to collect. Clamped to at least 1", "flag": "--max-parallel <n>", "required": false }, { "default": "12000", "description": "Per-adapter timeout used if this lookup has to collect. Clamped to at least 200", "flag": "--timeout-ms <ms>", "required": false } ], "requires_sudo": false, "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>)" }, { "description": "Get one batched subset of the snapshot (one call per Conky panel instead of one per field)", "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" ], "name": "panel", "options": [ { "description": "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)", "flag": "<PANEL>", "required": true }, { "default": "false", "description": "Collect a fresh snapshot before building the panel instead of reading the cache", "flag": "--refresh", "required": false }, { "default": "30", "description": "How old the cached snapshot may be and still be used. --ttl 0 forces a fresh collection", "flag": "--ttl <seconds>", "required": false }, { "default": "1", "description": "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)", "flag": "--max-parallel <n>", "required": false }, { "default": "12000", "description": "Per-adapter timeout used if the panel has to collect. Clamped to at least 200", "flag": "--timeout-ms <ms>", "required": false } ], "requires_sudo": false, "usage": "conky-status panel <security|system|network|resources|gauges|all> [--refresh] [--ttl <sec>] [--max-parallel <n>] [--timeout-ms <ms>]" }, { "description": "Manage and execute user-defined Conky commands from JSON 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" ], "name": "user", "options": [ { "description": "Required action: path, init, list, or run", "flag": "<ACTION>", "required": true }, { "description": "Registered command name. Required when ACTION is run", "flag": "[NAME]", "required": false }, { "description": "Fallback printed when a run command fails or is missing. Applies only to ACTION run", "flag": "--default <value>", "required": false } ], "requires_sudo": false, "usage": "conky-status user <path|init|list|run> [NAME] [--default <value>] (--default applies to 'run')" } ] } ], "description": "Unified Rust gateway for Kodachi Conky data", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "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", "name": "KODACHI_FORCE_VERIFY", "values": "1" }, { "default": "the signatures directory next to the binary", "description": "Directory to look for the binary's signature files in, instead of the default location", "name": "KODACHI_SIG_DIR", "values": "path to a signature directory" }, { "default": "unset", "description": "Skip signature verification. Intended for build-pipeline self-tests on a not-yet-signed binary, not for normal use", "name": "KODACHI_BUILD_TEST", "values": "1" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" } ], "name": "conky-status", "usage": "conky-status [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.440653596Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Kodachi-standard global flags and output modes", "examples": [ { "command": "./conky-status -h", "description": "Show full CLI help", "expectedOutput": "Command/option reference" }, { "command": "./conky-status -v", "description": "Show binary version", "expectedOutput": "conky-status version <VERSION>" }, { "command": "./conky-status -n --json-pretty", "description": "Show program metadata using JSON pretty mode", "expectedOutput": "Envelope with info payload" }, { "command": "./conky-status -e", "description": "Show comprehensive usage examples", "expectedOutput": "Category-based examples list" }, { "command": "./conky-status snapshot --json-human", "description": "Use human-readable JSON rendering (jq-like)", "expectedOutput": "Enhanced JSON envelope", "notes": "Falls back to pretty JSON if jq is unavailable" } ], "id": "1_core_flags", "title": "Core Flags" }, { "description": "Refresh, cache, concurrency and timeout controls. The snapshot is the single collection every other command reads from: get and panel just slice it.", "examples": [ { "command": "./conky-status snapshot --json", "description": "Collect a snapshot using the default behavior (fresh collection)", "expectedOutput": "Envelope with meta, adapters and data sections" }, { "command": "./conky-status snapshot --cached --ttl 30", "description": "Reuse the cached snapshot when it is at most 30 seconds old", "expectedOutput": "A fast cached response, or a fresh collection if the cache is older than the TTL" }, { "command": "./conky-status snapshot --ttl 0 --json", "description": "Force a fresh collection by declaring that nothing counts as fresh", "expectedOutput": "A freshly collected snapshot with meta.stale false", "notes": "--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." }, { "command": "./conky-status snapshot --refresh --timeout-ms 1200", "description": "Force a new collection but give each adapter only 1.2 seconds", "expectedOutput": "A fresh snapshot; slow adapters are dropped and their fields fall back to defaults", "notes": "A tight timeout trades completeness for speed. Check meta and the adapters section to see which ones were dropped." }, { "command": "./conky-status snapshot --refresh --max-parallel 6 --json-pretty", "description": "Collect faster by running more adapters at once", "expectedOutput": "Pretty-printed JSON snapshot, collected in less wall time", "notes": "Each adapter is a subprocess, so keep this moderate. The default is 2 for snapshot and 1 for panel." } ], "id": "2_snapshot_modes", "title": "Snapshot Modes" }, { "description": "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.", "examples": [ { "command": "./conky-status get data.auth.group", "description": "Read authenticated user group", "expectedOutput": "Group value or '?'" }, { "command": "./conky-status get meta --json-pretty", "description": "Fetch a whole section instead of one field: here the snapshot metadata", "expectedOutput": "The meta object, including 'stale' and the collection timestamp", "notes": "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)." }, { "command": "./conky-status get data.health.score_display --default 0", "description": "Read health score with default fallback", "expectedOutput": "Numeric score string" }, { "command": "./conky-status get data.system.network.interface --refresh", "description": "Force refresh before interface lookup", "expectedOutput": "Interface name like ens33/wlan0" }, { "command": "./conky-status get data.tor.torrified_onoff --json", "description": "Structured JSON response for a single key", "expectedOutput": "Envelope with key, resolved_key, value, stale" } ], "id": "3_get_native_keys", "title": "Get Native Keys" }, { "description": "Legacy script-compatible key aliases for Conky migration", "examples": [ { "command": "./conky-status get ip-cache.ip --default Offline", "description": "Effective external IP (the Tor exit when torrified, the direct IP otherwise)", "expectedOutput": "Effective IP or Offline", "notes": "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." }, { "command": "./conky-status get ip-public.ip --default Offline", "description": "Direct WAN IP, regardless of Tor exit routing", "expectedOutput": "Public IP or Offline", "notes": "Always the real WAN address, even when torrified. Use ip-cache.ip when you want 'what the world sees'." }, { "command": "./conky-status get auth-detail.sessionid", "description": "Equivalent of auth-detail.sh sessionid", "expectedOutput": "Masked session token or N/A" }, { "command": "./conky-status get dns-cache.mode --default Unknown", "description": "Equivalent of dns-cache.sh mode", "expectedOutput": "DNS mode string" }, { "command": "./conky-status get system-status.swapperc --default 0", "description": "Gauge-ready swap usage percent from gateway", "expectedOutput": "Integer 0-100" }, { "command": "./conky-status get net-traffic.totalpercent --default 0", "description": "Gauge-ready total bandwidth percent (0-100)", "expectedOutput": "Integer 0-100", "notes": "Computed from total uploaded+downloaded bytes against 10 GiB scale" }, { "command": "./conky-status get security-status.vpn --json-pretty", "description": "Equivalent of security-status.sh vpn", "expectedOutput": "JSON envelope with boolean value" }, { "command": "./conky-status get cloud-status.cards", "description": "Equivalent of cloud-status.sh cards", "expectedOutput": "Cloud cards count or '?'" } ], "id": "4_get_compat_keys", "title": "Get Compatibility Keys" }, { "description": "Batched panel subsets for exec/execpi integration", "examples": [ { "command": "./conky-status panel security", "description": "Key=value output for security panel", "expectedOutput": "Multiple lines: internet/login/group/..." }, { "command": "./conky-status panel system --json-pretty", "description": "System panel subset in JSON", "expectedOutput": "Envelope with panel data map" }, { "command": "./conky-status panel network --refresh", "description": "Refresh before network panel render", "expectedOutput": "Updated panel key=value lines" }, { "command": "./conky-status panel resources", "description": "Resource panel subset (traffic plus the security booleans)", "expectedOutput": "Panel key=value lines" }, { "command": "./conky-status panel gauges --json", "description": "Everything a bar or gauge needs, in one call", "expectedOutput": "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", "notes": "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." }, { "command": "./conky-status panel all --json-human", "description": "Dump the full data section in human JSON mode", "expectedOutput": "Large JSON envelope with the whole data section" } ], "id": "5_panel_modes", "title": "Panel Modes" }, { "description": "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.", "examples": [ { "command": "${exec ./conky-status get ip-cache.ip --default Offline}", "description": "Render the effective external IP in a Conky text field", "expectedOutput": "The same scalar value the old script produced, for example 185.220.101.4 or Offline", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/ip-cache.sh ip}" }, { "command": "${exec ./conky-status get auth-detail.group --default '?'}", "description": "Render the authenticated group", "expectedOutput": "The group name, or ? when not authenticated", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/auth-detail.sh group}" }, { "command": "${exec ./conky-status get dns-cache.ns1 --default N/A}", "description": "Render the primary nameserver", "expectedOutput": "The nameserver address, or N/A", "notes": "Replaces: ${exec ~/.config/kodachi/conky/scripts/dns-cache.sh ns1}" }, { "command": "${execpi 20 ./conky-status panel security}", "description": "Fetch a whole panel on an interval instead of one exec per field", "expectedOutput": "key=value lines that the panel section of the conkyrc renders", "notes": "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." } ], "id": "6_conky_integration", "title": "Conky Integration" }, { "description": "Configure custom commands in JSON so Conky can call unsupported fields through the gateway", "examples": [ { "command": "./conky-status user path", "description": "Show registry file path", "expectedOutput": "~/.config/kodachi/conky/config/user-commands.json" }, { "command": "./conky-status user init", "description": "Create template registry if missing", "expectedOutput": "created: <path> or existing: <path>" }, { "command": "./conky-status user list --json-pretty", "description": "List registered custom command names", "expectedOutput": "JSON list with command count" }, { "command": "./conky-status user run hostname_short", "description": "Execute one configured command directly", "expectedOutput": "A single Conky-safe value on stdout", "notes": "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." }, { "command": "./conky-status user run uptime_pretty --default N/A", "description": "Run a registered command but never fail the conkyrc line that calls it", "expectedOutput": "The command's value, or N/A if it is missing or fails", "notes": "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." }, { "command": "./conky-status get user.hostname_short --default Unknown", "description": "Conky-friendly key path for a custom user command", "expectedOutput": "The scalar value produced by the registry-backed command", "notes": "custom.<name> is accepted as an alias for user.<name>." }, { "command": "${exec ./conky-status get user.hostname_short --default Unknown}", "description": "Direct Conky call without exposing command logic in bash", "expectedOutput": "Rendered value in panel" } ], "id": "7_user_command_registry", "title": "User Command Registry" }, { "description": "Binary self-signature verification diagnostics and enforcement", "examples": [ { "command": "KODACHI_FORCE_VERIFY=1 ./conky-status -v", "description": "Force signature check in debug builds", "expectedOutput": "Version output if signature verifies", "notes": "Fails with SECURITY error when signature is missing/invalid" }, { "command": "KODACHI_SIG_DIR=./results/signatures ./conky-status snapshot --json", "description": "Use custom signature directory", "expectedOutput": "Snapshot output with successful startup" }, { "command": "KODACHI_BUILD_TEST=1 ./conky-status -v", "description": "Skip signature check in controlled build-test mode", "expectedOutput": "Version output", "notes": "Intended for build pipeline self-tests only" }, { "command": "./conky-status -v", "description": "Release behavior with mandatory signature verification", "expectedOutput": "Version output or SECURITY failure message" } ], "id": "8_signature_verification", "title": "Signature Verification" } ], "description": "Usage examples for conky-status", "name": "conky-status", "quickReference": [ "./conky-status -h", "./conky-status -e", "./conky-status panel security", "./conky-status panel gauges --json", "./conky-status get ip-cache.ip --default Offline", "./conky-status snapshot --cached --ttl 30 --json", "./conky-status user list" ] }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:37.766787242Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "online-auth", "path": "/opt/kodachi/dashboard/hooks/online-auth", "timestamp": "2026-07-21T01:54:38Z", "file_info": { "size": 4685728, "sha256": "90232dbd2460ec9da9b0ad579fe5d7c6e21824085f031d9a905966e9d6814e49" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Copyright Ā© 2026 Kodachi Security OS", "description": "Secure online authentication client for Kodachi OS", "features": [ "Secure authentication with certificate pinning", "Session management with automatic heartbeat", "API key synchronization", "User group and status checking", "Comprehensive logging and error handling", "Multi-language architecture integration", "TLS 1.3 encrypted communications", "Real-time status monitoring", "Automatic retry mechanisms" ], "license": "Proprietary", "name": "online-auth", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 3, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:38.251602338Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "online-auth", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 4, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:38.348068450Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "API Management", "commands": [ { "description": "Manually sync API key with server", "examples": [ "sudo online-auth sync-api-key", "sudo online-auth sync-api-key --json" ], "name": "sync-api-key", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth sync-api-key [OPTIONS]" } ] }, { "category": "Authentication", "commands": [ { "description": "Authenticate with the server", "examples": [ "sudo online-auth authenticate", "sudo online-auth authenticate --json", "sudo online-auth authenticate --keep-alive", "sudo online-auth authenticate --keep-alive --json", "sudo online-auth authenticate --relogin", "sudo online-auth authenticate --keep-alive --relogin" ], "name": "authenticate", "options": [ { "description": "Keep the session alive with automatic heartbeats", "flag": "--keep-alive, -k", "required": false }, { "description": "Re-authenticate automatically when the session expires (implies --keep-alive)", "flag": "--relogin", "required": false }, { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth authenticate [OPTIONS]" }, { "description": "Check if currently logged in", "examples": [ "sudo online-auth check-login", "sudo online-auth check-login --json" ], "name": "check-login", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth check-login [OPTIONS]" }, { "description": "End the current session", "examples": [ "sudo online-auth logout", "sudo online-auth logout --json" ], "name": "logout", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth logout [OPTIONS]" }, { "description": "Check if user ID is blocked", "examples": [ "sudo online-auth check-if-blocked", "sudo online-auth check-if-blocked --json" ], "name": "check-if-blocked", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth check-if-blocked [OPTIONS]" }, { "description": "Show user and session IDs", "examples": [ "sudo online-auth get-ids", "sudo online-auth get-ids --json" ], "name": "get-ids", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth get-ids [OPTIONS]" }, { "description": "Show all status information at once", "examples": [ "sudo online-auth check-all-status", "sudo online-auth check-all-status --json" ], "name": "check-all-status", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth check-all-status [OPTIONS]" } ] }, { "category": "Heartbeat", "commands": [ { "description": "Send a single heartbeat", "examples": [ "sudo online-auth send-heartbeat", "sudo online-auth send-heartbeat --json" ], "name": "send-heartbeat", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth send-heartbeat [OPTIONS]" }, { "description": "Send heartbeat with retry", "examples": [ "sudo online-auth send-heartbeat-with-retry", "sudo online-auth send-heartbeat-with-retry --json" ], "name": "send-heartbeat-with-retry", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth send-heartbeat-with-retry [OPTIONS]" }, { "description": "Start automatic heartbeat service", "examples": [ "sudo online-auth start-heartbeat", "sudo online-auth start-heartbeat --json" ], "name": "start-heartbeat", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth start-heartbeat [OPTIONS]" }, { "description": "Stop automatic heartbeat service", "examples": [ "sudo online-auth stop-heartbeat", "sudo online-auth stop-heartbeat --json" ], "name": "stop-heartbeat", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth stop-heartbeat [OPTIONS]" }, { "description": "Check if heartbeat service is running", "examples": [ "sudo online-auth check-heartbeat", "sudo online-auth check-heartbeat --json" ], "name": "check-heartbeat", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth check-heartbeat [OPTIONS]" } ] }, { "category": "Information", "commands": [ { "description": "Get user card URL", "examples": [ "sudo online-auth get-card", "sudo online-auth get-card --json" ], "name": "get-card", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth get-card [OPTIONS]" }, { "description": "Check which user group you belong to (VIP = premium)", "examples": [ "sudo online-auth which-group", "sudo online-auth which-group --json" ], "name": "which-group", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth which-group [OPTIONS]" } ] }, { "category": "License", "commands": [ { "description": "Activate a license key for premium features", "examples": [ "sudo online-auth activate-license --key \"H7KM-P2Q9-R5TW-X3YZ-A4B2\"", "sudo online-auth activate-license -k \"H7KM-P2Q9-R5TW-X3YZ-A4B2\" --json" ], "name": "activate-license", "options": [ { "description": "License key in the format XXXX-XXXX-XXXX-XXXX-XXXX", "flag": "--key, -k <LICENSE_KEY>", "required": true }, { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth activate-license [OPTIONS]" }, { "description": "Release license to allow transfer to another device", "examples": [ "sudo online-auth release-license", "sudo online-auth release-license --json" ], "name": "release-license", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth release-license [OPTIONS]" }, { "description": "Check current license status and details", "examples": [ "sudo online-auth license-status", "sudo online-auth license-status --json" ], "name": "license-status", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth license-status [OPTIONS]" }, { "description": "Dismiss an admin popup message for this device (records dismissal server-side)", "examples": [ "sudo ADMIN_MESSAGE_ID=$(online-auth license-status --json | jq -r '.admin_messages[0].id') && online-auth dismiss-message --message-id \"$ADMIN_MESSAGE_ID\"", "sudo ADMIN_MESSAGE_ID=$(online-auth license-status --json | jq -r '.admin_messages[0].id') && online-auth dismiss-message -m \"$ADMIN_MESSAGE_ID\" --json" ], "name": "dismiss-message", "options": [ { "description": "UUID of the admin message to dismiss (read it from license-status admin_messages[].id)", "flag": "--message-id, -m <MESSAGE_ID>", "required": true }, { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth dismiss-message [OPTIONS]" } ] }, { "category": "Permission Guard", "commands": [ { "description": "Enable permission guard daemon to monitor and fix file permissions", "examples": [ "sudo online-auth enable-permission-guard", "sudo online-auth enable-permission-guard --json" ], "name": "enable-permission-guard", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth enable-permission-guard [OPTIONS]" }, { "description": "Disable permission guard daemon", "examples": [ "sudo online-auth disable-permission-guard", "sudo online-auth disable-permission-guard --json" ], "name": "disable-permission-guard", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth disable-permission-guard [OPTIONS]" }, { "description": "Check permission guard daemon status", "examples": [ "sudo online-auth permission-guard-status", "sudo online-auth permission-guard-status --json" ], "name": "permission-guard-status", "options": [ { "description": "Print the result envelope as compact JSON", "flag": "--json", "required": false }, { "description": "Print the result envelope as indented JSON", "flag": "--json-pretty", "required": false }, { "description": "Print colorized, jq-style JSON (implies --json)", "flag": "--json-human", "required": false } ], "requires_sudo": true, "usage": "online-auth permission-guard-status [OPTIONS]" } ] } ], "description": "Secure online authentication client for Kodachi OS", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir <PATH>" }, { "description": "Set custom port number (1024-65535)", "flag": "--port <PORT>" }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level <LEVEL>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config <FILE>" }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout <SECS>" } ], "name": "online-auth", "usage": "online-auth [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 3, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:38.457744430Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Logging in and out of Kodachi Cloud. Run online-auth with sudo: the device identity is derived from root-only hardware sources (dmidecode), so an unprivileged run computes a DIFFERENT hardware ID than the one the dashboard registered, and the server will not recognise the session. Every command below needs network access, and everything except authenticate needs an existing session.", "examples": [ { "command": "sudo online-auth authenticate", "description": "Log in to Kodachi Cloud and create a session", "expectedOutput": "Authentication successful, followed by the user ID and the session expiry", "notes": "Needs network access. Without sudo the hardware ID is computed from non-root sources and will not match the registered device." }, { "command": "sudo online-auth authenticate --json", "description": "Log in and capture the result for a script", "expectedOutput": "{\"status\":\"success\",\"command\":\"authenticate\",\"data\":{...session and user fields...},\"duration_ms\":...}" }, { "command": "sudo online-auth authenticate --keep-alive", "description": "Authenticate and enable auto-heartbeat", "expectedOutput": "Authentication successful with heartbeat enabled" }, { "command": "sudo online-auth authenticate --relogin", "description": "Authenticate with auto-relogin on disconnection", "expectedOutput": "Auto-relogin enabled with authentication", "notes": "Automatically enables heartbeat (--keep-alive) and re-authenticates when session expires" }, { "command": "sudo online-auth authenticate --keep-alive --relogin", "description": "Authenticate with explicit heartbeat and auto-relogin", "expectedOutput": "Authentication with heartbeat and auto-relogin enabled", "notes": "Both flags can be used together for clarity" }, { "command": "sudo online-auth check-login", "description": "Check whether a valid session exists right now", "expectedOutput": "Logged in as <USER_ID>, or 'Not logged in' with a non-zero exit code", "notes": "Exits non-zero when there is no session, which is what makes the 'check-login || authenticate' idiom work." }, { "command": "sudo online-auth logout", "description": "End the current session and clear the local session state", "expectedOutput": "Successfully logged out", "notes": "Also stops an active keep-alive heartbeat." }, { "command": "sudo online-auth check-if-blocked", "description": "Ask the server whether this device or user is blocked", "expectedOutput": "Blocked: false (or the block reason when the account is blocked)" }, { "command": "sudo online-auth check-all-status", "description": "One-shot summary: login state, group, heartbeat and block status", "expectedOutput": "A status block with the login state, the user group, the heartbeat state and the block flag", "notes": "This is the call the dashboard makes to paint the auth indicator." } ], "id": "1_authentication_management", "title": "Authentication Management" }, { "description": "Identity and account information", "examples": [ { "command": "sudo online-auth get-ids", "description": "Show user and session IDs", "expectedOutput": "User ID and session ID displayed" }, { "command": "sudo online-auth get-ids --json", "description": "Get IDs in JSON format", "expectedOutput": "JSON with user and session IDs" }, { "command": "sudo online-auth which-group", "description": "Check user group (VIP = premium)", "expectedOutput": "User group displayed" }, { "command": "sudo online-auth get-card", "description": "Get user card URL", "expectedOutput": "User card URL displayed" } ], "id": "2_user_information", "title": "User Information" }, { "description": "Session keepalive and heartbeat operations", "examples": [ { "command": "sudo online-auth send-heartbeat", "description": "Send a single heartbeat", "expectedOutput": "Heartbeat sent successfully" }, { "command": "sudo online-auth send-heartbeat-with-retry", "description": "Send heartbeat with retry logic", "expectedOutput": "Heartbeat sent with retry if needed" }, { "command": "sudo online-auth start-heartbeat", "description": "Start automatic heartbeat service", "expectedOutput": "Heartbeat service started" }, { "command": "sudo online-auth stop-heartbeat", "description": "Stop automatic heartbeat service", "expectedOutput": "Heartbeat service stopped" }, { "command": "sudo online-auth check-heartbeat", "description": "Check if heartbeat service is running", "expectedOutput": "Heartbeat service status displayed" } ], "id": "3_heartbeat_management", "title": "Heartbeat Management" }, { "description": "Control permission guard daemon for file permission monitoring", "examples": [ { "command": "sudo online-auth enable-permission-guard", "description": "Start permission guard daemon to monitor file permissions", "expectedOutput": "Permission guard daemon enabled successfully", "notes": "Ensures files maintain correct ownership and prevents root-owned files in user directories" }, { "command": "sudo online-auth disable-permission-guard", "description": "Stop permission guard daemon", "expectedOutput": "Permission guard daemon disabled successfully", "notes": "Stops automatic permission monitoring and correction" }, { "command": "sudo online-auth permission-guard-status", "description": "Check if permission guard daemon is running", "expectedOutput": "Permission guard daemon is running/not running" }, { "command": "sudo online-auth enable-permission-guard --json", "description": "Enable permission guard with JSON output", "expectedOutput": "{\"status\": \"success\", \"message\": \"Permission guard daemon enabled\", \"is_running\": true}", "notes": "Useful for automation scripts and monitoring" }, { "command": "sudo online-auth permission-guard-status --json", "description": "Get permission guard status in JSON format", "expectedOutput": "{\"status\": \"success\", \"message\": \"Permission guard daemon is running\", \"is_running\": true}" } ], "id": "4_permission_guard", "title": "Permission Guard Management" }, { "description": "API key synchronization and management", "examples": [ { "command": "sudo online-auth sync-api-key", "description": "Manually sync API key with server", "expectedOutput": "API key synchronized successfully" }, { "command": "sudo online-auth sync-api-key --json", "description": "Sync API key with JSON output", "expectedOutput": "JSON response with sync status" } ], "id": "5_api_management", "title": "API Management" }, { "description": "Version and program details", "examples": [ { "command": "online-auth --version", "description": "Show version number", "expectedOutput": "online-auth version <VERSION>" }, { "command": "online-auth --info", "description": "Show detailed program information", "expectedOutput": "Detailed information about online-auth" }, { "command": "online-auth --help", "description": "Show help information", "expectedOutput": "Help text with all commands" }, { "command": "online-auth --examples", "description": "Show usage examples", "expectedOutput": "This examples output" } ], "id": "6_program_information", "title": "Program Information" }, { "description": "Complete authentication workflows", "examples": [ { "command": "sudo online-auth authenticate && sudo online-auth which-group", "description": "Authenticate and check group", "expectedOutput": "Authentication followed by group info", "notes": "Useful for setup scripts" }, { "command": "sudo online-auth authenticate --keep-alive && sudo online-auth get-card", "description": "Auth with heartbeat and get card", "expectedOutput": "Authentication with heartbeat, then card URL" }, { "command": "sudo online-auth check-login || sudo online-auth authenticate", "description": "Check login or authenticate if needed", "expectedOutput": "Login status or authentication", "notes": "Ensures authenticated state" } ], "id": "7_workflow_combinations", "title": "Workflow Combinations" }, { "description": "Debug and error resolution", "examples": [ { "command": "sudo online-auth check-login --json", "description": "Check connection status", "expectedOutput": "JSON with detailed connection info" }, { "command": "sudo online-auth sync-api-key", "description": "Refresh API credentials", "expectedOutput": "API key refreshed", "notes": "Use when authentication fails" }, { "command": "sudo online-auth logout && sudo online-auth authenticate", "description": "Reset authentication", "expectedOutput": "Fresh authentication session" }, { "command": "sudo online-auth stop-heartbeat && sudo online-auth start-heartbeat", "description": "Restart heartbeat service", "expectedOutput": "Heartbeat service restarted" } ], "id": "8_troubleshooting", "title": "Troubleshooting" }, { "description": "Session behaviour flags. online-auth takes its endpoint, timeout and retry policy from the embedded config, so the cli-core globals --timeout, --port and --log-level are accepted for interface consistency but online-auth does not act on them. The global --retry option is not exposed; send-heartbeat-with-retry uses its built-in policy. The flags below do change what it does.", "examples": [ { "command": "sudo online-auth authenticate --relogin --json", "description": "Log in the way the dashboard does: keep-alive plus automatic re-login when the session expires", "expectedOutput": "Success envelope; a relogin_state.json marker is written to the tmp directory and the heartbeat service starts", "notes": "--relogin implies --keep-alive, so passing both is redundant but harmless." }, { "command": "sudo online-auth send-heartbeat-with-retry --json", "description": "Send one heartbeat with the built-in retry policy instead of failing on the first network hiccup", "expectedOutput": "Success envelope once a heartbeat lands, or an error envelope after the retries are exhausted", "notes": "The retry policy is internal to this command; there is no global --retry option." } ], "id": "9_advanced_options", "title": "Advanced Options" }, { "description": "Working with JSON formatted responses", "examples": [ { "command": "sudo online-auth authenticate --json | jq '.status'", "description": "Extract status from JSON", "expectedOutput": "\"success\" or \"error\"" }, { "command": "sudo online-auth get-ids --json | jq '.data.anon_secure_hash_id'", "description": "Extract the anonymous secure hash ID from JSON (sensitive value)", "expectedOutput": "Anonymous secure hash ID value (sensitive: treat like a secret, do not log or share)" }, { "command": "sudo online-auth check-all-status --json | jq '.data'", "description": "Get all status data as JSON", "expectedOutput": "The complete status object (login state, group, heartbeat, block flag)", "notes": "Useful for monitoring scripts" }, { "command": "sudo online-auth license-status --json-pretty", "description": "Read the license envelope indented, without piping it through jq", "expectedOutput": "Indented JSON envelope with the license tier, device count and expiry" }, { "command": "sudo online-auth permission-guard-status --json-human", "description": "Colorized, jq-style JSON for reading at a terminal", "expectedOutput": "Highlighted JSON envelope with is_running and the daemon message", "notes": "--json-human implies JSON mode. Use --json, not --json-human, when piping to a parser." } ], "id": "10_json_output", "title": "JSON Output" }, { "description": "License activation, status, and transfer operations", "examples": [ { "command": "sudo online-auth activate-license --key \"H7KM-P2Q9-R5TW-X3YZ-A4B2\"", "description": "Activate a license key for premium features", "expectedOutput": "License activated with tier and feature details", "notes": "Key format: XXXX-XXXX-XXXX-XXXX-XXXX (24 chars with dashes)" }, { "command": "sudo online-auth activate-license -k \"H7KM-P2Q9-R5TW-X3YZ-A4B2\" --json", "description": "Activate license with JSON output", "expectedOutput": "JSON response with license details, tier, and features" }, { "command": "sudo online-auth license-status", "description": "Check current license status and details", "expectedOutput": "License tier, version, devices used, and expiry info" }, { "command": "sudo online-auth license-status --json", "description": "Get license status in JSON format", "expectedOutput": "JSON formatted license information", "notes": "Useful for scripting and automation" }, { "command": "sudo online-auth release-license", "description": "Release license to transfer to another device", "expectedOutput": "License released, can be activated on new device", "notes": "Use when moving to new hardware or reinstalling" }, { "command": "sudo online-auth release-license --json", "description": "Release license with JSON confirmation", "expectedOutput": "JSON confirmation of license release" }, { "command": "sudo online-auth license-status --json | jq -r '.admin_messages[0].id'", "description": "Read the ID of the admin message currently shown on this device", "expectedOutput": "A UUID such as 3f2a91c4-77b8-4d0e-9a11-6c5f0d2e8b31, or 'null' when there is no pending message", "notes": "license-status prints the license object directly, not a result envelope, so the jq path is .admin_messages, not .data.admin_messages. It reports admin messages even on an unlicensed device." }, { "command": "sudo online-auth dismiss-message --message-id \"3f2a91c4-77b8-4d0e-9a11-6c5f0d2e8b31\"", "description": "Dismiss an admin popup message so the server stops sending it to this device", "expectedOutput": "Message dismissed (the dismissal is recorded server-side for this hardware ID)", "notes": "--message-id (-m) is required and must be the UUID from license-status admin_messages[].id. The dismissal is per device, not per user." } ], "id": "11_license_management", "title": "License Management" } ], "description": "Usage examples for online-auth", "name": "online-auth", "quickReference": [ "online-auth --help", "online-auth --version", "online-auth --info --json", "online-auth --examples --json", "sudo online-auth authenticate --relogin", "sudo online-auth check-all-status --json", "sudo online-auth check-login", "sudo online-auth logout", "sudo online-auth license-status", "sudo online-auth permission-guard-status" ] }, "errors": [], "metadata": { "executionTime": 4, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:38.682207198Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "tor-switch", "path": "/opt/kodachi/dashboard/hooks/tor-switch", "timestamp": "2026-07-21T01:54:39Z", "file_info": { "size": 8791552, "sha256": "fdfa00e5ac409838b016d7a66d7aeb1fa249e502e2a44431002b6ce077ef3ae8" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Tor configuration and routing management for Kodachi OS", "features": [ "Tor network management and configuration", "Multi-instance Tor support", "Exit node rotation and control", "DNS leak prevention integration", "Firewall rule management", "HAProxy configuration for load balancing", "Authentication and security verification", "Comprehensive logging and monitoring" ], "license": "Proprietary", "name": "tor-switch", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 12, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.210811538Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "tor-switch", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 14, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.324485768Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Basic Operations", "commands": [ { "description": "Start Tor daemon", "examples": [ "sudo tor-switch start-tor" ], "name": "start-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch start-tor [OPTIONS]" }, { "description": "Stop Tor daemon", "examples": [ "sudo tor-switch stop-tor" ], "name": "stop-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch stop-tor [OPTIONS]" }, { "description": "Restart Tor daemon", "examples": [ "sudo tor-switch restart-tor" ], "name": "restart-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch restart-tor [OPTIONS]" } ] }, { "category": "Bridge Management", "commands": [ { "description": "Store obfs4 bridge lines and activate bridge mode for all instances", "examples": [ "sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'", "sudo tor-switch set-bridges --from-file /tmp/bridges.txt" ], "name": "set-bridges", "options": [ { "description": "An obfs4 bridge line (repeatable)", "flag": "-b, --bridge <LINE>", "required": false }, { "description": "Read bridge lines from a file (blank lines and # comments ignored)", "flag": "--from-file <PATH>", "required": false }, { "default": "obfs4", "description": "Pluggable transport type (default: obfs4)", "flag": "--transport <TRANSPORT>", "required": false }, { "description": "Output in JSON format", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-bridges [OPTIONS]" }, { "description": "Enable stored bridges for all instances and restart them", "examples": [ "sudo tor-switch enable-bridges" ], "name": "enable-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch enable-bridges [OPTIONS]" }, { "description": "Disable bridges (revert to direct Tor) and restart all instances", "examples": [ "sudo tor-switch disable-bridges" ], "name": "disable-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch disable-bridges [OPTIONS]" }, { "description": "List stored bridge configuration and detected obfs4proxy path", "examples": [ "tor-switch list-bridges --json" ], "name": "list-bridges", "options": [], "requires_sudo": false, "usage": "tor-switch list-bridges [OPTIONS]" }, { "description": "Remove all stored bridges, disable bridge mode, and restart instances", "examples": [ "sudo tor-switch clear-bridges" ], "name": "clear-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch clear-bridges [OPTIONS]" }, { "description": "Validate stored bridge lines and report obfs4proxy availability (read-only)", "examples": [ "tor-switch test-bridges --json" ], "name": "test-bridges", "options": [], "requires_sudo": false, "usage": "tor-switch test-bridges [OPTIONS]" }, { "description": "Set bridge selection mode: 'all' uses every bridge, 'random' picks a random subset each rotation", "examples": [ "sudo tor-switch set-bridge-mode --mode all", "sudo tor-switch set-bridge-mode --mode random --count 2" ], "name": "set-bridge-mode", "options": [ { "description": "Selection mode: all or random", "flag": "-m, --mode <MODE>", "required": true }, { "description": "Number of bridges to activate in random mode (>= 1)", "flag": "--count <N>", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-bridge-mode [OPTIONS]" }, { "description": "Re-apply bridge config to all instances (picks a fresh random subset in random mode)", "examples": [ "sudo tor-switch rotate-bridges" ], "name": "rotate-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch rotate-bridges [OPTIONS]" }, { "description": "Install a cron job that rotates bridges on the given interval (e.g. 15m, 1h)", "examples": [ "sudo tor-switch bridge-rotate-timer 15m" ], "name": "bridge-rotate-timer", "options": [ { "description": "Rotation interval (e.g. 15m, 1h, 30s)", "flag": "<INTERVAL>", "required": true } ], "requires_sudo": true, "usage": "tor-switch bridge-rotate-timer [OPTIONS]" }, { "description": "Remove the bridge rotation cron job", "examples": [ "sudo tor-switch stop-bridge-rotate-timer" ], "name": "stop-bridge-rotate-timer", "options": [], "requires_sudo": true, "usage": "tor-switch stop-bridge-rotate-timer [OPTIONS]" } ] }, { "category": "Configuration", "commands": [ { "description": "Validate torrc configuration", "examples": [ "tor-switch validate-torrc" ], "name": "validate-torrc", "options": [], "requires_sudo": false, "usage": "tor-switch validate-torrc [OPTIONS]" }, { "description": "Reload Tor configuration", "examples": [ "sudo tor-switch reload-tor-config" ], "name": "reload-tor-config", "options": [], "requires_sudo": true, "usage": "tor-switch reload-tor-config [OPTIONS]" }, { "description": "Reload config for all instances", "examples": [ "sudo tor-switch reload-tor-config-all" ], "name": "reload-tor-config-all", "options": [], "requires_sudo": true, "usage": "tor-switch reload-tor-config-all [OPTIONS]" }, { "description": "Backup configuration", "examples": [ "sudo tor-switch backup-config" ], "name": "backup-config", "options": [], "requires_sudo": true, "usage": "tor-switch backup-config [OPTIONS]" }, { "description": "Backup all configurations", "examples": [ "sudo tor-switch backup-config-all" ], "name": "backup-config-all", "options": [], "requires_sudo": true, "usage": "tor-switch backup-config-all [OPTIONS]" }, { "description": "Restore configuration", "examples": [ "sudo tor-switch restore-config backup-2025-01-28" ], "name": "restore-config", "options": [ { "description": "Backup name to restore (e.g., backup-2025-01-28)", "flag": "<BACKUP_NAME>", "required": true }, { "description": "Target instance (optional)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch restore-config [OPTIONS]" }, { "description": "Restore all configurations", "examples": [ "sudo tor-switch restore-config-all backup-2025-01-28" ], "name": "restore-config-all", "options": [ { "description": "Backup name to restore (e.g., backup-2025-01-28)", "flag": "<BACKUP_NAME>", "required": true } ], "requires_sudo": true, "usage": "tor-switch restore-config-all [OPTIONS]" }, { "description": "List configuration backups", "examples": [ "tor-switch list-backups" ], "name": "list-backups", "options": [], "requires_sudo": false, "usage": "tor-switch list-backups [OPTIONS]" }, { "description": "Generate new Tor control password", "examples": [ "sudo tor-switch generate-new-tor-password" ], "name": "generate-new-tor-password", "options": [], "requires_sudo": true, "usage": "tor-switch generate-new-tor-password [OPTIONS]" }, { "description": "Generate password for all instances", "examples": [ "sudo tor-switch generate-new-tor-password-all" ], "name": "generate-new-tor-password-all", "options": [], "requires_sudo": true, "usage": "tor-switch generate-new-tor-password-all [OPTIONS]" }, { "description": "Clean custom torrc file", "examples": [ "sudo tor-switch clean-torrc-custom" ], "name": "clean-torrc-custom", "options": [], "requires_sudo": true, "usage": "tor-switch clean-torrc-custom [OPTIONS]" }, { "description": "Clean custom torrc for all instances", "examples": [ "sudo tor-switch clean-torrc-custom-all" ], "name": "clean-torrc-custom-all", "options": [], "requires_sudo": true, "usage": "tor-switch clean-torrc-custom-all [OPTIONS]" } ] }, { "category": "DNS Management", "commands": [ { "description": "Start Tor DNS with iptables", "examples": [ "sudo tor-switch start-tor-dns-iptables" ], "name": "start-tor-dns-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch start-tor-dns-iptables [OPTIONS]" }, { "description": "Start Tor DNS with nftables", "examples": [ "sudo tor-switch start-tor-dns-nftables" ], "name": "start-tor-dns-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch start-tor-dns-nftables [OPTIONS]" }, { "description": "Stop Tor DNS iptables", "examples": [ "sudo tor-switch stop-tor-dns-iptables" ], "name": "stop-tor-dns-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch stop-tor-dns-iptables [OPTIONS]" }, { "description": "Stop Tor DNS nftables", "examples": [ "sudo tor-switch stop-tor-dns-nftables" ], "name": "stop-tor-dns-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch stop-tor-dns-nftables [OPTIONS]" }, { "description": "Route DNS through Tor (auto-detects the active firewall). DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-dns" ], "name": "torrify-system-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-dns [OPTIONS]" }, { "description": "Route DNS through Tor with iptables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables-dns" ], "name": "torrify-system-iptables-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables-dns [OPTIONS]" }, { "description": "Route DNS through Tor with nftables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables-dns" ], "name": "torrify-system-nftables-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables-dns [OPTIONS]" }, { "description": "Verify Tor DNS resolution", "examples": [ "tor-switch verify-tor-dns", "tor-switch verify-tor-dns --json" ], "name": "verify-tor-dns", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns [OPTIONS]" }, { "description": "Verify DNS for all instances", "examples": [ "tor-switch verify-tor-dns-all" ], "name": "verify-tor-dns-all", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-all [OPTIONS]" }, { "description": "Direct Tor DNS verification", "examples": [ "tor-switch verify-tor-dns-direct" ], "name": "verify-tor-dns-direct", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-direct [OPTIONS]" }, { "description": "Verify Tor DNS port", "examples": [ "tor-switch verify-tor-dns-port" ], "name": "verify-tor-dns-port", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-port [OPTIONS]" } ] }, { "category": "Exit Node Control", "commands": [ { "description": "Set Tor exit node", "examples": [ "sudo tor-switch set-exit-node us", "sudo tor-switch set-exit-node gb --instance secondary", "sudo tor-switch set-exit-node de --instance streaming", "sudo tor-switch set-exit-node ch --instance secure", "sudo tor-switch set-exit-node random", "sudo tor-switch set-exit-node all-world", "sudo tor-switch set-exit-node random-europe", "sudo tor-switch set-exit-node random-asia", "sudo tor-switch set-exit-node random-africa", "sudo tor-switch set-exit-node random-north-america", "sudo tor-switch set-exit-node random-south-america", "sudo tor-switch set-exit-node random-oceania", "sudo tor-switch set-exit-node random-middle-east", "sudo tor-switch set-exit-node random-5eyes", "sudo tor-switch set-exit-node random-9eyes", "sudo tor-switch set-exit-node random-14eyes", "sudo tor-switch set-exit-node random-high-volume", "sudo tor-switch set-exit-node random-low-volume", "sudo tor-switch set-exit-node europe", "sudo tor-switch set-exit-node asia", "sudo tor-switch set-exit-node africa", "sudo tor-switch set-exit-node north-america", "sudo tor-switch set-exit-node south-america", "sudo tor-switch set-exit-node oceania", "sudo tor-switch set-exit-node middle-east", "sudo tor-switch set-exit-node 5eyes", "sudo tor-switch set-exit-node 9eyes", "sudo tor-switch set-exit-node 14eyes", "sudo tor-switch set-exit-node high-volume", "sudo tor-switch set-exit-node low-volume", "sudo tor-switch set-exit-node europe --instance europe", "sudo tor-switch set-exit-node asia --instance asia", "sudo tor-switch set-exit-node north-america --instance americas", "sudo tor-switch set-exit-node random-low-volume --instance research", "sudo tor-switch set-exit-node high-volume --instance testing" ], "name": "set-exit-node", "options": [ { "description": "2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random-<group> such as random-europe", "flag": "<NODE>", "required": true }, { "description": "Target instance (optional)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exit-node [OPTIONS]" }, { "description": "Set exit node for all instances", "examples": [ "sudo tor-switch set-exit-node-all ca" ], "name": "set-exit-node-all", "options": [ { "description": "2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random-<group> such as random-europe", "flag": "<NODE>", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-exit-node-all [OPTIONS]" }, { "description": "Set excluded nodes", "examples": [ "sudo tor-switch set-exclude-node cn,ru,ir", "sudo tor-switch set-exclude-node 5eyes", "sudo tor-switch set-exclude-node 9eyes", "sudo tor-switch set-exclude-node 14eyes", "sudo tor-switch set-exclude-node europe", "sudo tor-switch set-exclude-node asia", "sudo tor-switch set-exclude-node north-america", "sudo tor-switch set-exclude-node high-volume", "sudo tor-switch set-exclude-node low-volume", "sudo tor-switch set-exclude-node random-high-volume", "sudo tor-switch set-exclude-node random-low-volume", "sudo tor-switch set-exclude-node asia --instance secure", "sudo tor-switch set-exclude-node 14eyes --instance privacy-1", "sudo tor-switch set-exclude-node 5eyes --instance privacy-1", "sudo tor-switch set-exclude-node 9eyes --instance privacy-2", "sudo tor-switch set-exclude-node 14eyes --instance privacy-3" ], "name": "set-exclude-node", "options": [ { "description": "Comma-separated country codes to exclude (cn,ru,ir) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random-<group> such as random-14eyes", "flag": "<NODE>", "required": true }, { "description": "Target instance (optional)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node [OPTIONS]" }, { "description": "Set excluded nodes for all instances", "examples": [ "sudo tor-switch set-exclude-node-all fr" ], "name": "set-exclude-node-all", "options": [ { "description": "Comma-separated country codes to exclude (cn,ru,ir) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random-<group> such as random-14eyes", "flag": "<NODE>", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node-all [OPTIONS]" }, { "description": "Clear exit node restrictions", "examples": [ "sudo tor-switch clear-exit-node" ], "name": "clear-exit-node", "options": [ { "description": "Target instance (optional, defaults to default instance)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exit-node [OPTIONS]" }, { "description": "Clear exit node for all instances", "examples": [ "sudo tor-switch clear-exit-node-all" ], "name": "clear-exit-node-all", "options": [], "requires_sudo": true, "usage": "tor-switch clear-exit-node-all [OPTIONS]" }, { "description": "Clear excluded nodes for all instances", "examples": [ "sudo tor-switch clear-exclude-node-all" ], "name": "clear-exclude-node-all", "options": [], "requires_sudo": true, "usage": "tor-switch clear-exclude-node-all [OPTIONS]" }, { "description": "Create new Tor circuit", "examples": [ "sudo tor-switch new-tor-circuit" ], "name": "new-tor-circuit", "options": [ { "description": "Target instance (optional, defaults to default instance)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch new-tor-circuit [OPTIONS]" }, { "description": "New circuit for all instances", "examples": [ "sudo tor-switch new-tor-circuit-all" ], "name": "new-tor-circuit-all", "options": [], "requires_sudo": true, "usage": "tor-switch new-tor-circuit-all [OPTIONS]" } ] }, { "category": "Firewall", "commands": [ { "description": "Flush iptables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt", "examples": [ "sudo tor-switch flush-iptables" ], "name": "flush-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch flush-iptables [OPTIONS]" }, { "description": "Flush nftables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt", "examples": [ "sudo tor-switch flush-nftables" ], "name": "flush-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch flush-nftables [OPTIONS]" }, { "description": "List iptables rules", "examples": [ "sudo tor-switch list-iptables" ], "name": "list-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch list-iptables [OPTIONS]" }, { "description": "List iptables NAT rules", "examples": [ "sudo tor-switch list-iptables-nat" ], "name": "list-iptables-nat", "options": [], "requires_sudo": true, "usage": "tor-switch list-iptables-nat [OPTIONS]" }, { "description": "List nftables rules", "examples": [ "sudo tor-switch list-nftables" ], "name": "list-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch list-nftables [OPTIONS]" } ] }, { "category": "HAProxy", "commands": [ { "description": "Generate HAProxy configuration", "examples": [ "sudo tor-switch generate-haproxy-config roundrobin 9055", "sudo tor-switch generate-haproxy-config source 8080", "sudo tor-switch generate-haproxy-config leastconn 9000", "sudo tor-switch generate-haproxy-config random 8888", "sudo tor-switch generate-haproxy-config" ], "name": "generate-haproxy-config", "options": [ { "description": "Load balancing mode (roundrobin, source, random, leastconn, first)", "flag": "<MODE>", "required": false }, { "description": "Bind port (default: 9055)", "flag": "<PORT>", "required": false }, { "description": "Output file path (default: /etc/haproxy/tor-haproxy.cfg)", "flag": "<OUTPUT>", "required": false }, { "description": "Maximum connections (default: 4096)", "flag": "<MAXCONN>", "required": false } ], "requires_sudo": true, "usage": "tor-switch generate-haproxy-config [OPTIONS]" }, { "description": "Start HAProxy service", "examples": [ "sudo tor-switch haproxy-start" ], "name": "haproxy-start", "options": [], "requires_sudo": true, "usage": "tor-switch haproxy-start [OPTIONS]" }, { "description": "Stop HAProxy service", "examples": [ "sudo tor-switch haproxy-stop" ], "name": "haproxy-stop", "options": [], "requires_sudo": true, "usage": "tor-switch haproxy-stop [OPTIONS]" }, { "description": "Check HAProxy status", "examples": [ "tor-switch haproxy-status" ], "name": "haproxy-status", "options": [], "requires_sudo": false, "usage": "tor-switch haproxy-status [OPTIONS]" }, { "description": "List HAProxy load balancing modes", "examples": [ "tor-switch list-haproxy-modes" ], "name": "list-haproxy-modes", "options": [], "requires_sudo": false, "usage": "tor-switch list-haproxy-modes [OPTIONS]" }, { "description": "Display load balancing configuration", "examples": [ "tor-switch display-load-balancing-config" ], "name": "display-load-balancing-config", "options": [], "requires_sudo": false, "usage": "tor-switch display-load-balancing-config [OPTIONS]" } ] }, { "category": "Help", "commands": [ { "description": "Show help information", "examples": [ "tor-switch show-help" ], "name": "show-help", "options": [], "requires_sudo": false, "usage": "tor-switch show-help [OPTIONS]" }, { "description": "Show usage examples", "examples": [ "tor-switch show-examples" ], "name": "show-examples", "options": [], "requires_sudo": false, "usage": "tor-switch show-examples [OPTIONS]" } ] }, { "category": "Instance Management", "commands": [ { "description": "Create new Tor instance", "examples": [ "sudo tor-switch create-instance secondary", "sudo tor-switch create-instance europe", "sudo tor-switch create-instance asia", "sudo tor-switch create-instance americas", "sudo tor-switch create-instance research", "sudo tor-switch create-instance testing" ], "name": "create-instance", "options": [ { "description": "Instance name", "flag": "<NAME>", "required": true } ], "requires_sudo": true, "usage": "tor-switch create-instance [OPTIONS]" }, { "description": "Delete Tor instance", "examples": [ "sudo tor-switch delete-instance secondary" ], "name": "delete-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch delete-instance [OPTIONS]" }, { "description": "Delete all Tor instances", "examples": [ "sudo tor-switch delete-all-instances" ], "name": "delete-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch delete-all-instances [OPTIONS]" }, { "description": "Delete all instances including default", "examples": [ "sudo tor-switch delete-all-instances-with-default" ], "name": "delete-all-instances-with-default", "options": [], "requires_sudo": true, "usage": "tor-switch delete-all-instances-with-default [OPTIONS]" }, { "description": "Start a Tor instance", "examples": [ "sudo tor-switch start-instance secondary" ], "name": "start-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch start-instance [OPTIONS]" }, { "description": "Stop a Tor instance", "examples": [ "sudo tor-switch stop-instance secondary" ], "name": "stop-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch stop-instance [OPTIONS]" }, { "description": "Restart a Tor instance", "examples": [ "sudo tor-switch restart-instance secondary" ], "name": "restart-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch restart-instance [OPTIONS]" }, { "description": "Start all Tor instances", "examples": [ "sudo tor-switch start-all-instances" ], "name": "start-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch start-all-instances [OPTIONS]" }, { "description": "Stop all Tor instances", "examples": [ "sudo tor-switch stop-all-instances" ], "name": "stop-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch stop-all-instances [OPTIONS]" }, { "description": "Restart all Tor instances", "examples": [ "sudo tor-switch restart-all-instances" ], "name": "restart-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch restart-all-instances [OPTIONS]" }, { "description": "Show instance details", "examples": [ "tor-switch show-instance streaming" ], "name": "show-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": false, "usage": "tor-switch show-instance [OPTIONS]" }, { "description": "Set default Tor instance", "examples": [ "sudo tor-switch set-default-instance performance-0" ], "name": "set-default-instance", "options": [ { "description": "Instance tag/name", "flag": "<TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-default-instance [OPTIONS]" }, { "description": "Rename a Tor instance", "examples": [ "sudo tor-switch rename-instance old-name new-name" ], "name": "rename-instance", "options": [ { "description": "Current instance tag/name", "flag": "<OLD_TAG>", "required": true }, { "description": "New instance tag/name", "flag": "<NEW_TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch rename-instance [OPTIONS]" }, { "description": "Clone a Tor instance", "examples": [ "sudo tor-switch clone-instance main backup" ], "name": "clone-instance", "options": [ { "description": "Source instance tag/name", "flag": "<SOURCE_TAG>", "required": true }, { "description": "Target instance tag/name", "flag": "<TARGET_TAG>", "required": true } ], "requires_sudo": true, "usage": "tor-switch clone-instance [OPTIONS]" }, { "description": "Create multiple Tor instances. If COUNT is omitted, picks the RAM-aware default from instance_sizing::recommended_instance_count (4 GBā†’3, 8 GBā†’5, 16 GBā†’7, 32 GBā†’10, 256 GBā†’20). Passing COUNT is an explicit user override and bypasses the model (still clamped to [floor, cap] for safety).", "examples": [ "sudo tor-switch create-multiple-instances 5", "sudo tor-switch create-multiple-instances 3 performance", "sudo tor-switch create-multiple-instances 10 worker", "sudo tor-switch create-multiple-instances 5 region", "sudo tor-switch create-multiple-instances 3 node", "sudo tor-switch create-multiple-instances 3 privacy", "sudo tor-switch create-multiple-instances 5 ha", "sudo tor-switch create-multiple-instances 10 perf" ], "name": "create-multiple-instances", "options": [ { "description": "Number of instances to create (omit to use RAM-aware default)", "flag": "<COUNT>", "required": false }, { "description": "Optional prefix for instance names", "flag": "<PREFIX>", "required": false } ], "requires_sudo": true, "usage": "tor-switch create-multiple-instances [OPTIONS]" } ] }, { "category": "Load Balancing", "commands": [ { "description": "Set load balancing mode", "examples": [ "sudo tor-switch set-load-balancing-mode round-robin", "sudo tor-switch set-load-balancing-mode weighted", "sudo tor-switch set-load-balancing-mode consistent-hashing" ], "name": "set-load-balancing-mode", "options": [ { "description": "Load balancing mode: round-robin, weighted or consistent-hashing", "flag": "<MODE>", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-load-balancing-mode [OPTIONS]" }, { "description": "Set instance weight for load balancing", "examples": [ "sudo tor-switch set-instance-weight secondary 50", "sudo tor-switch set-instance-weight tor1 50", "sudo tor-switch set-instance-weight tor1 10", "sudo tor-switch set-instance-weight tor2 30", "sudo tor-switch set-instance-weight tor3 60", "sudo tor-switch set-instance-weight performance-0 75", "sudo tor-switch set-instance-weight backup 5", "sudo tor-switch set-instance-weight worker-1 25", "sudo tor-switch set-instance-weight ha-1 30", "sudo tor-switch set-instance-weight ha-2 25", "sudo tor-switch set-instance-weight ha-3 20", "sudo tor-switch set-instance-weight ha-4 15", "sudo tor-switch set-instance-weight ha-5 10" ], "name": "set-instance-weight", "options": [ { "description": "Instance name", "flag": "<INSTANCE>", "required": true }, { "description": "Weight value (1-100)", "flag": "<WEIGHT>", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-instance-weight [OPTIONS]" }, { "description": "Torrify with iptables load balancing. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables-load-balanced" ], "name": "torrify-system-iptables-load-balanced", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables-load-balanced [OPTIONS]" }, { "description": "Torrify with nftables load balancing. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables-load-balanced" ], "name": "torrify-system-nftables-load-balanced", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables-load-balanced [OPTIONS]" }, { "description": "Pre-warm Tor instances and verify circuit readiness without applying firewall rules", "examples": [ "sudo tor-switch prepare-tor" ], "name": "prepare-tor", "options": [], "requires_sudo": true, "usage": "tor-switch prepare-tor [OPTIONS]" } ] }, { "category": "Main Tor Management", "commands": [ { "description": "Validate main Tor configuration", "examples": [ "tor-switch validate-torrc-main --maintor", "tor-switch validate-torrc-main --maintor --json" ], "name": "validate-torrc-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch validate-torrc-main [OPTIONS]" }, { "description": "Display main Tor settings (ports, exit/exclude nodes, security)", "examples": [ "tor-switch read-main-tor-config" ], "name": "read-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch read-main-tor-config [OPTIONS]" }, { "description": "Backup main Tor configuration", "examples": [ "sudo tor-switch backup-main-tor-config" ], "name": "backup-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch backup-main-tor-config [OPTIONS]" }, { "description": "Restore main Tor configuration from backup", "examples": [ "sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup" ], "name": "restore-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false }, { "description": "Backup file name to restore (under backups/main-tor)", "flag": "<VALUE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch restore-main-tor-config [OPTIONS]" }, { "description": "Set exit node for main Tor", "examples": [ "sudo tor-switch set-exit-node-main US --maintor" ], "name": "set-exit-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false }, { "description": "Exit node country code(s), e.g. US or {us},{de}", "flag": "<VALUE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exit-node-main [OPTIONS]" }, { "description": "Clear exit restrictions for main Tor", "examples": [ "sudo tor-switch clear-exit-node-main --maintor" ], "name": "clear-exit-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exit-node-main [OPTIONS]" }, { "description": "Set excluded countries for main Tor", "examples": [ "sudo tor-switch set-exclude-node-main CN,RU --maintor" ], "name": "set-exclude-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false }, { "description": "Country code(s) to exclude, e.g. CN,RU or {cn},{ru}", "flag": "<VALUE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node-main [OPTIONS]" }, { "description": "Clear exclude restrictions for main Tor", "examples": [ "sudo tor-switch clear-exclude-node-main", "sudo tor-switch clear-exclude-node-main --maintor" ], "name": "clear-exclude-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exclude-node-main [OPTIONS]" }, { "description": "Show current exit/exclude settings for main Tor", "examples": [ "tor-switch list-exit-exclude-main" ], "name": "list-exit-exclude-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch list-exit-exclude-main [OPTIONS]" }, { "description": "Reload main Tor configuration (SIGHUP)", "examples": [ "sudo tor-switch reload-main-tor" ], "name": "reload-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch reload-main-tor [OPTIONS]" }, { "description": "Detailed status of main Tor daemon", "examples": [ "tor-switch status-main-tor" ], "name": "status-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch status-main-tor [OPTIONS]" }, { "description": "Verify DNS routing through main Tor", "examples": [ "tor-switch verify-main-tor-dns" ], "name": "verify-main-tor-dns", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch verify-main-tor-dns [OPTIONS]" }, { "description": "Request new circuit for main Tor", "examples": [ "sudo tor-switch new-circuit-main-tor" ], "name": "new-circuit-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch new-circuit-main-tor [OPTIONS]" }, { "description": "Security audit of main Tor config", "examples": [ "tor-switch check-main-tor-security" ], "name": "check-main-tor-security", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch check-main-tor-security [OPTIONS]" }, { "description": "Show bandwidth usage of main Tor", "examples": [ "tor-switch main-tor-bandwidth" ], "name": "main-tor-bandwidth", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-bandwidth [OPTIONS]" }, { "description": "List active connections through main Tor", "examples": [ "tor-switch main-tor-connections" ], "name": "main-tor-connections", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-connections [OPTIONS]" }, { "description": "Display recent main Tor logs", "examples": [ "tor-switch main-tor-logs" ], "name": "main-tor-logs", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance <INSTANCE>", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-logs [OPTIONS]" } ] }, { "category": "Status Operations", "commands": [ { "description": "Check if Tor service is running via systemctl", "examples": [ "tor-switch check-tor" ], "name": "check-tor", "options": [], "requires_sudo": false, "usage": "tor-switch check-tor [OPTIONS]" }, { "description": "Check systemctl status for all Tor instances", "examples": [ "tor-switch check-tor-all" ], "name": "check-tor-all", "options": [], "requires_sudo": false, "usage": "tor-switch check-tor-all [OPTIONS]" }, { "description": "Verify Tor connectivity through network check", "examples": [ "tor-switch torverify", "tor-switch torverify --json-pretty" ], "name": "torverify", "options": [], "requires_sudo": false, "usage": "tor-switch torverify [OPTIONS]" }, { "description": "Get comprehensive Tor service status (PID, memory, uptime)", "examples": [ "tor-switch tor-status", "tor-switch tor-status --json" ], "name": "tor-status", "options": [], "requires_sudo": false, "usage": "tor-switch tor-status [OPTIONS]" }, { "description": "Get comprehensive status for all Tor instances", "examples": [ "tor-switch tor-status-all" ], "name": "tor-status-all", "options": [], "requires_sudo": false, "usage": "tor-switch tor-status-all [OPTIONS]" }, { "description": "Get Tor status information", "examples": [ "tor-switch get-tor-status" ], "name": "get-tor-status", "options": [], "requires_sudo": false, "usage": "tor-switch get-tor-status [OPTIONS]" }, { "description": "Get custom Tor status", "examples": [ "tor-switch get-tor-custom-status" ], "name": "get-tor-custom-status", "options": [], "requires_sudo": false, "usage": "tor-switch get-tor-custom-status [OPTIONS]" }, { "description": "List all Tor instances", "examples": [ "tor-switch list-instances" ], "name": "list-instances", "options": [], "requires_sudo": false, "usage": "tor-switch list-instances [OPTIONS]" }, { "description": "List all Tor instances with IP addresses", "examples": [ "tor-switch list-instances-with-ip" ], "name": "list-instances-with-ip", "options": [], "requires_sudo": false, "usage": "tor-switch list-instances-with-ip [OPTIONS]" }, { "description": "Show RAM-aware recommended Tor LB instance count (square-root model, clamped 3..20). Output includes detected RAM, current user override (if any), and the effective N the binary will use. Other Kodachi components (dashboard, helpers) should query this instead of recomputing (single source of truth).", "examples": [ "tor-switch recommended-instances" ], "name": "recommended-instances", "options": [], "requires_sudo": false, "usage": "tor-switch recommended-instances [OPTIONS]" } ] }, { "category": "System Management", "commands": [ { "description": "Check active firewall system", "examples": [ "tor-switch which-is-active" ], "name": "which-is-active", "options": [], "requires_sudo": false, "usage": "tor-switch which-is-active [OPTIONS]" }, { "description": "Clean up orphaned Tor instances", "examples": [ "sudo tor-switch cleanup" ], "name": "cleanup", "options": [ { "description": "Perform thorough cleanup that will also reset failed systemd units", "flag": "--thorough", "required": false } ], "requires_sudo": true, "usage": "tor-switch cleanup [OPTIONS]" }, { "description": "Clean orphaned services", "examples": [ "sudo tor-switch clean-orphan-services" ], "name": "clean-orphan-services", "options": [], "requires_sudo": true, "usage": "tor-switch clean-orphan-services [OPTIONS]" } ] }, { "category": "System Routing", "commands": [ { "description": "Route all traffic through Tor via iptables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables" ], "name": "torrify-system-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables [OPTIONS]" }, { "description": "Stop routing traffic through Tor via iptables. DESTRUCTIVE: removes Tor protection immediately", "examples": [ "sudo tor-switch detorrify-system-iptables" ], "name": "detorrify-system-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch detorrify-system-iptables [OPTIONS]" }, { "description": "Route all traffic through Tor via nftables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables" ], "name": "torrify-system-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables [OPTIONS]" }, { "description": "Stop routing traffic through Tor via nftables. DESTRUCTIVE: removes Tor protection immediately", "examples": [ "sudo tor-switch detorrify-system-nftables" ], "name": "detorrify-system-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch detorrify-system-nftables [OPTIONS]" }, { "description": "Restore the Tor instance pool at boot when the persisted firewall is torrified (no-op otherwise)", "examples": [ "sudo tor-switch boot-restore-torrified --json" ], "name": "boot-restore-torrified", "options": [], "requires_sudo": true, "usage": "tor-switch boot-restore-torrified [OPTIONS]" } ] }, { "category": "Timer & Automation", "commands": [ { "description": "Enable automatic IP changes", "examples": [ "sudo tor-switch auto-ip-change 10m" ], "name": "auto-ip-change", "options": [ { "description": "Interval for IP changes (e.g., 10m, 1h, 30s)", "flag": "<INTERVAL>", "required": true }, { "description": "Target instance (optional)", "flag": "--instance <INSTANCE>", "required": false } ], "requires_sudo": true, "usage": "tor-switch auto-ip-change [OPTIONS]" }, { "description": "Stop automatic IP changes", "examples": [ "sudo tor-switch stop-auto-ip-change" ], "name": "stop-auto-ip-change", "options": [], "requires_sudo": true, "usage": "tor-switch stop-auto-ip-change [OPTIONS]" }, { "description": "Update IP change timer", "examples": [ "sudo tor-switch update-ip-timer browsing 5m", "sudo tor-switch update-ip-timer worker-1 30m", "sudo tor-switch update-ip-timer streaming 1h", "sudo tor-switch update-ip-timer research 15m", "sudo tor-switch update-ip-timer backup 24h", "sudo tor-switch update-ip-timer privacy-1 5m", "sudo tor-switch update-ip-timer privacy-2 10m", "sudo tor-switch update-ip-timer privacy-3 15m", "sudo tor-switch update-ip-timer research 2m" ], "name": "update-ip-timer", "options": [ { "description": "Instance name", "flag": "<INSTANCE>", "required": true }, { "description": "New interval (e.g., 5m, 1h, 30s)", "flag": "<INTERVAL>", "required": true } ], "requires_sudo": true, "usage": "tor-switch update-ip-timer [OPTIONS]" }, { "description": "Update timer for all instances", "examples": [ "sudo tor-switch update-ip-all-timer 10m", "sudo tor-switch update-ip-all-timer 2h", "sudo tor-switch update-ip-all-timer 15m" ], "name": "update-ip-all-timer", "options": [ { "description": "New interval for all instances (e.g., 10m, 1h)", "flag": "<INTERVAL>", "required": true } ], "requires_sudo": true, "usage": "tor-switch update-ip-all-timer [OPTIONS]" }, { "description": "Remove IP change timer", "examples": [ "sudo tor-switch remove-ip-timer browsing" ], "name": "remove-ip-timer", "options": [ { "description": "Instance name", "flag": "<INSTANCE>", "required": true } ], "requires_sudo": true, "usage": "tor-switch remove-ip-timer [OPTIONS]" }, { "description": "Remove all IP timers", "examples": [ "sudo tor-switch remove-ip-all-timer" ], "name": "remove-ip-all-timer", "options": [], "requires_sudo": true, "usage": "tor-switch remove-ip-all-timer [OPTIONS]" }, { "description": "List all IP change timers", "examples": [ "tor-switch list-ip-timers" ], "name": "list-ip-timers", "options": [], "requires_sudo": false, "usage": "tor-switch list-ip-timers [OPTIONS]" }, { "description": "List auto IP change settings", "examples": [ "tor-switch list-auto-ip-change" ], "name": "list-auto-ip-change", "options": [], "requires_sudo": false, "usage": "tor-switch list-auto-ip-change [OPTIONS]" } ] } ], "description": "Tor configuration and routing management for Kodachi OS", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir <PATH>" }, { "description": "Set custom port number (1024-65535)", "flag": "--port <PORT>" }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level <LEVEL>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config <FILE>" }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout <SECS>" } ], "name": "tor-switch", "usage": "tor-switch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 15, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.454219335Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Essential operations for getting started", "examples": [ { "command": "sudo tor-switch start-tor", "description": "Start Tor daemon", "expectedOutput": "Tor daemon started successfully", "notes": "Requires sudo privileges for system-level operations" }, { "command": "sudo tor-switch stop-tor", "description": "Stop Tor daemon", "expectedOutput": "Tor daemon stopped successfully", "notes": "Gracefully shuts down Tor service" }, { "command": "sudo tor-switch restart-tor", "description": "Restart Tor daemon", "expectedOutput": "Tor daemon restarted successfully", "notes": "Combines stop and start operations" }, { "command": "sudo tor-switch torrify-system-iptables-dns", "description": "Route DNS through Tor using iptables", "expectedOutput": "DNS routing through Tor enabled (iptables)", "notes": "Redirects all system DNS queries to Tor DNS listener" }, { "command": "sudo tor-switch torrify-system-nftables-dns", "description": "Route DNS through Tor using nftables", "expectedOutput": "DNS routing through Tor enabled (nftables)", "notes": "Redirects all system DNS queries to Tor DNS listener" }, { "command": "sudo tor-switch torrify-system-iptables", "description": "Route all traffic through Tor", "expectedOutput": "System traffic routing through Tor enabled", "notes": "All network traffic will be routed through Tor" }, { "command": "sudo tor-switch detorrify-system-iptables", "description": "Stop routing traffic through Tor", "expectedOutput": "System traffic routing through Tor disabled", "notes": "Returns to normal direct internet connection" }, { "command": "sudo tor-switch torrify-system-nftables", "description": "Route all traffic through Tor via nftables", "expectedOutput": "System traffic routing through Tor enabled (nftables)", "notes": "DESTRUCTIVE: rewrites the system firewall and takes effect immediately, with no confirmation prompt. Uses the modern nftables backend. A --force (alias --yes) flag is accepted for compatibility but is not required and changes nothing." }, { "command": "sudo tor-switch detorrify-system-nftables", "description": "Stop routing traffic through Tor via nftables", "expectedOutput": "System traffic routing through Tor disabled (nftables)", "notes": "DESTRUCTIVE: drops the Tor firewall rules and returns you to a normal direct internet connection, with no confirmation prompt. Your traffic is no longer anonymised after this." }, { "command": "tor-switch check-tor", "description": "Check if Tor service is running", "expectedOutput": "Tor is responding/not responding", "notes": "Checks if Tor service is active via systemctl" }, { "command": "tor-switch torverify", "description": "Verify actual Tor connectivity", "expectedOutput": "Shows whether traffic is routed through Tor and displays IP", "notes": "Makes direct HTTP request to check.torproject.org to verify torrification" }, { "command": "sudo tor-switch new-tor-circuit", "description": "Get new Tor circuit/IP", "expectedOutput": "New circuit established with different exit IP", "notes": "Forces new Tor circuit for different exit node" } ], "id": "01_basic_usage", "title": "Basic Usage" }, { "description": "Managing multiple Tor instances for performance", "examples": [ { "command": "sudo tor-switch create-instance secondary", "description": "Create a secondary Tor instance", "expectedOutput": "Instance 'secondary' created successfully", "notes": "Multiple instances provide load balancing and redundancy" }, { "command": "tor-switch list-instances", "description": "List all available instances", "expectedOutput": "Shows all instances with their status" }, { "command": "sudo tor-switch start-instance secondary", "description": "Start specific instance", "expectedOutput": "Instance 'secondary' started" }, { "command": "sudo tor-switch stop-instance secondary", "description": "Stop specific instance", "expectedOutput": "Instance 'secondary' stopped" }, { "command": "sudo tor-switch restart-instance secondary", "description": "Restart specific instance", "expectedOutput": "Instance 'secondary' restarted" }, { "command": "sudo tor-switch restart-all-instances", "description": "Restart all Tor instances", "expectedOutput": "Restarted 5 out of 5 Tor instances" }, { "command": "sudo tor-switch delete-instance secondary", "description": "Delete an instance permanently", "expectedOutput": "Instance 'secondary' deleted", "notes": "This permanently removes the instance configuration" }, { "command": "sudo tor-switch start-all-instances", "description": "Start all configured instances", "expectedOutput": "All Tor instances started" }, { "command": "sudo tor-switch stop-all-instances", "description": "Stop all running instances", "expectedOutput": "All Tor instances stopped" } ], "id": "02_instance_management", "title": "Instance Management" }, { "description": "Create, clone, rename and manage multiple Tor instances", "examples": [ { "command": "sudo tor-switch create-multiple-instances 5", "description": "Create 5 auto-named instances", "expectedOutput": "5 Tor instances created with auto-generated names", "notes": "Useful for load balancing and redundancy" }, { "command": "sudo tor-switch create-multiple-instances 3 performance", "description": "Create 3 instances with 'performance' prefix", "expectedOutput": "3 instances created: performance-0, performance-1, performance-2", "notes": "Creates instances with custom naming prefix" }, { "command": "sudo tor-switch create-multiple-instances 10 worker", "description": "Create 10 worker instances", "expectedOutput": "10 instances created: worker-1 through worker-10", "notes": "Ideal for high-throughput operations" }, { "command": "sudo tor-switch create-multiple-instances 5 region", "description": "Create 5 regional instances", "expectedOutput": "5 instances created: region-1 through region-5", "notes": "Perfect for geographic distribution" }, { "command": "sudo tor-switch create-multiple-instances 3 node", "description": "Create 3 node instances", "expectedOutput": "3 instances created: node-1, node-2, node-3", "notes": "Simple node-based naming" }, { "command": "sudo tor-switch clone-instance main backup", "description": "Clone 'main' instance to 'backup'", "expectedOutput": "Instance 'main' cloned to 'backup' successfully", "notes": "Copies all configuration from source instance" }, { "command": "sudo tor-switch rename-instance old-name new-name", "description": "Rename instance", "expectedOutput": "Instance renamed from 'old-name' to 'new-name'", "notes": "Updates all references and configuration files" }, { "command": "tor-switch list-instances-with-ip", "description": "List all instances with current IP addresses", "expectedOutput": "All instances listed with their current exit IPs", "notes": "Shows both instance names and their current exit IPs" }, { "command": "tor-switch show-instance streaming", "description": "Show detailed information for 'streaming' instance", "expectedOutput": "Detailed configuration and status for 'streaming' instance", "notes": "Shows configuration, status, and current IP information" }, { "command": "sudo tor-switch set-default-instance performance-0", "description": "Set 'performance-0' as the default instance", "expectedOutput": "Default instance set to 'performance-0'", "notes": "Changes which instance is used for default operations" }, { "command": "sudo tor-switch set-instance-weight secondary 50", "description": "Set weight for load balancing", "expectedOutput": "Instance 'secondary' weight set to 50", "notes": "Used for load balancing when multiple instances are active" }, { "command": "sudo tor-switch delete-all-instances", "description": "Delete all instances except default", "expectedOutput": "All non-default instances deleted", "notes": "Preserves default instance for basic functionality" }, { "command": "sudo tor-switch delete-all-instances-with-default", "description": "Delete ALL instances including default", "expectedOutput": "All instances deleted including default", "notes": "WARNING: Removes all instances" } ], "id": "03_advanced_instance_operations", "title": "Advanced Instance Operations" }, { "description": "Checking system status and verifying operations", "examples": [ { "command": "tor-switch tor-status", "description": "Get detailed Tor status", "expectedOutput": "Comprehensive status report of all Tor components" }, { "command": "tor-switch tor-status --json", "description": "Detailed status in JSON format", "expectedOutput": "JSON-formatted status report", "notes": "Machine-readable output for scripts" }, { "command": "tor-switch check-tor-all", "description": "Check Tor status for all instances", "expectedOutput": "Connection status for every configured instance", "notes": "Quick health check across all instances" }, { "command": "tor-switch torverify", "description": "Verify if system traffic is routed through Tor", "expectedOutput": "āœ“ You are connected through Tor\n IP Address: <Tor exit IP>", "notes": "Makes HTTP request to check.torproject.org API to verify torrification" }, { "command": "tor-switch torverify --json-pretty", "description": "Verify Tor connectivity with detailed JSON output", "expectedOutput": "{\n \"command\": \"torverify\",\n \"data\": {\n \"is_tor\": true,\n \"ip_address\": \"<exit IP>\",\n \"method\": \"api\",\n \"message\": \"You are connected through Tor with IP <exit IP>\"\n },\n \"errors\": [],\n \"metadata\": {...},\n \"status\": \"success\",\n \"timestamp\": \"...\",\n \"version\": \"<VERSION>\",\n \"warnings\": []\n}", "notes": "Useful for scripts and automation" }, { "command": "tor-switch tor-status-all", "description": "Get detailed status for all instances", "expectedOutput": "Comprehensive status report for all instances" }, { "command": "tor-switch get-tor-status", "description": "Get Tor daemon status", "expectedOutput": "Current Tor daemon status", "notes": "Quick status check - use tor-status for detailed report" }, { "command": "tor-switch recommended-instances", "description": "Show RAM-aware recommended load-balancing instance count", "expectedOutput": "Detected RAM, current override (if any), and the effective N (clamped 3..20)", "notes": "Read-only single source of truth (square-root model). Other components should query this instead of recomputing" } ], "id": "04_monitoring", "title": "Monitoring & Status" }, { "description": "Debug and resolve common issues", "examples": [ { "command": "sudo tor-switch cleanup", "description": "Clean up orphaned processes", "expectedOutput": "Orphaned instances and services cleaned up", "notes": "Use when experiencing startup issues" }, { "command": "sudo tor-switch cleanup", "description": "Clean orphaned Tor instances and services", "expectedOutput": "Cleanup completed successfully", "notes": "Removes orphaned instances and service files" }, { "command": "sudo tor-switch clean-orphan-services", "description": "Clean orphaned services", "expectedOutput": "Orphaned services removed" }, { "command": "sudo tor-switch new-tor-circuit-all", "description": "New circuits for all instances", "expectedOutput": "All instances have new circuits with different IPs", "notes": "Refreshes exit IPs for all active instances" } ], "id": "05_troubleshooting", "title": "Troubleshooting" }, { "description": "Control and configure Tor exit nodes for geographic routing and privacy. set-exit-node and set-exclude-node accept a 2-letter ISO country code (us, de, ch) or one of these group aliases: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world. Prefix a group with random- (random-europe, random-14eyes, random-low-volume) to pin one randomly chosen country from that group, or use `random` on its own for one random country worldwide.", "examples": [ { "command": "sudo tor-switch set-exit-node us", "description": "Route via United States", "expectedOutput": "Exit node set to United States", "notes": "Affects the default Tor instance. Traffic will exit through US-based Tor nodes" }, { "command": "sudo tor-switch set-exit-node gb --instance secondary", "description": "Set UK exit for specific instance", "expectedOutput": "Exit node set to United Kingdom for 'secondary'", "notes": "Instance-specific exit node configuration" }, { "command": "sudo tor-switch set-exit-node de --instance streaming", "description": "Set Germany exit for streaming instance", "expectedOutput": "Exit node set to Germany for 'streaming'", "notes": "Useful for geo-restricted content" }, { "command": "sudo tor-switch set-exit-node ch --instance secure", "description": "Set Switzerland exit for secure instance", "expectedOutput": "Exit node set to Switzerland for 'secure'", "notes": "Privacy-friendly jurisdiction" }, { "command": "sudo tor-switch set-exit-node random", "description": "Random exit node selection", "expectedOutput": "Exit node set to random selection", "notes": "Maximum anonymity through randomization" }, { "command": "sudo tor-switch set-exit-node all-world", "description": "Allow exit nodes from every country in the country-group table", "expectedOutput": "ExitNodes set to the full all-world country list", "notes": "Widest possible exit set. Unlike `random`, which pins one randomly chosen country, this lets Tor pick freely from every country." }, { "command": "sudo tor-switch set-exit-node random-europe", "description": "Random European exit node", "expectedOutput": "Exit node set to random European country", "notes": "Stay within European jurisdiction" }, { "command": "sudo tor-switch set-exit-node random-asia", "description": "Random Asian exit node", "expectedOutput": "Exit node set to random Asian country", "notes": "Exit through Asian infrastructure" }, { "command": "sudo tor-switch set-exit-node random-africa", "description": "Random African exit node", "expectedOutput": "Exit node set to random African country", "notes": "Exit through African networks" }, { "command": "sudo tor-switch set-exit-node random-north-america", "description": "Random North American exit", "expectedOutput": "Exit node set to random North American country", "notes": "US, Canada, or Mexico exit" }, { "command": "sudo tor-switch set-exit-node random-south-america", "description": "Random South American exit", "expectedOutput": "Exit node set to random South American country", "notes": "Latin American exit points" }, { "command": "sudo tor-switch set-exit-node random-oceania", "description": "Random Oceania exit node", "expectedOutput": "Exit node set to random Oceania country", "notes": "Australia, NZ, or Pacific islands" }, { "command": "sudo tor-switch set-exit-node random-middle-east", "description": "Random Middle Eastern exit", "expectedOutput": "Exit node set to random Middle Eastern country", "notes": "Middle Eastern exit points" }, { "command": "sudo tor-switch set-exit-node random-5eyes", "description": "Random Five Eyes exit", "expectedOutput": "Exit node set to random Five Eyes country", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exit-node random-9eyes", "description": "Random Nine Eyes exit", "expectedOutput": "Exit node set to random Nine Eyes country", "notes": "5eyes + DK, FR, NL, NO" }, { "command": "sudo tor-switch set-exit-node random-14eyes", "description": "Random Fourteen Eyes exit", "expectedOutput": "Exit node set to random Fourteen Eyes country", "notes": "9eyes + DE, BE, IT, ES, SE" }, { "command": "sudo tor-switch set-exit-node random-high-volume", "description": "Random high-traffic exit", "expectedOutput": "Exit node set to random high-volume country", "notes": "Better performance and anonymity" }, { "command": "sudo tor-switch set-exit-node random-low-volume", "description": "Random low-traffic exit", "expectedOutput": "Exit node set to random low-volume country", "notes": "Less common exit points" }, { "command": "sudo tor-switch set-exit-node europe", "description": "Route through any European country", "expectedOutput": "Exit node set to Europe region", "notes": "Countries: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA" }, { "command": "sudo tor-switch set-exit-node asia", "description": "Route through any Asian country", "expectedOutput": "Exit node set to Asia region", "notes": "Countries: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN" }, { "command": "sudo tor-switch set-exit-node africa", "description": "Route through any African country", "expectedOutput": "Exit node set to Africa region", "notes": "Countries: EG, KE, MA, NG, SC, TN, ZA" }, { "command": "sudo tor-switch set-exit-node north-america", "description": "Route through North America", "expectedOutput": "Exit node set to North America region", "notes": "US, Canada, or Mexico" }, { "command": "sudo tor-switch set-exit-node south-america", "description": "Route through South America", "expectedOutput": "Exit node set to South America region", "notes": "Countries: AR, BR, CL, CO, PE, UY, VE" }, { "command": "sudo tor-switch set-exit-node oceania", "description": "Route through Oceania", "expectedOutput": "Exit node set to Oceania region", "notes": "Countries: AU, NZ" }, { "command": "sudo tor-switch set-exit-node middle-east", "description": "Route through Middle East", "expectedOutput": "Exit node set to Middle East region", "notes": "Countries: AE, IL, IR, LB, OM, QA, SA, TR" }, { "command": "sudo tor-switch set-exit-node 5eyes", "description": "Use Five Eyes countries", "expectedOutput": "Exit node set to Five Eyes alliance", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exit-node 9eyes", "description": "Use Nine Eyes countries", "expectedOutput": "Exit node set to Nine Eyes alliance", "notes": "5eyes + Denmark, France, Netherlands, Norway" }, { "command": "sudo tor-switch set-exit-node 14eyes", "description": "Use Fourteen Eyes countries", "expectedOutput": "Exit node set to Fourteen Eyes alliance", "notes": "9eyes + Germany, Belgium, Italy, Spain, Sweden" }, { "command": "sudo tor-switch set-exit-node high-volume", "description": "Use high-traffic countries", "expectedOutput": "Exit node set to high-volume countries", "notes": "Affects default instance. High-volume countries: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA" }, { "command": "sudo tor-switch set-exit-node low-volume", "description": "Use low-traffic countries", "expectedOutput": "Exit node set to low-volume countries", "notes": "Affects default instance. Countries excluding high-volume and 14eyes nations for uniqueness" }, { "command": "sudo tor-switch set-exit-node-all ca", "description": "Set Canada for all instances", "expectedOutput": "Exit node set to Canada for all instances", "notes": "Applies setting to all configured instances" }, { "command": "sudo tor-switch clear-exit-node", "description": "Clear exit node restrictions", "expectedOutput": "Exit node restrictions cleared", "notes": "Returns to default random exit selection" }, { "command": "sudo tor-switch set-exclude-node cn,ru,ir", "description": "Exclude specific countries", "expectedOutput": "Excluded nodes set", "notes": "Prevents routing through specified countries" }, { "command": "sudo tor-switch set-exclude-node 5eyes", "description": "Exclude Five Eyes countries", "expectedOutput": "Five Eyes countries excluded", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exclude-node 9eyes", "description": "Exclude Nine Eyes countries", "expectedOutput": "Nine Eyes countries excluded", "notes": "5eyes + Denmark, France, Netherlands, Norway" }, { "command": "sudo tor-switch set-exclude-node 14eyes", "description": "Exclude Fourteen Eyes countries", "expectedOutput": "Fourteen Eyes countries excluded", "notes": "9eyes + Germany, Belgium, Italy, Spain, Sweden" }, { "command": "sudo tor-switch set-exclude-node europe", "description": "Exclude all European countries", "expectedOutput": "European countries excluded", "notes": "Excludes: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA" }, { "command": "sudo tor-switch set-exclude-node asia", "description": "Exclude all Asian countries", "expectedOutput": "Asian countries excluded", "notes": "Excludes: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN" }, { "command": "sudo tor-switch set-exclude-node north-america", "description": "Exclude North American countries", "expectedOutput": "North American countries excluded", "notes": "US, Canada, Mexico excluded" }, { "command": "sudo tor-switch set-exclude-node high-volume", "description": "Exclude high-traffic countries", "expectedOutput": "High-volume countries excluded", "notes": "Excludes: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA" }, { "command": "sudo tor-switch set-exclude-node low-volume", "description": "Exclude low-traffic countries", "expectedOutput": "Low-volume countries excluded", "notes": "Use only high-traffic exit nodes" }, { "command": "sudo tor-switch set-exclude-node random-high-volume", "description": "Exclude one random high-traffic country", "expectedOutput": "Random high-volume country excluded", "notes": "Randomly blocks one popular exit country" }, { "command": "sudo tor-switch set-exclude-node random-low-volume", "description": "Exclude one random low-traffic country", "expectedOutput": "Random low-volume country excluded", "notes": "Randomly blocks one uncommon exit country" }, { "command": "sudo tor-switch set-exclude-node asia --instance secure", "description": "Exclude Asia for secure instance", "expectedOutput": "Asia excluded for 'secure' instance", "notes": "Instance-specific exclusion" }, { "command": "sudo tor-switch set-exclude-node 14eyes --instance privacy-1", "description": "Exclude 14eyes for privacy instance", "expectedOutput": "14eyes excluded for 'privacy-1' instance", "notes": "Maximum privacy configuration" }, { "command": "sudo tor-switch set-exclude-node-all fr", "description": "Exclude France for all instances", "expectedOutput": "France excluded for all instances", "notes": "Global exclusion across all instances" }, { "command": "sudo tor-switch clear-exclude-node-main", "description": "Clear all excluded countries", "expectedOutput": "All exclusions removed", "notes": "Resets to default behavior" }, { "command": "sudo tor-switch clear-exclude-node-all", "description": "Clear excluded nodes for all instances", "expectedOutput": "Exclusions removed for all instances", "notes": "Global clear matching set-exclude-node-all scope" }, { "command": "sudo tor-switch clear-exit-node-all", "description": "Clear exit restrictions for all instances", "expectedOutput": "Exit restrictions cleared for all instances", "notes": "All instances return to random exit selection" } ], "id": "06_exit_node_management", "title": "Exit Node Management" }, { "description": "Native load balancing using iptables/nftables firewall rules", "examples": [ { "command": "sudo tor-switch set-load-balancing-mode round-robin", "description": "Sequential distribution", "expectedOutput": "Load balancing mode set to round-robin", "notes": "Each new connection uses the next Tor instance in order" }, { "command": "sudo tor-switch set-load-balancing-mode weighted", "description": "Weight-based distribution", "expectedOutput": "Load balancing mode set to weighted", "notes": "Routes traffic based on instance weights" }, { "command": "sudo tor-switch set-load-balancing-mode consistent-hashing", "description": "Client IP affinity for session persistence", "expectedOutput": "Load balancing mode set to consistent-hashing", "notes": "Same client IP always routes to same Tor instance" }, { "command": "sudo tor-switch set-instance-weight tor1 50", "description": "Set weight for specific instance", "expectedOutput": "Weight for instance 'tor1' set to 50", "notes": "Only affects weighted mode distribution" }, { "command": "sudo tor-switch set-instance-weight tor1 10", "description": "Set low weight for minimal traffic", "expectedOutput": "Weight for instance 'tor1' set to 10", "notes": "10% of traffic when using weighted mode" }, { "command": "sudo tor-switch set-instance-weight tor2 30", "description": "Set moderate weight for balanced traffic", "expectedOutput": "Weight for instance 'tor2' set to 30", "notes": "30% of traffic distribution" }, { "command": "sudo tor-switch set-instance-weight tor3 60", "description": "Set high weight for primary traffic", "expectedOutput": "Weight for instance 'tor3' set to 60", "notes": "60% of traffic - primary instance" }, { "command": "sudo tor-switch set-instance-weight performance-0 75", "description": "High weight for performance instance", "expectedOutput": "Weight for instance 'performance-0' set to 75", "notes": "Prioritize high-performance instance" }, { "command": "sudo tor-switch set-instance-weight backup 5", "description": "Minimal weight for backup instance", "expectedOutput": "Weight for instance 'backup' set to 5", "notes": "Mostly idle, used for failover" }, { "command": "sudo tor-switch set-instance-weight worker-1 25", "description": "Equal weight for worker instances", "expectedOutput": "Weight for instance 'worker-1' set to 25", "notes": "4 workers at 25% each = equal distribution" }, { "command": "tor-switch display-load-balancing-config", "description": "Show current load balancing setup", "expectedOutput": "Current load balancing configuration details" }, { "command": "sudo tor-switch torrify-system-iptables-load-balanced", "description": "Apply load balanced routing (iptables)", "expectedOutput": "Load balanced routing through Tor enabled", "notes": "Routes traffic through multiple Tor instances using iptables" }, { "command": "sudo tor-switch torrify-system-nftables-load-balanced", "description": "Apply load balanced routing (nftables)", "expectedOutput": "Load balanced routing through Tor enabled (nftables)", "notes": "Modern firewall load balanced routing using nftables" }, { "command": "sudo tor-switch prepare-tor", "description": "Pre-warm Tor instances and verify circuit readiness", "expectedOutput": "Instances bootstrapped and circuits confirmed ready", "notes": "Warms instances without applying any firewall rules. Run it before torrify to avoid first-connection delays" } ], "id": "07_load_balancing", "title": "Load Balancing (Native Kernel-Level)" }, { "description": "HAProxy provides advanced application-level load balancing", "examples": [ { "command": "sudo tor-switch generate-haproxy-config roundrobin 9055", "description": "Generate config with round-robin algorithm", "expectedOutput": "HAProxy configuration generated", "notes": "Each server is used in turns on port 9055" }, { "command": "sudo tor-switch generate-haproxy-config source 8080", "description": "Generate config with source IP hash", "expectedOutput": "HAProxy configuration generated", "notes": "IP hash persistence on port 8080" }, { "command": "sudo tor-switch generate-haproxy-config leastconn 9000", "description": "Generate config with least connections", "expectedOutput": "HAProxy configuration generated", "notes": "Routes to instance with fewest active connections" }, { "command": "sudo tor-switch generate-haproxy-config random 8888", "description": "Generate config with random selection", "expectedOutput": "HAProxy configuration generated", "notes": "Randomly selects backend for each connection" }, { "command": "sudo tor-switch haproxy-start", "description": "Start HAProxy service", "expectedOutput": "HAProxy started successfully" }, { "command": "tor-switch haproxy-status", "description": "Check HAProxy status", "expectedOutput": "HAProxy service status and statistics" }, { "command": "sudo tor-switch haproxy-stop", "description": "Stop HAProxy service", "expectedOutput": "HAProxy stopped" }, { "command": "tor-switch list-haproxy-modes", "description": "Show available HAProxy algorithms", "expectedOutput": "List of supported HAProxy algorithms", "notes": "roundrobin, source, leastconn, random" } ], "id": "08_haproxy", "title": "HAProxy Integration (Application-Level Proxy)" }, { "description": "Automatic IP rotation and timer-based operations", "examples": [ { "command": "sudo tor-switch auto-ip-change 10m", "description": "Auto IP change every 10 minutes", "expectedOutput": "Automatic IP change enabled with 10 minute interval", "notes": "Creates new Tor circuit for default instance to get new exit IP" }, { "command": "sudo tor-switch update-ip-timer browsing 5m", "description": "Set timer for specific instance", "expectedOutput": "IP change timer set for 'browsing' instance" }, { "command": "sudo tor-switch update-ip-timer worker-1 30m", "description": "Set 30-minute timer for worker instance", "expectedOutput": "IP change timer set for 'worker-1' instance: 30 minutes", "notes": "Balanced rotation for moderate privacy" }, { "command": "sudo tor-switch update-ip-timer streaming 1h", "description": "Set hourly timer for streaming", "expectedOutput": "IP change timer set for 'streaming' instance: 1 hour", "notes": "Less frequent changes for stable connections" }, { "command": "sudo tor-switch update-ip-timer research 15m", "description": "Set 15-minute timer for research", "expectedOutput": "IP change timer set for 'research' instance: 15 minutes", "notes": "Frequent rotation for privacy-focused browsing" }, { "command": "sudo tor-switch update-ip-timer backup 24h", "description": "Set daily timer for backup instance", "expectedOutput": "IP change timer set for 'backup' instance: 24 hours", "notes": "Minimal rotation for long-running operations" }, { "command": "sudo tor-switch update-ip-all-timer 10m", "description": "Set 10-minute timer for all instances", "expectedOutput": "IP change timer set for all instances: 10 minutes", "notes": "Synchronizes rotation across all instances" }, { "command": "sudo tor-switch update-ip-all-timer 2h", "description": "Set 2-hour timer for all instances", "expectedOutput": "IP change timer set for all instances: 2 hours", "notes": "Stable rotation for production workloads" }, { "command": "tor-switch list-ip-timers", "description": "List all IP change timers", "expectedOutput": "Table showing all instances with their IP change intervals" }, { "command": "sudo tor-switch remove-ip-timer browsing", "description": "Remove timer for instance", "expectedOutput": "IP change timer removed" }, { "command": "sudo tor-switch stop-auto-ip-change", "description": "Stop auto IP change", "expectedOutput": "Automatic IP change stopped" }, { "command": "sudo tor-switch update-ip-all-timer 15m", "description": "Set timer for all instances", "expectedOutput": "IP change timer set for all instances", "notes": "Synchronizes IP rotation across instances" }, { "command": "sudo tor-switch remove-ip-all-timer", "description": "Remove all IP change timers", "expectedOutput": "All IP timers removed", "notes": "Removes all automatic IP rotation timers from all instances" }, { "command": "tor-switch list-auto-ip-change", "description": "List automatic IP change settings", "expectedOutput": "Auto IP change configurations for all instances" } ], "id": "09_timer_and_automation", "title": "Timer Management and Automation" }, { "description": "Configure and manage DNS routing through Tor. AUTH NOTE: start-tor-dns-* and torrify-system-*-dns are anonymity-affecting mutations and REQUIRE an active online-auth session (`sudo online-auth authenticate` first). stop-tor-dns-* is exempt: it is in the emergency/recovery list and works even when auth is unavailable.", "examples": [ { "command": "sudo tor-switch start-tor-dns-iptables", "description": "Start Tor DNS listener with iptables", "expectedOutput": "Tor DNS service started with iptables rules", "notes": "Sets up Tor DNS listener service on port 9053. AUTH REQUIRED: run `sudo online-auth authenticate` first." }, { "command": "sudo tor-switch stop-tor-dns-iptables", "description": "Stop Tor DNS routing", "expectedOutput": "Tor DNS iptables rules removed", "notes": "Emergency/recovery exempt: works without auth." }, { "command": "sudo tor-switch torrify-system-dns", "description": "Route all DNS through Tor", "expectedOutput": "System DNS queries routed through Tor", "notes": "Auto-detects and uses whichever firewall backend is active. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." }, { "command": "sudo tor-switch start-tor-dns-nftables", "description": "Start Tor DNS listener with nftables", "expectedOutput": "Tor DNS service started with nftables rules", "notes": "Sets up Tor DNS listener service on port 9053. AUTH REQUIRED: run `sudo online-auth authenticate` first." }, { "command": "sudo tor-switch stop-tor-dns-nftables", "description": "Stop Tor DNS (nftables)", "expectedOutput": "Tor DNS nftables rules removed", "notes": "Emergency/recovery exempt: works without auth." }, { "command": "sudo tor-switch torrify-system-iptables-dns", "description": "Route DNS through Tor using iptables", "expectedOutput": "DNS routing through Tor enabled (iptables)", "notes": "Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." }, { "command": "sudo tor-switch torrify-system-nftables-dns", "description": "Route DNS through Tor using nftables", "expectedOutput": "DNS routing through Tor enabled (nftables)", "notes": "Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." } ], "id": "10_dns_management", "title": "DNS Management" }, { "description": "Test and verify DNS routing through Tor", "examples": [ { "command": "tor-switch verify-tor-dns", "description": "Verify Tor DNS resolution of .onion addresses", "expectedOutput": "DNS verification successful! (tests both direct and port methods)", "notes": "Resolves .onion addresses to verify DNS goes through Tor" }, { "command": "tor-switch verify-tor-dns-all", "description": "Verify DNS resolution for all Tor instances", "expectedOutput": "DNS verification results for each instance", "notes": "Tests .onion resolution for all configured Tor instances" }, { "command": "tor-switch verify-tor-dns-direct", "description": "Verify .onion resolution using system DNS", "expectedOutput": "Onion addresses can be resolved directly", "notes": "Uses system resolver to test .onion domain resolution" }, { "command": "tor-switch verify-tor-dns-port", "description": "Verify .onion resolution via Tor DNS port", "expectedOutput": "Onion addresses can be resolved using DNS port", "notes": "Uses instance's DNS port to test .onion resolution" }, { "command": "tor-switch verify-tor-dns --json", "description": "Verify Tor DNS and capture the result for a script", "expectedOutput": "JSON envelope with per-method resolution results", "notes": "The verify-tor-dns* commands take no arguments: they always test the currently active Tor DNS listener. To check one specific instance, make it the default first with set-default-instance, or use verify-tor-dns-all to cover every instance." } ], "id": "11_dns_verification", "title": "DNS Verification" }, { "description": "Manage iptables and nftables firewall rules. The flush-* and torrify/detorrify commands change the live firewall the moment you run them, with no confirmation prompt. A --force (alias --yes) flag is still accepted for backwards compatibility, but it is NOT a confirmation gate and passing it changes nothing.", "examples": [ { "command": "sudo tor-switch flush-iptables", "description": "Flush iptables rules", "expectedOutput": "All iptables rules cleared", "notes": "DESTRUCTIVE, NOT REVERSIBLE: drops every iptables rule and policy, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt." }, { "command": "tor-switch list-iptables", "description": "List current iptables rules", "expectedOutput": "Display of all active iptables rules" }, { "command": "tor-switch which-is-active", "description": "Check active firewall", "expectedOutput": "Shows whether iptables or nftables is active" }, { "command": "sudo tor-switch flush-nftables", "description": "Flush nftables rules", "expectedOutput": "All nftables rules cleared", "notes": "DESTRUCTIVE, NOT REVERSIBLE: drops every nftables rule, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt." }, { "command": "tor-switch list-nftables", "description": "List current nftables rules", "expectedOutput": "Display of all active nftables rules" }, { "command": "tor-switch list-iptables-nat", "description": "List NAT rules", "expectedOutput": "Display of all NAT table rules", "notes": "Shows network address translation rules" }, { "command": "sudo tor-switch boot-restore-torrified --json", "description": "Rebuild the Tor instance pool at boot when the persisted firewall is already torrified", "expectedOutput": "JSON envelope reporting the instances restarted, or a no-op result when the saved firewall is not torrified", "notes": "You normally never run this by hand: kodachi-tor-pool-boot.service runs it at every boot. It is auth-exempt so it still works before online-auth is up. On a non-torrified system it does nothing." } ], "id": "12_firewall_operations", "title": "Firewall Operations" }, { "description": "Manage Tor configuration files and validation", "examples": [ { "command": "tor-switch validate-torrc", "description": "Validate torrc configuration", "expectedOutput": "Configuration validation results", "notes": "Checks syntax without starting Tor" }, { "command": "sudo tor-switch reload-tor-config", "description": "Reload configuration", "expectedOutput": "Configuration reloaded successfully", "notes": "Applies changes without restart" }, { "command": "sudo tor-switch generate-new-tor-password", "description": "Generate new control password", "expectedOutput": "New control password generated" }, { "command": "sudo tor-switch clean-torrc-custom", "description": "Clean custom configuration", "expectedOutput": "Custom torrc entries removed" }, { "command": "sudo tor-switch clean-torrc-custom-all", "description": "Clean all custom configurations", "expectedOutput": "Custom entries removed from all instances" }, { "command": "sudo tor-switch reload-tor-config-all", "description": "Reload all configurations", "expectedOutput": "All instance configurations reloaded" }, { "command": "sudo tor-switch generate-new-tor-password-all", "description": "Generate passwords for all instances", "expectedOutput": "New control passwords generated for all" }, { "command": "tor-switch get-tor-custom-status", "description": "Get custom configuration status", "expectedOutput": "Status of custom configurations" } ], "id": "13_configuration_management", "title": "Configuration Management" }, { "description": "Backup and restore Tor instance configurations", "examples": [ { "command": "sudo tor-switch backup-config", "description": "Backup configuration", "expectedOutput": "Configuration backed up with timestamp (default instance)" }, { "command": "tor-switch list-backups", "description": "List available backups", "expectedOutput": "Table showing all backup files" }, { "command": "sudo tor-switch restore-config backup-2025-01-28", "description": "Restore from backup", "expectedOutput": "Configuration restored", "notes": "Restores configuration and restarts instances" }, { "command": "sudo tor-switch backup-config-all", "description": "Backup all configurations", "expectedOutput": "All instance configurations backed up" }, { "command": "sudo tor-switch restore-config-all backup-2025-01-28", "description": "Restore all from backup", "expectedOutput": "All configurations restored from backup", "notes": "Restores complete multi-instance setup" } ], "id": "14_backup_and_restore", "title": "Backup and Restore" }, { "description": "WARNING, TROUBLESHOOTING ONLY: these commands edit the shared system Tor daemon (/etc/tor/torrc), not a Kodachi instance. Changing main Tor affects every application that talks to the system Tor and can break instance routing. For all normal work use the Kodachi instance commands instead. Add --maintor to target the system daemon explicitly.", "examples": [ { "command": "tor-switch validate-torrc-main --maintor", "description": "Validate main Tor configuration", "expectedOutput": "Main Tor configuration validated", "notes": "Validates /etc/tor/torrc syntax and settings" }, { "command": "tor-switch read-main-tor-config", "description": "Display main Tor configuration", "expectedOutput": "Main Tor configuration displayed", "notes": "Shows ports, exit/exclude nodes, and security settings" }, { "command": "sudo tor-switch backup-main-tor-config", "description": "Backup main Tor configuration", "expectedOutput": "Main Tor configuration backed up", "notes": "Creates timestamped backup in backups/main-tor/" }, { "command": "sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup", "description": "Restore main Tor configuration", "expectedOutput": "Main Tor configuration restored", "notes": "Current config is backed up before restoring" }, { "command": "sudo tor-switch set-exit-node-main US --maintor", "description": "Set US exit node for main Tor", "expectedOutput": "Exit node set to US for main Tor", "notes": "Forces traffic to exit through United States" }, { "command": "sudo tor-switch clear-exit-node-main --maintor", "description": "Clear exit node restrictions", "expectedOutput": "Exit node restrictions cleared for main Tor", "notes": "Allows Tor to choose any exit country" }, { "command": "sudo tor-switch set-exclude-node-main CN,RU --maintor", "description": "Exclude countries from circuits", "expectedOutput": "Excluded nodes set for main Tor", "notes": "Prevents routing through specified countries" }, { "command": "sudo tor-switch clear-exclude-node-main --maintor", "description": "Clear excluded countries", "expectedOutput": "Exclude restrictions cleared for main Tor", "notes": "Removes all country exclusions" }, { "command": "tor-switch list-exit-exclude-main", "description": "Show exit/exclude settings", "expectedOutput": "Exit/exclude settings displayed", "notes": "Displays current geographic routing rules" }, { "command": "sudo tor-switch reload-main-tor", "description": "Reload main Tor configuration", "expectedOutput": "Main Tor configuration reloaded", "notes": "Sends SIGHUP signal to apply config changes" }, { "command": "tor-switch status-main-tor", "description": "Get main Tor daemon status", "expectedOutput": "Main Tor status displayed", "notes": "Shows systemctl status and port information" }, { "command": "tor-switch verify-main-tor-dns", "description": "Verify DNS routing through Tor", "expectedOutput": "DNS routing through main Tor verified", "notes": "Tests DNS resolution via tor-resolve" }, { "command": "sudo tor-switch new-circuit-main-tor", "description": "Request new Tor circuit", "expectedOutput": "New circuit requested for main Tor", "notes": "Gets new IP by building fresh circuit" }, { "command": "tor-switch check-main-tor-security", "description": "Security audit main Tor", "expectedOutput": "Security audit completed", "notes": "Checks for security misconfigurations" }, { "command": "tor-switch main-tor-bandwidth", "description": "Show Tor bandwidth usage", "expectedOutput": "Bandwidth usage displayed", "notes": "Displays active SOCKS connections count" }, { "command": "tor-switch main-tor-connections", "description": "List active Tor connections", "expectedOutput": "Active connections listed", "notes": "Shows established connections on SOCKS port" }, { "command": "tor-switch main-tor-logs", "description": "Display recent Tor logs", "expectedOutput": "Recent logs displayed", "notes": "Shows last 50 lines from Tor log or journald" }, { "command": "tor-switch validate-torrc-main --maintor --json", "description": "Validate with JSON output", "expectedOutput": "JSON validation output returned", "notes": "Machine-readable output for scripting" } ], "id": "15_main_tor_management", "title": "Main Tor Management (TROUBLESHOOTING ONLY)" }, { "description": "Complete workflow examples for common use cases", "examples": [ { "command": "# Privacy-focused browsing setup\nsudo tor-switch create-multiple-instances 3 privacy\nsudo tor-switch set-exclude-node 5eyes --instance privacy-1\nsudo tor-switch set-exclude-node 9eyes --instance privacy-2\nsudo tor-switch set-exclude-node 14eyes --instance privacy-3\nsudo tor-switch update-ip-timer privacy-1 5m\nsudo tor-switch update-ip-timer privacy-2 10m\nsudo tor-switch update-ip-timer privacy-3 15m", "description": "Complete privacy-focused setup", "expectedOutput": "Privacy-optimized Tor configuration active", "notes": "Avoids surveillance alliance countries with rapid rotation" }, { "command": "# Regional distribution setup\nsudo tor-switch create-instance europe\nsudo tor-switch create-instance asia\nsudo tor-switch create-instance americas\nsudo tor-switch set-exit-node europe --instance europe\nsudo tor-switch set-exit-node asia --instance asia\nsudo tor-switch set-exit-node north-america --instance americas", "description": "Geographic distribution setup", "expectedOutput": "Regional Tor instances configured", "notes": "Access region-specific content simultaneously" }, { "command": "# High-availability setup\nsudo tor-switch create-multiple-instances 5 ha\nsudo tor-switch set-load-balancing-mode weighted\nsudo tor-switch set-instance-weight ha-1 30\nsudo tor-switch set-instance-weight ha-2 25\nsudo tor-switch set-instance-weight ha-3 20\nsudo tor-switch set-instance-weight ha-4 15\nsudo tor-switch set-instance-weight ha-5 10\nsudo tor-switch torrify-system-iptables-load-balanced", "description": "High-availability load balanced setup", "expectedOutput": "HA configuration with weighted distribution active", "notes": "Redundant instances with priority-based traffic distribution" }, { "command": "# Research and testing setup\nsudo tor-switch create-instance research\nsudo tor-switch create-instance testing\nsudo tor-switch set-exit-node random-low-volume --instance research\nsudo tor-switch set-exit-node high-volume --instance testing\nsudo tor-switch update-ip-timer research 2m\ntor-switch verify-tor-dns-all", "description": "Research and testing environment", "expectedOutput": "Research/testing instances configured", "notes": "Separate instances for different testing scenarios. verify-tor-dns takes no --instance flag, so verify-tor-dns-all is used to cover both instances at once." }, { "command": "# Performance-optimized setup\nsudo tor-switch create-multiple-instances 10 perf\nsudo tor-switch set-load-balancing-mode round-robin\nsudo tor-switch generate-haproxy-config\nsudo tor-switch haproxy-start\ntor-switch haproxy-status", "description": "Maximum performance configuration", "expectedOutput": "Performance-optimized setup with HAProxy active", "notes": "10 instances with HAProxy for maximum throughput" }, { "command": "# Clean slate reset\nsudo tor-switch stop-all-instances\nsudo tor-switch cleanup\nsudo tor-switch flush-iptables\nsudo tor-switch restart-tor\ntor-switch check-tor", "description": "Complete reset to default state", "expectedOutput": "System reset to clean Tor configuration", "notes": "Removes all custom configurations and instances" }, { "command": "# Monitoring and diagnostics\ntor-switch tor-status-all\ntor-switch list-instances\ntor-switch list-ip-timers\ntor-switch display-load-balancing-config\ntor-switch haproxy-status", "description": "Complete system status check", "expectedOutput": "Full diagnostic report displayed", "notes": "Comprehensive view of all Tor configurations" } ], "id": "16_advanced_workflows", "title": "Advanced Workflows" }, { "description": "obfs4 bridges allow Tor to bootstrap over XTLS-Vision Reality VPN connections, where plain Tor fails because Vision inspects the nested TLS. Bridges wrap the Tor handshake in an opaque layer that Vision cannot identify.", "examples": [ { "command": "sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'", "description": "Store a single obfs4 bridge and activate it for all instances", "expectedOutput": "Bridges saved (1 lines). obfs4proxy: /usr/bin/obfs4proxy", "notes": "Requires obfs4proxy installed (apt install obfs4proxy). All instances are restarted automatically." }, { "command": "sudo tor-switch set-bridges --from-file /tmp/bridges.txt", "description": "Load multiple bridge lines from a file (one per line, # comments ignored)", "expectedOutput": "Bridges saved. All instances restarted with bridge configuration.", "notes": "Recommended for the dashboard: write bridge lines to a temp file then pass --from-file." }, { "command": "tor-switch list-bridges --json", "description": "Show stored bridge config and obfs4proxy detection result as JSON", "expectedOutput": "{\"enabled\":true,\"transport\":\"obfs4\",\"bridges_count\":2,...}", "notes": "Read-only, no sudo required." }, { "command": "tor-switch test-bridges --json", "description": "Validate stored bridge lines and check obfs4proxy path without making changes", "expectedOutput": "{\"all_valid\":true,\"obfs4proxy_found\":true,...}", "notes": "Read-only, no sudo required. Use before enable-bridges to confirm lines are well-formed." }, { "command": "sudo tor-switch disable-bridges", "description": "Revert to direct Tor (strip bridge block, restart all instances)", "expectedOutput": "Bridges disabled. Tor instances reverted to direct connections.", "notes": "Preserves stored bridge lines so you can re-enable later." }, { "command": "sudo tor-switch enable-bridges", "description": "Re-activate previously stored bridges for all instances", "expectedOutput": "Bridges enabled. N bridges active.", "notes": "Requires at least one bridge stored via set-bridges." }, { "command": "sudo tor-switch clear-bridges", "description": "Remove all stored bridges and revert all instances to direct Tor", "expectedOutput": "All bridges cleared. Tor instances using direct connections.", "notes": "Permanently removes bridges.json entries. Use disable-bridges instead to keep them for later." }, { "command": "sudo tor-switch set-bridge-mode --mode all", "description": "Use all stored bridges simultaneously (default behavior)", "expectedOutput": "Bridge selection mode set to 'all' (active_count=1, N bridges stored).", "notes": "Re-applies the bridge config and restarts all instances." }, { "command": "sudo tor-switch set-bridge-mode --mode random --count 2", "description": "Randomly pick 2 bridges from the stored list each time bridges are applied", "expectedOutput": "Bridge selection mode set to 'random' (active_count=2, N bridges stored).", "notes": "Useful when you have many bridges and want to vary which ones are used." }, { "command": "sudo tor-switch rotate-bridges", "description": "Pick a fresh random subset of bridges and restart all instances", "expectedOutput": "Bridge rotation applied: 1 bridge(s) selected from 5 stored.", "notes": "In 'all' mode this re-applies without changing the active set. In 'random' mode a new subset is picked." }, { "command": "sudo tor-switch bridge-rotate-timer 15m", "description": "Install a cron job that calls rotate-bridges every 15 minutes", "expectedOutput": "Bridge rotation cron installed: every 15 minutes (*/15 * * * *). Use stop-bridge-rotate-timer to remove.", "notes": "Minimum interval is 1 minute. Tagged with KODACHI_BRIDGE_ROTATE in crontab. Only one timer can be active; running again replaces the previous one." }, { "command": "sudo tor-switch stop-bridge-rotate-timer", "description": "Remove the bridge rotation cron job", "expectedOutput": "Bridge rotation cron job removed.", "notes": "Reports cleanly if no timer was installed." } ], "id": "17_bridges", "title": "Bridge Management (obfs4 Pluggable Transport)" }, { "description": "Built-in help and usage examples", "examples": [ { "command": "tor-switch show-help", "description": "Show help information", "expectedOutput": "Full command reference with descriptions", "notes": "Equivalent to -h; read-only, no privileges required" }, { "command": "tor-switch show-examples", "description": "Show usage examples", "expectedOutput": "Categorized example commands with expected output", "notes": "Equivalent to -e; read-only, no privileges required" } ], "id": "18_help", "title": "Help & Documentation" } ], "description": "Usage examples for tor-switch", "name": "tor-switch", "quickReference": [ "tor-switch --help", "tor-switch --version", "tor-switch --info --json", "tor-switch --examples", "tor-switch check-tor", "tor-switch torverify", "tor-switch tor-status", "tor-switch list-instances", "tor-switch which-is-active", "tor-switch verify-tor-dns", "sudo tor-switch start-tor", "sudo tor-switch new-tor-circuit", "sudo tor-switch set-exit-node US", "sudo tor-switch set-exclude-node 14eyes", "sudo tor-switch create-instance secondary", "sudo tor-switch torrify-system-iptables", "sudo tor-switch detorrify-system-iptables", "sudo tor-switch torrify-system-iptables-dns" ] }, "errors": [], "metadata": { "executionTime": 13, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.683278153Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "workflow-manager", "path": "/opt/kodachi/dashboard/hooks/workflow-manager", "timestamp": "2026-07-21T01:54:40Z", "file_info": { "size": 4502848, "sha256": "63bf382c55e55fb3bd44067e3fe65b8e0e5aedc87528d6697bf31b306191d18b" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "Ā© 2026 Kodachi OS", "description": "Workflow manager for batch command execution with conditional logic", "features": [ "Template-based workflow management", "Conditional command execution", "Batch processing with retry logic", "State tracking and logging", "Concurrent execution support", "Pause steps with user confirmation", "Substring, regex and JSON path conditions", "JSON path subset support (dot fields + array indexes)", "Prerequisites validation before execution", "System state checking and probes", "Reusable probe functions for conditions" ], "license": "Proprietary", "name": "workflow-manager", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://www.digi77.com" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:40.155150502Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "workflow-manager", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:40.263999522Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Diagnostics", "commands": [ { "description": "Validate workflow prerequisites", "examples": [ "workflow-manager prereq check initial_terminal_setup_wireguard_torrify", "workflow-manager prereq validate my-workflow", "workflow-manager prereq check my-workflow --json" ], "name": "prereq", "options": [ { "description": "check, or validate (an alias for check)", "flag": "<SUBCOMMAND>", "required": true }, { "description": "Template whose prerequisites block is evaluated", "flag": "<TEMPLATE>", "required": true } ], "requires_sudo": false, "usage": "workflow-manager prereq <check|validate> <TEMPLATE>" }, { "description": "Query system state", "examples": [ "workflow-manager state", "workflow-manager state online", "workflow-manager state security_score --json" ], "name": "state", "options": [ { "description": "Single state to query (online, torrify, tor_running, security_score, routing_mode, authenticated, ...). Omit to return all 20", "flag": "[FIELD]", "required": false }, { "description": "Emit the state as a JSON envelope (global flag)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "workflow-manager state [FIELD]" } ] }, { "category": "Execution", "commands": [ { "description": "Run a workflow template", "examples": [ "workflow-manager run my-workflow --dry-run", "workflow-manager run my-workflow", "workflow-manager run my-workflow --kill-policy continue", "workflow-manager run my-workflow --max-log-size 20971520", "workflow-manager run my-workflow --param interface=eth0 --param mode=safe", "workflow-manager run my-workflow --yes", "workflow-manager run my-workflow --json" ], "name": "run", "options": [ { "description": "Template to execute", "flag": "<TEMPLATE>", "required": true }, { "default": "false", "description": "List the steps that would run without executing any of them", "flag": "--dry-run", "required": false }, { "default": "stop", "description": "What to do when a step fails: stop, continue or skip_remaining. Overrides global_settings.kill_policy", "flag": "--kill-policy <POLICY>", "required": false }, { "default": "10485760", "description": "Cap the run log size in bytes. Overrides global_settings.max_log_size", "flag": "--max-log-size <BYTES>", "required": false }, { "description": "Override a declared workflow parameter. Repeat for multiple parameters", "flag": "--param <KEY=VALUE>", "required": false }, { "default": "false", "description": "Skip ordinary top-level [y/N] prompts in text mode; never approves high-risk or included child steps", "flag": "-y, --yes", "required": false }, { "description": "Override a workflow parameter; may be repeated", "flag": "--param <NAME=VALUE>", "required": false }, { "description": "Carry one exact dashboard-approved child step record; may be repeated", "flag": "--approved-step <JSON>", "required": false } ], "requires_sudo": false, "usage": "workflow-manager run <TEMPLATE> [OPTIONS]" } ] }, { "category": "Steps", "commands": [ { "description": "Add a step to a workflow template", "examples": [ "workflow-manager add my-workflow 'echo Hello World'", "workflow-manager add my-workflow 'tar czf backup.tar.gz /data' -t 600 --description 'Archive data'", "workflow-manager add my-workflow 'cleanup.sh' -c if_success", "workflow-manager add my-workflow './notify.sh' --if-contains 'ERROR'", "workflow-manager add my-workflow './handle-connected.sh' --if-json-path '$.status=\"connected\"'", "workflow-manager add my-workflow './tor-ready.sh' --if-state tor_running --if-state-expect true", "workflow-manager add my-workflow './low-score-fix.sh' --if-expression \"state.security_score < 60\"", "workflow-manager add w1 \"ip-fetch\",\"online-auth check-login\",\"ip addr show\"" ], "name": "add", "options": [ { "description": "Template to append the step to", "flag": "<TEMPLATE>", "required": true }, { "description": "Command to execute. A comma separated list creates one step per command", "flag": "<COMMAND>", "required": true }, { "description": "Step description", "flag": "--description <TEXT>", "required": false }, { "default": "always", "description": "Basic condition: always, if_success or if_fail", "flag": "-c, --condition <TYPE>", "required": false }, { "description": "Run only if the named probe from the profile's probes block matches", "flag": "--if-probe <NAME>", "required": false }, { "description": "Value the probe must return (JSON: true, 4, \"ok\")", "flag": "--if-probe-expect <JSON>", "required": false }, { "description": "Run only if a live system state matches (see `workflow-manager state`)", "flag": "--if-state <NAME>", "required": false }, { "description": "Value the state must have (JSON: true, false, \"wireguard\")", "flag": "--if-state-expect <JSON>", "required": false }, { "description": "Boolean expression over probe('NAME') and state.NAME, joined with && and ||", "flag": "--if-expression <EXPR>", "required": false }, { "description": "Run only if the previous step's output contains TEXT (substring, case sensitive)", "flag": "--if-contains <TEXT>", "required": false }, { "description": "Run only if the previous output does not contain TEXT", "flag": "--if-not-contains <TEXT>", "required": false }, { "description": "Run only if the previous output equals VALUE exactly (trimmed)", "flag": "--if-equals <VALUE>", "required": false }, { "description": "Run only if the previous output matches the regex", "flag": "--if-regex <PATTERN>", "required": false }, { "description": "Run only if the previous output does not match the regex", "flag": "--if-not-regex <PATTERN>", "required": false }, { "description": "Run only if a JSON field matches, e.g. '$.status=\"connected\"' (writes if_json_path_equals)", "flag": "--if-json-path <EXPR>", "required": false }, { "description": "Step timeout. Falls back to global_settings.default_timeout when omitted", "flag": "-t, --timeout <SECONDS>", "required": false }, { "default": "false", "description": "Prompt [y/N] before this step runs (text mode only)", "flag": "--confirm", "required": false }, { "description": "Directory to run the step from", "flag": "-w, --working-dir <PATH>", "required": false }, { "default": "0", "description": "Process priority, -20 (highest) to 19 (lowest). Negative values need root", "flag": "--nice-level <N>", "required": false }, { "description": "Comma separated allowlist of environment variables passed to the step", "flag": "--env <VARS>", "required": false } ], "requires_sudo": false, "usage": "workflow-manager add <TEMPLATE> <COMMAND> [OPTIONS]" }, { "description": "Add a pause step to a workflow template", "examples": [ "workflow-manager pause my-workflow -m 'Review results before continuing'", "workflow-manager pause backup -m 'Verify backup integrity' -c if_success" ], "name": "pause", "options": [ { "description": "Template to append the pause to", "flag": "<TEMPLATE>", "required": true }, { "description": "Message shown to the user while the workflow waits", "flag": "-m, --message <TEXT>", "required": false }, { "default": "always", "description": "Basic condition: always, if_success or if_fail", "flag": "-c, --condition <TYPE>", "required": false } ], "requires_sudo": false, "usage": "workflow-manager pause <TEMPLATE> [OPTIONS]" }, { "description": "Add an include step to a workflow template (includes another profile)", "examples": [ "workflow-manager include my-workflow shared-prereqs --description 'Reusable setup steps'", "workflow-manager include my-workflow tor-recovery -c if_fail", "workflow-manager include my-workflow base-recovery-sequence --if-state online --if-state-expect true" ], "name": "include", "options": [ { "description": "Template to append the include to", "flag": "<TEMPLATE>", "required": true }, { "description": "Existing profile whose steps are expanded in place at run time", "flag": "<PROFILE>", "required": true }, { "description": "Step description", "flag": "--description <TEXT>", "required": false }, { "default": "always", "description": "Basic condition: always, if_success or if_fail", "flag": "-c, --condition <TYPE>", "required": false }, { "description": "Run only if the named probe from the profile's probes block matches", "flag": "--if-probe <NAME>", "required": false }, { "description": "Value the probe must return (JSON: true, 4, \"ok\")", "flag": "--if-probe-expect <JSON>", "required": false }, { "description": "Run only if a live system state matches (see `workflow-manager state`)", "flag": "--if-state <NAME>", "required": false }, { "description": "Value the state must have (JSON: true, false, \"wireguard\")", "flag": "--if-state-expect <JSON>", "required": false }, { "description": "Boolean expression over probe('NAME') and state.NAME, joined with && and ||", "flag": "--if-expression <EXPR>", "required": false } ], "requires_sudo": false, "usage": "workflow-manager include <TEMPLATE> <PROFILE> [OPTIONS]" }, { "description": "Update a step in a workflow template", "examples": [ "workflow-manager update my-workflow 1 'echo Updated Command' -t 300", "workflow-manager update my-workflow 2 --if-contains 'ERROR' --description 'Alert on error'", "workflow-manager update my-workflow 2 --clear-condition -c always", "workflow-manager update my-workflow 3 -m 'Verify the archive, then press Enter' --confirm true", "workflow-manager update my-workflow 4 --profile base-recovery-sequence" ], "name": "update", "options": [ { "description": "Template to edit", "flag": "<TEMPLATE>", "required": true }, { "description": "Step number to update, as shown by `workflow-manager show`", "flag": "<STEP_ID>", "required": true }, { "description": "New command for a command step. Omit it to change only the flags below", "flag": "[COMMAND]", "required": false }, { "description": "New message for a pause step", "flag": "-m, --message <TEXT>", "required": false }, { "description": "New profile for an include step", "flag": "--profile <NAME>", "required": false }, { "description": "New step description", "flag": "--description <TEXT>", "required": false }, { "default": "always", "description": "Basic condition: always, if_success or if_fail", "flag": "-c, --condition <TYPE>", "required": false }, { "description": "Run only if the named probe from the profile's probes block matches", "flag": "--if-probe <NAME>", "required": false }, { "description": "Value the probe must return (JSON: true, 4, \"ok\")", "flag": "--if-probe-expect <JSON>", "required": false }, { "description": "Run only if a live system state matches (see `workflow-manager state`)", "flag": "--if-state <NAME>", "required": false }, { "description": "Value the state must have (JSON: true, false, \"wireguard\")", "flag": "--if-state-expect <JSON>", "required": false }, { "description": "Boolean expression over probe('NAME') and state.NAME, joined with && and ||", "flag": "--if-expression <EXPR>", "required": false }, { "description": "Run only if the previous step's output contains TEXT (substring, case sensitive)", "flag": "--if-contains <TEXT>", "required": false }, { "description": "Run only if the previous output does not contain TEXT", "flag": "--if-not-contains <TEXT>", "required": false }, { "description": "Run only if the previous output equals VALUE exactly (trimmed)", "flag": "--if-equals <VALUE>", "required": false }, { "description": "Run only if the previous output matches the regex", "flag": "--if-regex <PATTERN>", "required": false }, { "description": "Run only if the previous output does not match the regex", "flag": "--if-not-regex <PATTERN>", "required": false }, { "description": "Run only if a JSON field matches, e.g. '$.status=\"connected\"' (writes if_json_path_equals)", "flag": "--if-json-path <EXPR>", "required": false }, { "default": "false", "description": "Drop the stored condition payload and reset to the basic type given by -c", "flag": "--clear-condition", "required": false }, { "description": "New step timeout", "flag": "-t, --timeout <SECONDS>", "required": false }, { "description": "Set or clear the confirm flag (true or false)", "flag": "--confirm <BOOL>", "required": false }, { "description": "New working directory for the step", "flag": "-w, --working-dir <PATH>", "required": false }, { "description": "New process priority, -20 (highest) to 19 (lowest)", "flag": "--nice-level <N>", "required": false }, { "description": "New comma separated environment allowlist", "flag": "--env <VARS>", "required": false } ], "requires_sudo": false, "usage": "workflow-manager update <TEMPLATE> <STEP_ID> [COMMAND] [OPTIONS]" }, { "description": "Delete a step from a workflow template", "examples": [ "workflow-manager delete-step my-workflow 2", "workflow-manager show my-workflow && workflow-manager delete-step my-workflow 3" ], "name": "delete-step", "options": [ { "description": "Template to edit", "flag": "<TEMPLATE>", "required": true }, { "description": "Step number to remove, as shown by `workflow-manager show`", "flag": "<STEP_ID>", "required": true } ], "requires_sudo": false, "usage": "workflow-manager delete-step <TEMPLATE> <STEP_ID>" } ] }, { "category": "Templates", "commands": [ { "description": "Create a new workflow template", "examples": [ "workflow-manager create my-workflow", "workflow-manager create backup-workflow --description 'Daily backup routine'", "workflow-manager create diagnostics && workflow-manager add diagnostics './health-control net-check'" ], "name": "create", "options": [ { "description": "Name of the template, stored as config/profiles/<NAME>.json", "flag": "<NAME>", "required": true }, { "description": "Human readable description of the workflow", "flag": "--description <TEXT>", "required": false }, { "description": "Overwrite an existing template with the same name", "flag": "--force", "required": false } ], "requires_sudo": false, "usage": "workflow-manager create <NAME> [OPTIONS]" }, { "description": "List all workflow templates", "examples": [ "workflow-manager list", "workflow-manager list --json" ], "name": "list", "options": [ { "description": "Emit the template list as a JSON envelope (global flag)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "workflow-manager list" }, { "description": "Show details of a workflow template", "examples": [ "workflow-manager show my-workflow", "workflow-manager show my-workflow --json" ], "name": "show", "options": [ { "description": "Template to display", "flag": "<TEMPLATE>", "required": true }, { "description": "Print the raw profile JSON, which is exactly what the runner deserializes (global flag)", "flag": "--json", "required": false } ], "requires_sudo": false, "usage": "workflow-manager show <TEMPLATE>" }, { "description": "Delete an entire workflow template", "examples": [ "workflow-manager delete my-workflow", "workflow-manager list && workflow-manager delete obsolete-workflow" ], "name": "delete", "options": [ { "description": "Template to delete. This removes the profile JSON from disk and cannot be undone", "flag": "<TEMPLATE>", "required": true } ], "requires_sudo": false, "usage": "workflow-manager delete <TEMPLATE>" } ] } ], "description": "Workflow manager for batch command execution with conditional logic", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format <FORMAT>" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter <FIELD1,FIELD2>" }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields <FIELD_LIST>" }, { "description": "Limit number of results returned", "flag": "--limit <NUMBER>" }, { "description": "Skip first N results (for pagination)", "flag": "--offset <NUMBER>" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" } ], "name": "workflow-manager", "usage": "workflow-manager [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 1, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:40.362663837Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Create a template, add a step, preview it, then run it. Templates are stored as JSON profiles under the hooks config directory (config/profiles/<NAME>.json).", "examples": [ { "command": "workflow-manager create my-workflow", "description": "Create an empty workflow template", "expectedOutput": "Template 'my-workflow' created successfully" }, { "command": "workflow-manager add my-workflow 'echo Hello World'", "description": "Append a command step to the template", "expectedOutput": "Step 1 added to template 'my-workflow'", "notes": "`add` requires the template to exist already, so run `create` first." }, { "command": "workflow-manager show my-workflow", "description": "Inspect the steps, their IDs and their conditions", "expectedOutput": "Workflow Template: my-workflow\nStep 1: echo Hello World (condition: always)" }, { "command": "workflow-manager run my-workflow --dry-run", "description": "Preview execution without running any command", "expectedOutput": "Dry run: 1 step would be executed", "notes": "Always dry-run first: steps run real shell commands." }, { "command": "workflow-manager run my-workflow", "description": "Execute every step in order", "expectedOutput": "Workflow completed: Success (1/1 steps)", "notes": "workflow-manager itself does not need root. Individual steps may, if the command inside the step does." } ], "id": "0_quick_start", "title": "Quick Start" }, { "description": "Create, list, view, and delete workflow templates.", "examples": [ { "command": "workflow-manager create backup-workflow --description 'Daily backup routine'", "description": "Create a template with a human readable label", "expectedOutput": "Template 'backup-workflow' created successfully" }, { "command": "workflow-manager list", "description": "Show every stored workflow template", "expectedOutput": "Workflow Templates (2 total)\n backup-workflow (4 steps)\n my-workflow (1 step)" }, { "command": "workflow-manager show backup-workflow --json", "description": "Print the raw profile JSON, which is what the runner deserializes", "expectedOutput": "The full profile object: name, description, global_settings, prerequisites, probes and steps", "notes": "Use this to see the exact schema before hand editing config/profiles/backup-workflow.json." }, { "command": "workflow-manager delete backup-workflow", "description": "Remove an entire workflow template", "expectedOutput": "Template 'backup-workflow' deleted successfully", "notes": "Destructive and irreversible: the profile JSON is deleted from disk. Use `delete-step` if you only want to remove one step." } ], "id": "1_template_management", "title": "Template Management" }, { "description": "Add command steps to a template. A comma separated command list creates one step per command.", "examples": [ { "command": "workflow-manager add my-workflow 'tar czf backup.tar.gz /data' --timeout 600 --description 'Archive data'", "description": "Add a step with a 10 minute timeout and a description", "expectedOutput": "Step 2 added to template 'my-workflow' (timeout 600s)", "notes": "--timeout (-t) is the STEP timeout. It shadows the cli-core global --timeout inside `add`." }, { "command": "workflow-manager create w1 && workflow-manager add w1 \"ip-fetch\",\"online-auth check-login\",\"ip addr show\"", "description": "Create a template and add three steps in one call using comma separation", "expectedOutput": "Template 'w1' created, 3 steps added to template 'w1'", "notes": "All steps created in one call share the same timeout and condition settings." }, { "command": "workflow-manager add my-workflow 'cleanup.sh' -c if_success", "description": "Run this step only if the previous step exited 0", "expectedOutput": "Step added with condition if_success" }, { "command": "workflow-manager add my-workflow './health-control panic hard' --confirm", "description": "Mark a step as requiring an interactive confirmation before it runs", "expectedOutput": "Step added with confirm=true", "notes": "confirm=true prompts [y/N] before the step runs, in TEXT mode only. A --json run (what the dashboard uses) proceeds past it without prompting, so confirm is a human speed bump, not a safety gate." }, { "command": "workflow-manager add my-workflow './long-scan.sh' --nice-level 10 -w /opt/kodachi/dashboard/hooks", "description": "Run a background friendly step from a specific working directory", "expectedOutput": "Step added with nice_level=10 and working_dir set", "notes": "nice-level range is -20 (highest priority) to 19 (lowest). Negative values need root." }, { "command": "workflow-manager add my-workflow './report.sh' --env 'HOME,PATH,LANG'", "description": "Allow only the listed environment variables through to the step", "expectedOutput": "Step added with env_allowlist [HOME, PATH, LANG]", "notes": "Comma separated. Anything not listed is stripped from the step environment." } ], "id": "2_adding_steps", "title": "Adding Steps" }, { "description": "Every condition the runner understands, expressed as an `add` flag. One condition per step.", "examples": [ { "command": "workflow-manager add my-workflow './check-status.sh' -c always", "description": "Always execute (this is the default)", "expectedOutput": "Step added with condition always" }, { "command": "workflow-manager add my-workflow './deploy.sh' -c if_success", "description": "Execute only if the previous step exited 0", "expectedOutput": "Step added with condition if_success", "notes": "The most common condition for sequential workflows." }, { "command": "workflow-manager add my-workflow './rollback.sh' -c if_fail", "description": "Execute only if the previous step exited non-zero", "expectedOutput": "Step added with condition if_fail", "notes": "Useful for error recovery and rollback." }, { "command": "workflow-manager add my-workflow './alert-success.sh' --if-contains 'success'", "description": "Execute if the previous step's output CONTAINS the text", "expectedOutput": "Step added with condition if_contains", "notes": "Plain substring match, case sensitive. No wildcards: use --if-regex if you need a pattern." }, { "command": "workflow-manager add my-workflow './continue.sh' --if-not-contains 'error'", "description": "Execute if the previous output does NOT contain the text", "expectedOutput": "Step added with condition if_not_contains", "notes": "Substring match, case sensitive." }, { "command": "workflow-manager add my-workflow './handle-done.sh' --if-equals 'ready'", "description": "Execute if the previous output is exactly this value", "expectedOutput": "Step added with condition if_equals", "notes": "Exact match, case sensitive. Output is trimmed before comparison." }, { "command": "workflow-manager add my-workflow './process-result.sh' --if-regex '^status: (ok|success)$'", "description": "Execute if the previous output matches a regex", "expectedOutput": "Step added with condition if_regex" }, { "command": "workflow-manager add my-workflow './alert-few-services.sh' --if-not-regex '(service.*active.*){5,}'", "description": "Execute if the previous output does NOT match a regex (here: fewer than 5 active services)", "expectedOutput": "Step added with condition if_not_regex", "notes": "Quantifiers such as {5,} let you use a regex as a crude counter." }, { "command": "workflow-manager add my-workflow './handle-connected.sh' --if-json-path '$.status=\"connected\"'", "description": "Execute if a field in the previous step's JSON output equals a value", "expectedOutput": "Step added with condition if_json_path_equals", "notes": "The previous output must be valid JSON. The CLI flag is --if-json-path; the serde tag written into the profile is if_json_path_equals." }, { "command": "workflow-manager add my-workflow './finland-detected.sh' --if-json-path '$.data.records[0].country_name=\"Finland\"'", "description": "Execute if a nested JSON field, reached through an array index, matches", "expectedOutput": "Step added with condition if_json_path_equals", "notes": "Supported path syntax: $ root, .field, [index]. Recursive descent (..) and wildcards (*) are NOT supported." }, { "command": "workflow-manager add my-workflow './ip-online.sh' --if-json-path '$.ip_connectivity=true'", "description": "Execute if a JSON boolean is true", "expectedOutput": "Step added with condition if_json_path_equals", "notes": "Booleans and numbers are written unquoted: =true, =2. Strings need quotes: =\"ok\"." }, { "command": "workflow-manager add my-workflow './tor-ready.sh' --if-state tor_running --if-state-expect true", "description": "Execute only when a live system state matches (independent of the previous step)", "expectedOutput": "Step added with condition if_state", "notes": "--if-state-expect takes JSON (true, false, 60, \"wireguard\"). Run `workflow-manager state` to see the state names." }, { "command": "workflow-manager add my-workflow './skip-if-hardened.sh' --if-probe is_hardened --if-probe-expect false", "description": "Execute based on a probe function defined in the profile", "expectedOutput": "Step added with condition if_probe", "notes": "The probe name must exist in the profile's `probes` block, see the Probe Functions category. --if-probe-expect takes JSON." }, { "command": "workflow-manager add my-workflow './low-score-fix.sh' --if-expression \"state.authenticated == true && state.security_score < 60\"", "description": "Execute if a boolean expression over states and probes evaluates true", "expectedOutput": "Step added with condition if_expression", "notes": "Grammar: atoms are probe('NAME') or state.NAME, operators == != < > <= >=, combined with && and || and negated with !. There is no contains() function and no step_id or workflow_status variable." } ], "id": "3_conditional_logic", "title": "Conditional Logic (CLI flags)" }, { "description": "Run workflows and control what happens when a step fails.", "examples": [ { "command": "workflow-manager run my-workflow --dry-run", "description": "List the steps that would run, without executing anything", "expectedOutput": "Dry run: 5 steps would be executed", "notes": "Conditions that depend on previous output cannot be fully resolved in a dry run." }, { "command": "workflow-manager run my-workflow", "description": "Execute every step in order, evaluating each condition first", "expectedOutput": "Workflow completed: Success (5/5 steps, 2 skipped by condition)", "notes": "Steps run real shell commands. Read the template with `show` before running one you did not write." }, { "command": "workflow-manager run my-workflow --kill-policy continue", "description": "Keep going after a failed step instead of stopping", "expectedOutput": "Workflow completed with failures (step 3 failed, remaining steps executed)", "notes": "Values: stop (default and safest), continue, skip_remaining. This overrides global_settings.kill_policy for this run." }, { "command": "workflow-manager run my-workflow --max-log-size 20971520", "description": "Raise the per-run log cap for a very chatty workflow", "expectedOutput": "Workflow completed: Success", "notes": "Bytes, not megabytes. Default is 10485760 (10 MB). Overrides global_settings.max_log_size." }, { "command": "workflow-manager run my-workflow --yes", "description": "Run unattended in text mode, skipping the [y/N] prompt on confirm:true steps", "expectedOutput": "Workflow completed: Success (no confirmation prompts shown)", "notes": "--yes (-y) approves EVERY confirm:true step, including destructive ones, with no prompt. It only affects text mode: the [y/N] prompt is text mode only." }, { "command": "workflow-manager run my-workflow --json", "description": "Run non-interactively and get a machine readable result (this is how the dashboard runs workflows)", "expectedOutput": "JSON envelope with per-step status, exit codes and durations", "notes": "--json is non-interactive: confirm:true steps run WITHOUT any prompt and without --yes. Do not rely on confirm as a safety gate for automated runs." } ], "id": "4_workflow_execution", "title": "Workflow Execution" }, { "description": "Update or delete a single step. Step IDs come from `show`.", "examples": [ { "command": "workflow-manager show my-workflow", "description": "Find the step IDs before editing", "expectedOutput": "Step 1: echo Hello\nStep 2: ./backup.sh\nStep 3: ./cleanup.sh" }, { "command": "workflow-manager update my-workflow 1 'echo Updated Command' -t 300", "description": "Replace step 1's command and timeout", "expectedOutput": "Step 1 updated successfully", "notes": "The command positional is optional: pass only the flags you want to change." }, { "command": "workflow-manager update my-workflow 2 --if-contains 'ERROR' --description 'Alert on error'", "description": "Change a step's condition and its description in place", "expectedOutput": "Step 2 updated successfully (condition if_contains)", "notes": "update accepts the same condition flags as add: -c, --if-contains, --if-not-contains, --if-equals, --if-regex, --if-not-regex, --if-json-path, --if-probe(-expect), --if-state(-expect), --if-expression." }, { "command": "workflow-manager update my-workflow 2 --clear-condition -c always", "description": "Drop a step's condition payload and reset it to a plain condition type", "expectedOutput": "Step 2 updated successfully (condition always)", "notes": "--clear-condition removes the stored pattern/path/probe value. Without it, switching from if_contains back to always can leave a stale payload." }, { "command": "workflow-manager update my-workflow 3 -m 'Verify the archive, then press Enter' --confirm true", "description": "Update a pause step's message and require confirmation", "expectedOutput": "Step 3 updated successfully", "notes": "-m/--message applies to pause steps, --profile applies to include steps, the command positional applies to command steps." }, { "command": "workflow-manager delete-step my-workflow 2", "description": "Remove step 2 from the workflow", "expectedOutput": "Step 2 deleted from 'my-workflow'", "notes": "Steps are renumbered after a delete, so re-run `show` before deleting another one." } ], "id": "5_step_management", "title": "Managing Individual Steps" }, { "description": "Two non-command step types: a pause that waits for the user, and an include that expands another profile inline.", "examples": [ { "command": "workflow-manager pause my-workflow -m 'Review results before continuing'", "description": "Add an interactive pause point", "expectedOutput": "Pause step added to template 'my-workflow'", "notes": "The run blocks until the user presses Enter, so a paused workflow is not suitable for unattended or --json runs." }, { "command": "workflow-manager pause backup -m 'Verify backup integrity' -c if_success", "description": "Pause only when the previous step succeeded", "expectedOutput": "Pause step added with condition if_success" }, { "command": "workflow-manager include my-workflow shared-prereqs --description 'Reusable setup steps'", "description": "Compose another profile into this template", "expectedOutput": "Include step 3 added to template 'my-workflow'", "notes": "The named profile must exist. Its steps are expanded in place when the workflow runs." }, { "command": "workflow-manager include my-workflow tor-recovery -c if_fail", "description": "Pull in a recovery profile only when the previous step failed", "expectedOutput": "Include step added with condition if_fail", "notes": "include accepts -c/--condition plus --if-probe(-expect), --if-state(-expect) and --if-expression." } ], "id": "6_pause_and_include", "title": "Pause and Include Steps" }, { "description": "Build a complete workflow in one shell line by chaining create and add with &&.", "examples": [ { "command": "workflow-manager create tor-recovery && workflow-manager add tor-recovery './routing-switch recover internet' -t 60 && workflow-manager add tor-recovery './health-control net-check' -c if_success && workflow-manager add tor-recovery './tor-switch start' -c if_success -t 120", "description": "Create a template and add three conditional steps in one chain", "expectedOutput": "Template created, 3 steps added successfully", "notes": "`create` must come first: `add` refuses to run against a template that does not exist." }, { "command": "workflow-manager create diagnostics && workflow-manager add diagnostics './health-control net-check' -t 30 && workflow-manager add diagnostics './tor-switch tor-status' -c if_success && workflow-manager add diagnostics './dns-leak test' -c if_success && workflow-manager add diagnostics './integrity-check check-all' -c if_success", "description": "Build a 4 step diagnostics workflow", "expectedOutput": "diagnostics created, 4 steps added" }, { "command": "workflow-manager create backup && workflow-manager add backup 'tar czf backup.tar.gz /data' && workflow-manager pause backup -m 'Check backup size' -c if_success && workflow-manager add backup 'rsync backup.tar.gz remote:/backups' -c if_success && workflow-manager add backup 'rm backup.tar.gz' -c if_success", "description": "Mix command steps and a pause to build an interactive backup workflow", "expectedOutput": "Backup workflow with 4 steps created" } ], "id": "7_batch_building", "title": "Efficient Batch Building" }, { "description": "End to end workflows built from real Kodachi hook commands.", "examples": [ { "command": "workflow-manager create ip-verify && workflow-manager add ip-verify 'ip-fetch --json' -t 60 && workflow-manager add ip-verify 'echo Finland detected' --if-json-path '$.data.records[0].country_name=\"Finland\"' && workflow-manager run ip-verify", "description": "Fetch the public IP and branch on the geolocated country", "expectedOutput": "Finland detected", "notes": "Needs network access. ip-fetch does not need root." }, { "command": "workflow-manager create auth-check && workflow-manager add auth-check 'online-auth check-login --json' -t 30 && workflow-manager add auth-check 'echo Session valid' --if-contains 'valid' && workflow-manager run auth-check", "description": "Confirm there is a valid authenticated session", "expectedOutput": "Session valid", "notes": "Many hook commands refuse to run without an authenticated session, so this is a useful first step in a longer workflow." }, { "command": "workflow-manager create health-audit && workflow-manager add health-audit 'sudo health-control net-check --json' -t 60 && workflow-manager add health-audit 'echo Network online' --if-json-path '$.ip_connectivity=true' && workflow-manager add health-audit 'sudo routing-switch status --json' -c if_success -t 30 && workflow-manager run health-audit", "description": "Chain a network check into a routing status check", "expectedOutput": "Network online", "notes": "The steps themselves need root here (health-control and routing-switch do), workflow-manager does not." }, { "command": "workflow-manager create tor-verify && workflow-manager add tor-verify 'sudo tor-switch get-tor-status --json' -t 30 && workflow-manager add tor-verify 'echo Tor responding' --if-json-path '$.data.is_responding=true' && workflow-manager run tor-verify", "description": "Verify the Tor daemon is up and answering", "expectedOutput": "Tor responding", "notes": "Requires Tor to be installed and its control port reachable." } ], "id": "8_kodachi_workflows", "title": "Real-World Kodachi Workflows" }, { "description": "A profile can declare system state that must hold before any step runs. The block is `prerequisites` and it has exactly three fields: `required` (array), `optional` (array, warnings only) and `on_failure`. There is no flat form: keys such as \"authenticated\": true at the top of the block do not deserialize.", "examples": [ { "command": "workflow-manager prereq check initial_terminal_setup_wireguard_torrify", "description": "Validate a profile's prerequisites without running the workflow", "expectedOutput": "All prerequisites met, or the list of failed checks with their error messages", "notes": "`prereq validate <TEMPLATE>` is accepted as an alias for `prereq check`." }, { "command": "workflow-manager show initial_terminal_setup_wireguard_torrify --json", "description": "Read the exact prerequisites shape the runner expects", "expectedOutput": "The profile JSON, including the prerequisites block", "notes": "The shape is: \"prerequisites\": {\"required\": [{\"check\": \"state.online\", \"expect\": true, \"error\": \"Internet connection required\"}, {\"check\": \"state.torrify\", \"expect\": false, \"error\": \"System must not be torrified\"}], \"on_failure\": \"abort\"}. Each entry needs `check` and `error`; `expect` is optional and defaults to a truthy check." }, { "command": "workflow-manager state", "description": "List the state names usable as a prerequisite `check` value", "expectedOutput": "A JSON object of all system states, for example {\"online\": true, \"torrify\": false, \"tor_running\": true, ...}", "notes": "A check is written as \"state.<NAME>\" (the bare \"<NAME>\" form is also accepted). Optional checks go in the `optional` array: they warn but never block." }, { "command": "workflow-manager run initial_terminal_setup_wireguard_torrify --dry-run", "description": "See how on_failure behaves before committing to a real run", "expectedOutput": "Prerequisites validated, or 'Prerequisites not met' followed by the failed checks", "notes": "on_failure accepts \"abort\" (default) and \"warn\". Only \"abort\" stops the run: any other value, including a typo, lets the workflow continue. If the profile has no prerequisites block, no checks are performed." } ], "id": "9_prerequisites", "title": "Prerequisites" }, { "description": "Query the live system state that conditions, probes and prerequisites read from.", "examples": [ { "command": "workflow-manager state", "description": "Show every system state as JSON", "expectedOutput": "{\"online\": true, \"torrify\": false, \"dnscrypt\": true, \"routing_mode\": \"wireguard\", \"tor_running\": true}" }, { "command": "workflow-manager state online", "description": "Query a single state field (cheaper: only that field is probed)", "expectedOutput": "{\"state\": \"online\", \"value\": true}", "notes": "20 states are available: online, routing_mode, vpn_connected, dnscrypt, ipv6_disabled, dns_kodachi_managed, firewall_active, kill_switch_armed, network_hardened, disk_encrypted, security_score, torrify, tor_running, tor_dns_active, tor_verified, mac_spoofing, bluetooth_enabled, wifi_enabled, authenticated, tor_instances_count." }, { "command": "workflow-manager state security_score --json", "description": "Read a numeric state, for use with --if-expression comparisons", "expectedOutput": "{\"state\": \"security_score\", \"value\": 62}", "notes": "Numeric states support < > <= >= inside --if-expression, for example \"state.security_score < 60\"." } ], "id": "10_state_checking", "title": "System State Checking" }, { "description": "A probe is a named, reusable check declared in the profile's `probes` block and referenced by --if-probe. A ProbeDefinition has exactly three fields: `probe_type` (\"builtin\", \"expression\" or \"count\"), `expression` (required for all three types) and an optional `description`. There is no `check` field.", "examples": [ { "command": "workflow-manager add my-workflow 'echo Already hardened, skipping' --if-probe is_hardened --if-probe-expect true", "description": "Reference a probe from a step condition", "expectedOutput": "Step added with condition if_probe", "notes": "Add the probes block to config/profiles/my-workflow.json first: \"probes\": {\"harden_count\": {\"probe_type\": \"count\", \"expression\": \"count('harden', previous_output)\", \"description\": \"Count 'harden' occurrences\"}, \"is_hardened\": {\"probe_type\": \"expression\", \"expression\": \"probe('harden_count') >= 4\"}}" }, { "command": "workflow-manager add my-workflow './use-tor-path.sh' --if-probe tor_up --if-probe-expect true", "description": "Use the one builtin probe: a live Tor connection check", "expectedOutput": "Step added with condition if_probe", "notes": "Declare it as \"tor_up\": {\"probe_type\": \"builtin\", \"expression\": \"tor_connection_check\"}. tor_connection_check is the ONLY builtin: any other expression under probe_type \"builtin\" fails at run time with 'Unknown builtin probe'. It shells out to ip-fetch check-tor, so it needs network access, and its result is cached for the run." }, { "command": "workflow-manager show my-workflow --json", "description": "Confirm the probes block deserializes the way the runner expects", "expectedOutput": "The profile JSON with its `probes` map, each entry showing probe_type and expression", "notes": "probe_type \"count\" evaluates count('<TEXT>', previous_output) and returns a number. probe_type \"expression\" evaluates the same grammar as --if-expression, so it can reference other probes with probe('NAME') and states with state.NAME." } ], "id": "11_probe_functions", "title": "Probe Functions (profile JSON)" }, { "description": "The `global_settings` block sets workflow wide defaults: kill_policy (\"stop\" by default), continue_policy (false by default), max_log_size (10485760 bytes), default_timeout (seconds) and working_dir. Step level values override them.", "examples": [ { "command": "workflow-manager show policy-demo --json", "description": "Read the global_settings block of an existing profile", "expectedOutput": "\"global_settings\": {\"kill_policy\": \"stop\", \"continue_policy\": false, \"max_log_size\": 10485760, \"default_timeout\": 300, \"working_dir\": \".\"}", "notes": "continue_policy is the master override: when true the workflow always continues and kill_policy is ignored. When false, kill_policy decides: \"stop\" ends the run, \"continue\" carries on, \"skip_remaining\" skips the rest without failing." }, { "command": "workflow-manager run policy-demo --kill-policy stop", "description": "Force the safest failure policy for one run, whatever the profile says", "expectedOutput": "Workflow stopped at the first failing step", "notes": "For security critical workflows use kill_policy \"stop\" with continue_policy false. For recovery workflows, \"continue\" is usually what you want." }, { "command": "workflow-manager add slow-scan './deep-scan.sh' -t 60", "description": "Give one step its own timeout, overriding default_timeout", "expectedOutput": "Step added with timeout 60s", "notes": "A step with no timeout inherits global_settings.default_timeout. A timed out command is sent SIGTERM, then SIGKILL if it does not exit." } ], "id": "12_global_settings", "title": "Global Settings (profile JSON)" }, { "description": "The 12 condition tags the runner accepts, exactly as they are written in the profile's `condition` object. Anything else fails to deserialize: always, if_success, if_fail, if_contains, if_not_contains, if_equals, if_regex, if_not_regex, if_json_path_equals, if_probe, if_state, if_expression.", "examples": [ { "command": "workflow-manager show my-workflow --json", "description": "See the condition object the CLI flags actually write", "expectedOutput": "\"condition\": {\"type\": \"if_contains\", \"pattern\": \"SUCCESS\"}", "notes": "Field per tag: always / if_success / if_fail take none. if_contains, if_not_contains, if_regex, if_not_regex take `pattern`. if_equals takes `value`. if_json_path_equals takes `path` and `value`. if_probe takes `probe` and `expect`. if_state takes `state` and `expect`. if_expression takes `expression`." }, { "command": "workflow-manager add my-workflow './alert.sh' --if-contains 'SUCCESS'", "description": "Substring matching, written as if_contains / if_not_contains", "expectedOutput": "Step added: {\"type\": \"if_contains\", \"pattern\": \"SUCCESS\"}", "notes": "This is a plain substring test, case sensitive. It is NOT glob: * and ? are literal characters here. For wildcards use if_regex." }, { "command": "workflow-manager add my-workflow './connected.sh' --if-json-path '$.status.connected=true'", "description": "JSON path equality, written as if_json_path_equals", "expectedOutput": "Step added: {\"type\": \"if_json_path_equals\", \"path\": \"$.status.connected\", \"value\": true}", "notes": "The stored field is `value`, not `expect`. Path syntax is a strict subset: $ root, .field, [index]. Recursive descent (..) and wildcards are not supported." }, { "command": "workflow-manager add my-workflow './score-fix.sh' --if-expression \"probe('harden_count') >= 4 || state.security_score < 60\"", "description": "Boolean expression, written as if_expression", "expectedOutput": "Step added: {\"type\": \"if_expression\", \"expression\": \"probe('harden_count') >= 4 || state.security_score < 60\"}", "notes": "Atoms: probe('NAME') and state.NAME. Operators: == != < > <= >=, joined with && and ||, negated with a leading !. Comparisons on booleans and strings support only == and !=." } ], "id": "13_condition_reference", "title": "Condition Reference (profile JSON)" }, { "description": "A step object has two required fields, `id` and `type` (\"command\", \"pause\" or \"include\"), plus `condition` (defaults to always if absent). Everything else is optional: cmd, description, timeout, confirm, env_allowlist, working_dir, nice_level, message, profile, parameters, and the ColonyOps hints cell_store, score_impact and colonyops_safety.", "examples": [ { "command": "workflow-manager show my-workflow --json", "description": "Read a complete step object as the runner stores it", "expectedOutput": "{\"id\": 1, \"type\": \"command\", \"cmd\": \"health-control net-check\", \"description\": \"Check network connectivity\", \"condition\": {\"type\": \"always\"}, \"timeout\": 60, \"confirm\": false, \"nice_level\": 0}", "notes": "`description` is optional, not required. A command step needs `cmd`, a pause step needs `message`, an include step needs `profile` (and may carry `parameters`)." }, { "command": "workflow-manager add my-workflow './panic.sh' --confirm --nice-level -10", "description": "Write the confirm and nice_level step fields from the CLI", "expectedOutput": "Step added: {\"confirm\": true, \"nice_level\": -10}", "notes": "confirm:true prompts [y/N] in text mode only, and `run --yes` skips that prompt. A --json run never prompts. nice_level goes from -20 to 19; negative values need root." }, { "command": "workflow-manager add my-workflow './report.sh' -w /opt/kodachi/dashboard/hooks --env 'HOME,PATH'", "description": "Write the working_dir and env_allowlist step fields", "expectedOutput": "Step added: {\"working_dir\": \"/opt/kodachi/dashboard/hooks\", \"env_allowlist\": [\"HOME\", \"PATH\"]}", "notes": "A step without working_dir inherits global_settings.working_dir. env_allowlist is a whitelist: variables not listed are not passed to the step." }, { "command": "workflow-manager include my-workflow base-recovery-sequence", "description": "Write an include step, which expands another profile at run time", "expectedOutput": "Step added: {\"type\": \"include\", \"profile\": \"base-recovery-sequence\", \"condition\": {\"type\": \"always\"}}", "notes": "Include lets you keep a library of small reusable profiles and compose them. The included profile must already exist." } ], "id": "14_step_reference", "title": "Step Reference (profile JSON)" } ], "description": "Usage examples for workflow-manager", "name": "workflow-manager", "quickReference": [ "workflow-manager --help", "workflow-manager --version", "workflow-manager --info --json", "workflow-manager --examples", "workflow-manager list", "workflow-manager show <TEMPLATE>", "workflow-manager run <TEMPLATE> --dry-run", "workflow-manager state" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:40.565977889Z", "version": "9.8.4 (build 320)", "warnings": [] } }, { "name": "ai-gateway", "path": "/opt/kodachi/dashboard/hooks/ai-gateway", "timestamp": "2026-07-21T01:54:40Z", "file_info": { "size": 5858288, "sha256": "12f0a34133f789f27c6c09ed690a337b0d86792067b4ed2e6f60a14705f69a05" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:41.039285859Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-gateway", "version": "9.8.4", "author": "Warith Al Maawali", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "Proprietary", "features": [ "Embedded command catalog with 568 commands from 25 services", "TF-IDF + substring hybrid search across all services", "Three-tier risk classification (Passive/Active/Dangerous)", "Policy firewall with allowlist enforcement", "Workspace confinement and path validation", "Failure cooldown to prevent cascading degradation", "Per-agent identity, rate limiting, and audit trail for executions", "Approval ticket workflow for agent-to-human authorization", "Configurable per-operation timeouts with env var override", "Full JSON/JSON-pretty/JSON-human output support" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:41.182810411Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-gateway", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:41.323460167Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-gateway", "description": "Unified AI gateway for command catalog, policy firewall, and safe execution", "usage": "ai-gateway [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Administration", "commands": [ { "name": "index", "description": "Rebuild the search index from the embedded registry", "usage": "ai-gateway index rebuild", "options": [ { "flag": "rebuild", "description": "Rebuild the TF-IDF search index over the command catalog and print the service and command counts. Run this after upgrading the hook binaries.", "required": true } ], "requires_sudo": false, "examples": [ "ai-gateway index rebuild", "ai-gateway index rebuild --json", "ai-gateway index rebuild --json-pretty" ] }, { "name": "policy", "description": "Show the current safety policy configuration", "usage": "ai-gateway policy show", "options": [ { "flag": "show", "description": "Display the policy firewall: risk-tier rules, the service allowlist, and whether KODACHI_PENTEST_MODE is currently enabled. Read-only.", "required": true } ], "requires_sudo": false, "examples": [ "ai-gateway policy show", "ai-gateway policy show --json", "ai-gateway policy show --json-pretty" ] }, { "name": "doctor", "description": "Health check that verifies all registered binaries exist and respond", "usage": "ai-gateway doctor", "options": [ { "flag": "(no command-specific options)", "description": "doctor probes every registered binary and reports whether it exists, responds, and at which version. Use the global --json, --json-pretty or --json-human to pick the output shape." } ], "requires_sudo": false, "examples": [ "ai-gateway doctor", "ai-gateway doctor --json", "ai-gateway doctor --json-pretty" ] }, { "name": "approve", "description": "Issue or verify human approval tickets for agent execution", "usage": "ai-gateway approve issue <service> <command> [--agent-id <id>] [--ttl <secs>]\nai-gateway approve verify --ticket <ticket> <service> <command> [--agent-id <id>]", "options": [ { "flag": "issue <SERVICE> <COMMAND>", "description": "Issue a signed, time-limited approval ticket for one service and command (requires KODACHI_GATEWAY_APPROVAL_SECRET)", "required": true }, { "flag": "verify --ticket <TICKET> <SERVICE> <COMMAND>", "description": "Verify a ticket against the service and command it was issued for", "required": true }, { "flag": "--agent-id <ID>", "description": "Agent identity the ticket is bound to", "default": "anonymous" }, { "flag": "--ttl <SECS>", "description": "Ticket lifetime in seconds, 1 to 3600 (issue only)", "default": "300" } ], "requires_sudo": false, "examples": [ "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "ai-gateway approve verify --ticket \"$TICKET\" health-control block-internet --agent-id kodachi-claw --json" ] } ] }, { "category": "Discovery", "commands": [ { "name": "list", "description": "List all services and their commands from the embedded registry", "usage": "ai-gateway list [--service <name>] [--category <name>]", "options": [ { "flag": "--service", "description": "Filter by service name" }, { "flag": "--category", "description": "Filter by category name" } ], "requires_sudo": false, "examples": [ "ai-gateway list", "ai-gateway list --json", "ai-gateway list --service tor-switch", "ai-gateway list --service health-control --json", "ai-gateway list --category passive" ] }, { "name": "search", "description": "Search across all services and commands using TF-IDF + substring matching", "usage": "ai-gateway search <query> [--limit <N>]", "options": [ { "flag": "--limit", "description": "Maximum number of results to return", "default": "20" } ], "requires_sudo": false, "examples": [ "ai-gateway search \"tor status\"", "ai-gateway search \"dns leak\" --json", "ai-gateway search \"network check\" --limit 5", "ai-gateway search \"panic\" --json-pretty" ] }, { "name": "help", "description": "Show detailed help for a service or specific command", "usage": "ai-gateway help <service> [command]", "options": [ { "flag": "<SERVICE>", "description": "Service name from the embedded catalog, for example tor-switch. An --agent-id value such as zeroclaw is not a service and returns \"Service not found\".", "required": true }, { "flag": "[COMMAND]", "description": "Optional command name. Omit it for the whole service spec.", "required": false } ], "requires_sudo": false, "examples": [ "ai-gateway help tor-switch", "ai-gateway help tor-switch tor-status --json", "ai-gateway help health-control --json-pretty", "ai-gateway help dns-leak test", "ai-gateway help ip-fetch fetch --json" ] }, { "name": "capabilities", "description": "Show effective capabilities for an AI agent identity", "usage": "ai-gateway capabilities [--agent-id <id>] [--agent-token <token>]", "options": [ { "flag": "--agent-id", "description": "Agent profile (kodachi-claw/nullclaw/agentzero/openclaw/picoclaw/nanoclaw/claude-code/gpt/gemini/open-interpreter; aliases: zeroclaw, nanclaw, \"claude code\", \"open interpreter\")", "default": "anonymous" }, { "flag": "--agent-token", "description": "Optional token for authenticated agent profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway capabilities --agent-id kodachi-claw --agent-token $KODACHI_AGENT_TOKEN_KODACHI_CLAW --json", "ai-gateway capabilities --agent-id nullclaw --agent-token $KODACHI_AGENT_TOKEN_NULLCLAW", "ai-gateway capabilities --agent-id openclaw --agent-token $KODACHI_AGENT_TOKEN_OPENCLAW --json", "ai-gateway capabilities --agent-id picoclaw --agent-token $KODACHI_AGENT_TOKEN_PICOCLAW --json", "ai-gateway capabilities --agent-id nanoclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id nanclaw --agent-token $KODACHI_AGENT_TOKEN_NANOCLAW --json", "ai-gateway capabilities --agent-id claude-code --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id \"claude code\" --agent-token $KODACHI_AGENT_TOKEN_CLAUDE_CODE --json", "ai-gateway capabilities --agent-id gpt --agent-token $KODACHI_AGENT_TOKEN_GPT --json", "ai-gateway capabilities --agent-id gemini --agent-token $KODACHI_AGENT_TOKEN_GEMINI --json", "ai-gateway capabilities --agent-id open-interpreter --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id \"open interpreter\" --agent-token $KODACHI_AGENT_TOKEN_OPEN_INTERPRETER --json", "ai-gateway capabilities --agent-id anonymous --json" ] } ] }, { "category": "Execution", "commands": [ { "name": "run", "description": "Validate and execute a binary command through the safety layer", "usage": "ai-gateway run <service> --command <cmd> [--args <args>...] [--args-json <json>] [--dry-run] [--timeout <secs>] [--agent-id <id>] [--agent-token <token>] [--approval-ticket <ticket>] OR ai-gateway run --batch-json <json> --agent-id <id> --agent-token <token>", "options": [ { "flag": "<SERVICE>", "description": "Service to invoke (required unless --batch-json is used)" }, { "flag": "--command <CMD>", "description": "Command to execute (required unless --batch-json is used)" }, { "flag": "--args", "description": "Command arguments (multiple)" }, { "flag": "--args-json", "description": "Command arguments as JSON object/array" }, { "flag": "--batch-json", "description": "Batch execution payload for trusted agents (JSON array, sequential mode only)" }, { "flag": "--dry-run", "description": "Validate without executing" }, { "flag": "--timeout", "description": "Execution timeout in seconds", "default": "60" }, { "flag": "--confirm", "description": "Approval token for commands requiring confirmation" }, { "flag": "--approval-ticket", "description": "Human-issued approval ticket for Active/Dangerous commands" }, { "flag": "--agent-id", "description": "Agent profile (trusted profiles require token auth)", "default": "anonymous" }, { "flag": "--agent-token", "description": "Agent auth token for token-required profiles" } ], "requires_sudo": false, "examples": [ "ai-gateway run health-control --command net-check --dry-run", "ai-gateway run ip-fetch --command fetch --dry-run --json", "ai-gateway run tor-switch --command tor-status --timeout 60 --json", "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --dry-run --json", "ai-gateway run dns-leak --command test --dry-run --json-pretty", "ai-gateway run tor-switch --command tor-status --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --dry-run --json", "KODACHI_TRUSTED_BATCH_MODE=true ai-gateway run --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --batch-json '[{\"service\":\"ip-fetch\",\"command\":\"fetch\",\"dry_run\":true},{\"service\":\"tor-switch\",\"command\":\"tor-status\",\"dry_run\":true}]' --json", "KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --args-json '{\"file\":\"results/example-to-wipe.txt\"}' --confirm \"I understand\" --dry-run --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format <FORMAT>", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter <FIELD1,FIELD2>", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields <FIELD_LIST>", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--offset <NUMBER>", "description": "Skip first N results (for pagination)" }, { "flag": "--port <PORT>", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level <LEVEL>", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config <FILE>", "description": "Use custom configuration file" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "3": "Permission denied", "5": "File not found", "1": "General error", "2": "Invalid arguments", "0": "Success", "4": "Network error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:41.628281649Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-gateway", "description": "Usage examples for ai-gateway", "categories": [ { "id": "0_quick_start", "title": "Quick Start", "description": "The gateway is the one safe door into every other Kodachi binary: find a command, read its spec, preview it, then run it. ai-gateway itself never needs root, but the service it launches may.", "examples": [ { "command": "ai-gateway search \"tor exit node\" --limit 5 --json", "description": "Find the command you want without knowing which service owns it", "expectedOutput": "Top 5 ranked matches, each with service, command, description and score" }, { "command": "ai-gateway help tor-switch tor-status --json", "description": "Read the full spec of a command before you invoke it", "expectedOutput": "JSON command spec with options, examples and risk tier" }, { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Preview the invocation: policy check, no execution", "expectedOutput": "Validation result showing the resolved binary and argv that would run" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "Run it for real once the dry-run looks right", "expectedOutput": "The live tor-status output, wrapped in the gateway envelope", "notes": "Passive commands need no confirmation and no env var. Active commands need --confirm, and Dangerous commands additionally need KODACHI_PENTEST_MODE=true." } ] }, { "id": "1_discovery", "title": "Service Discovery", "description": "Browse the embedded catalog of every Kodachi service and command. The catalog is compiled into the binary, so list works offline and without authentication.", "examples": [ { "command": "ai-gateway list --json", "description": "List every service in the catalog with its commands", "expectedOutput": "JSON array of the registered services, each with its command list and metadata" }, { "command": "ai-gateway list --service tor-switch --json", "description": "Narrow the catalog to one service", "expectedOutput": "The tor-switch commands with descriptions and risk tiers" }, { "command": "ai-gateway list --category Discovery", "description": "Filter by command category instead of by service", "expectedOutput": "The commands whose category matches, across all services", "notes": "--category (-c) matches the category name a service assigns to its own commands, so the useful values differ per service. Run 'ai-gateway list --service <name>' first to see which categories that service uses." }, { "command": "ai-gateway list --service health-control", "description": "Same listing in readable text instead of JSON", "expectedOutput": "A formatted list of the health-control commands" } ] }, { "id": "2_search", "title": "Command Search", "description": "Search across all services using TF-IDF + substring hybrid search engine", "examples": [ { "command": "ai-gateway search \"tor exit node\" --json", "description": "Search for Tor exit node commands", "expectedOutput": "Ranked results with relevance scores", "notes": "Uses TF-IDF cosine similarity + substring matching" }, { "command": "ai-gateway search \"dns leak\" --limit 5 --json", "description": "Search with limited results", "expectedOutput": "Top 5 matching commands for DNS leak operations" }, { "command": "ai-gateway search \"network check\"", "description": "Search for network check commands in text format", "expectedOutput": "Numbered list of matching commands with scores" }, { "command": "ai-gateway search \"panic\" --json", "description": "Find all panic/emergency commands", "expectedOutput": "Emergency commands with Dangerous risk tier", "notes": "Dangerous commands are blocked unless pentest mode" } ] }, { "id": "3_help", "title": "Service Help", "description": "Get detailed help for any service or specific command", "examples": [ { "command": "ai-gateway help tor-switch --json", "description": "Full specification for tor-switch service", "expectedOutput": "JSON with all commands, options, examples, features, requirements" }, { "command": "ai-gateway help health-control security-status --json", "description": "Help for a specific command", "expectedOutput": "Detailed command spec with parameters and examples" }, { "command": "ai-gateway help dns-switch", "description": "Text help for dns-switch service", "expectedOutput": "Formatted help output for dns-switch" }, { "command": "ai-gateway help ip-fetch --json-pretty", "description": "Pretty-printed JSON help for ip-fetch", "expectedOutput": "Indented JSON with full service specification" } ] }, { "id": "4_execution", "title": "Safe Command Execution", "description": "Validate first, then execute when appropriate. No env var is needed for passive/active commands.", "examples": [ { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Step 1 (validate): preview a passive command", "expectedOutput": "Validation result without actual execution", "notes": "Always use --dry-run first for safety" }, { "command": "ai-gateway run tor-switch --command tor-status --json", "description": "Step 2 (apply): execute passive command (no env needed)", "expectedOutput": "Live command execution result", "notes": "Passive commands execute without KODACHI_PENTEST_MODE" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --confirm --dry-run --json", "description": "Active command flow (no env needed): validate with explicit confirmation", "expectedOutput": "Validated active operation with parsed args-json", "notes": "For active commands, remove --dry-run to apply changes" }, { "command": "ai-gateway run dns-leak --command test --dry-run --timeout 60 --json", "description": "Dry-run DNS leak test with custom timeout", "expectedOutput": "Validation result for dns-leak test", "notes": "Timeout can be overridden with KODACHI_TOOL_TIMEOUT_MS env var" }, { "command": "ai-gateway run ip-fetch --command fetch --dry-run --json", "description": "Dry-run ip-fetch fetch command", "expectedOutput": "Validation result for ip-fetch fetch", "notes": "Dry-run keeps examples deterministic in offline/auth-restricted environments" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args-json '[\"de\"]' --dry-run --json", "description": "Pass structured JSON arguments for agent-safe invocation", "expectedOutput": "Dry-run validation with args expanded from JSON", "notes": "--args-json avoids brittle shell quoting in agent pipelines" }, { "command": "ai-gateway run tor-switch --command set-exit-node --args de --dry-run --json", "description": "Pass plain positional arguments straight through to the service", "expectedOutput": "Dry-run validation showing the argv the service would receive, including the passed-through arguments", "notes": "--args (-a) takes any number of values and forwards them verbatim, so everything after it is consumed as an argument until the next flag. Use --args-json instead when the values could be mistaken for gateway flags." }, { "command": "ai-gateway run health-control --command net-check --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --dry-run --json", "description": "Run under an agent identity so the call is rate-limited and audited", "expectedOutput": "Dry-run validation plus the identity that was authenticated and the risk tier it is allowed to reach", "notes": "The token is read server-side from the env var KODACHI_AGENT_TOKEN_<AGENT_ID>, uppercased with '-' replaced by '_'. It must be EXPORTED: if it is unset, the shell expands it to nothing and clap fails with \"a value is required\"." } ] }, { "id": "5_policy", "title": "Safety Policy", "description": "Read the policy firewall: which services are allowlisted, how commands are classified into the Passive, Active and Dangerous risk tiers, and what each tier demands before it will run.", "examples": [ { "command": "ai-gateway policy show --json", "description": "Show the active safety policy as JSON", "expectedOutput": "The risk-tier rules, the service allowlist, and whether pentest mode is currently on" }, { "command": "ai-gateway policy show", "description": "Show the same policy as readable text", "expectedOutput": "A formatted policy summary" }, { "command": "ai-gateway policy show --json-pretty", "description": "Indented policy JSON, easier to read while debugging a block", "expectedOutput": "Indented JSON with the complete policy details", "notes": "If a run was refused, this is the command that tells you why: check the command's tier and whether its service is on the allowlist." }, { "command": "KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-file --args-json '{\"file\":\"results/example-to-wipe.txt\"}' --confirm \"I understand\" --dry-run --json", "description": "Preview a Dangerous command: it needs the env var AND an explicit confirmation token", "expectedOutput": "Validation of the dangerous invocation, with nothing executed because of --dry-run", "notes": "KEEP --dry-run. The example target is only illustrative. Without dry-run this really does wipe the target file, and wipe-file is irreversible. KODACHI_PENTEST_MODE=true is required only for the Dangerous tier, and --confirm must be exactly \"I understand\" or dangerous:<service>:<command>." } ] }, { "id": "6_administration", "title": "Administration and Troubleshooting", "description": "Keep the search index fresh and find out why a service will not run. These are the commands to reach for when a run fails and you do not know whether the fault is policy, the index, or a missing binary.", "examples": [ { "command": "ai-gateway index rebuild --json", "description": "Rebuild the TF-IDF search index over the command catalog", "expectedOutput": "Index statistics: how many services and commands were indexed", "notes": "Do this after upgrading the hook binaries, otherwise search still ranks against the previous catalog." }, { "command": "ai-gateway doctor --json", "description": "Probe every registered binary and report whether it is usable", "expectedOutput": "Per-binary health: whether the file exists, whether it responds, its version and its size", "notes": "This is what to run when a run failed with \"Binary not found\": doctor shows exactly which entries have no binary behind them." }, { "command": "ai-gateway doctor", "description": "Same health check as a readable table", "expectedOutput": "A table of binary names against their health status", "notes": "doctor executes each binary with a probe flag, so it is slower than the other commands here." } ] }, { "id": "7_output_formats", "title": "Output Formats and Metadata", "description": "Every command accepts the same three JSON shapes, plus the binary's own metadata flags. Pick compact JSON for scripts, pretty for reading, and human when you want it formatted like jq.", "examples": [ { "command": "ai-gateway doctor --json", "description": "Compact JSON: one line, best for piping into a script", "expectedOutput": "A single-line JSON envelope" }, { "command": "ai-gateway search \"dns leak\" --json-pretty", "description": "Indented JSON for reading a result by eye", "expectedOutput": "The same envelope, indented across multiple lines" }, { "command": "ai-gateway policy show --json-human", "description": "Formatted, jq-style JSON", "expectedOutput": "The policy envelope, highlighted and formatted for a human" }, { "command": "ai-gateway --info --json", "description": "Report what this build of the gateway can do", "expectedOutput": "JSON with the feature list, security properties and requirements" }, { "command": "ai-gateway --version", "description": "Print the gateway version", "expectedOutput": "The ai-gateway version string" } ] }, { "id": "8_ai_agent_integration", "title": "AI Agent Integration", "description": "The loop an AI agent runs: search for the command, read its spec, dry-run it, then execute under an agent identity. IMPORTANT: an agent name (kodachi-claw, nullclaw, agentzero, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter) is a value for --agent-id, NOT a service you can 'run'. The service argument of 'run' must be a Kodachi binary from the catalog, such as tor-switch or ip-fetch. Use 'ai-gateway list' to see what is runnable.", "examples": [ { "command": "ai-gateway search \"check tor status\" --limit 1 --json", "description": "Step 1: the agent finds the best matching command", "expectedOutput": "The single top match, with its service, command and score", "notes": "ai-cmd delegates its execution to ai-gateway, so an agent that goes through the gateway gets the same safety checks either way." }, { "command": "ai-gateway help tor-switch tor-status --json", "description": "Step 2: the agent reads the machine-readable command spec", "expectedOutput": "The command spec: parameters, defaults, examples and risk tier", "notes": "'help' resolves the name against the embedded service catalog. An --agent-id value such as zeroclaw is not a service, so 'help zeroclaw' returns \"Service not found\"." }, { "command": "ai-gateway run tor-switch --command tor-status --dry-run --json", "description": "Step 3: the agent validates the invocation before committing to it", "expectedOutput": "Validation passes and shows exactly what would have run" }, { "command": "ai-gateway run tor-switch --command tor-status --agent-id claude-code --agent-token \"$KODACHI_AGENT_TOKEN_CLAUDE_CODE\" --json", "description": "Step 4: the agent executes under its own identity, so the call is rate-limited and audited", "expectedOutput": "The live tor-status result, plus the identity and rate limit that were applied", "notes": "Every named profile except 'anonymous' requires a token. Export KODACHI_AGENT_TOKEN_CLAUDE_CODE first: if it is unset the shell drops the word and clap fails with \"a value is required\"." }, { "command": "ai-gateway capabilities --agent-id nullclaw --agent-token \"$KODACHI_AGENT_TOKEN_NULLCLAW\" --json", "description": "Ask the gateway what a given agent identity is actually allowed to do", "expectedOutput": "The effective services, the highest risk tier allowed, and the per-minute rate limit", "notes": "This is the correct way to work with an agent name. 'run nullclaw' is not: nullclaw is an identity, and it is only a runnable service if you have separately installed a third-party binary of that name (see the External agent runtimes category)." } ] }, { "id": "8b_external_runtimes", "title": "External Agent Runtimes", "description": "Kodachi does not ship any agent runtime binary. The policy allowlist reserves three optional third-party names (kodachi-claw, nullclaw, aeroclaw) and the registry discovers them at runtime, but only if you have installed a binary of that name into the hooks directory yourself. On a stock install none of them exists, so running one fails with \"Binary not found\". Everything below assumes you installed it.", "examples": [ { "command": "ai-gateway doctor --json", "description": "Check whether an external agent runtime is actually installed", "expectedOutput": "The per-binary health report. An external runtime you have not installed simply does not appear, which is the normal state.", "notes": "Do this before you write a script against kodachi-claw, nullclaw or aeroclaw. They are optional and are not part of a stock Kodachi install." }, { "command": "ai-gateway policy show --json", "description": "Confirm which service names the policy firewall will even accept", "expectedOutput": "The allowlist, which includes the Kodachi services plus the reserved external names kodachi-claw, nullclaw and aeroclaw", "notes": "Being on the allowlist only means the policy will not refuse the name. The binary still has to exist on disk. Names such as agentzero, openclaw, picoclaw and nanoclaw are NOT on the allowlist: they exist only as --agent-id identities." }, { "command": "ai-gateway list --service kodachi-claw --json", "description": "List what an installed external runtime exposes", "expectedOutput": "The commands the runtime reported when the registry probed it, or a not-found error if it is not installed", "notes": "The registry discovers an external runtime by executing it with a probe flag under a 5 second timeout, so its command list comes from the binary itself, not from the compiled catalog." } ] }, { "id": "9_agent_security", "title": "Agent Identity, Tokens and Approval Tickets", "description": "Every execution can carry an agent identity, which decides the highest risk tier it may reach, its rate limit, and what lands in the audit trail. Valid --agent-id values: anonymous, kodachi-claw, nullclaw, agentzero, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, open-interpreter (zeroclaw is accepted as an alias of kodachi-claw). TOKENS: every profile except anonymous requires one. The gateway reads it server-side from the env var KODACHI_AGENT_TOKEN_<AGENT_ID>, uppercased with '-' turned into '_', and that variable must be EXPORTED before you run these commands. If it is unset, the shell expands $KODACHI_AGENT_TOKEN_... to nothing, the word disappears from the command line, and clap fails with \"a value is required\".", "examples": [ { "command": "export KODACHI_AGENT_TOKEN_CLAUDE_CODE=\"<your-token>\"", "description": "Set the token for an agent identity, once per shell", "expectedOutput": "No output. Every later --agent-id claude-code call can now authenticate.", "notes": "The env var name is derived from the agent id: kodachi-claw becomes KODACHI_AGENT_TOKEN_KODACHI_CLAW, open-interpreter becomes KODACHI_AGENT_TOKEN_OPEN_INTERPRETER." }, { "command": "ai-gateway capabilities --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --json", "description": "Ask what a trusted agent identity is allowed to do", "expectedOutput": "Its effective services, its maximum risk tier, and its per-minute rate limit" }, { "command": "ai-gateway capabilities --agent-id anonymous --json", "description": "Show the default capabilities of an unidentified caller", "expectedOutput": "The anonymous profile: no token needed, and a lower rate limit than the named profiles", "notes": "anonymous is the only profile that needs no token, and it is the default when you omit --agent-id." }, { "command": "ai-gateway approve issue health-control block-internet --agent-id kodachi-claw --ttl 600 --json", "description": "A human issues a time-limited ticket authorizing one agent to run one command", "expectedOutput": "A signed approval ticket string, valid for the TTL you gave", "notes": "Requires KODACHI_GATEWAY_APPROVAL_SECRET to be exported. --ttl is in seconds and must be 1 to 3600 (default 300). The ticket is bound to that exact service, command and agent id." }, { "command": "ai-gateway approve verify --ticket \"$TICKET\" health-control block-internet --agent-id kodachi-claw --json", "description": "Check a ticket is genuine and still valid before relying on it", "expectedOutput": "Whether the ticket verifies against this service, command and agent, and when it expires", "notes": "The service and command are positional and must match the ones the ticket was issued for, or verification fails." }, { "command": "ai-gateway run health-control --command block-internet --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --approval-ticket \"$TICKET\" --dry-run --json", "description": "The agent presents its identity and its ticket to run a gated command", "expectedOutput": "Execution gated by the identity policy, the rate limit and ticket verification. With --dry-run, nothing runs.", "notes": "block-internet cuts all network access on this machine. Drop --dry-run only when you mean it. Without a valid ticket the gateway refuses and returns requires_approval." }, { "command": "KODACHI_TRUSTED_BATCH_MODE=true ai-gateway run --agent-id kodachi-claw --agent-token \"$KODACHI_AGENT_TOKEN_KODACHI_CLAW\" --batch-json '[{\"service\":\"ip-fetch\",\"command\":\"fetch\",\"dry_run\":true},{\"service\":\"tor-switch\",\"command\":\"tor-status\",\"dry_run\":true}]' --json", "description": "Run several invocations in one call, sequentially, as a trusted agent", "expectedOutput": "One result per entry in the array, in order, each with its own policy verdict", "notes": "Batch mode needs three things at once: KODACHI_TRUSTED_BATCH_MODE=true, an authenticated agent, and a profile that requires a token. anonymous can never batch. When --batch-json is used, the service argument and --command are supplied inside the JSON instead of on the command line. Each entry may set its own dry_run." } ] } ], "quickReference": [ "ai-gateway --help", "ai-gateway --version", "ai-gateway --info --json", "ai-gateway --examples", "ai-gateway list --json", "ai-gateway search \"tor exit node\" --limit 5 --json", "ai-gateway help tor-switch tor-status --json", "ai-gateway run tor-switch --command tor-status --dry-run --json", "ai-gateway policy show --json", "ai-gateway doctor --json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "ai-trainer", "path": "/opt/kodachi/dashboard/hooks/ai-trainer", "timestamp": "2026-07-21T01:54:42Z", "file_info": { "size": 4468688, "sha256": "ef5fd92bb2c64d66dfe600d1a18e44b2766492d0ec6a0b9475b459e0b951d4f2" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:42.133849598Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-trainer", "version": "9.8.4", "author": "Warith Al Maawali <warith@digi77.com>", "description": "AI model training and validation for Kodachi OS command intelligence", "copyright": "Ā© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "LicenseRef-Kodachi-SAN-1.1", "features": [ "TF-IDF based command embeddings", "Incremental model updates", "Model validation and accuracy testing" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:42.275880336Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-trainer", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:42.443123013Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-trainer", "description": "AI model training and validation for Kodachi OS command intelligence", "usage": "ai-trainer [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Model Management", "commands": [ { "name": "export", "description": "Export model embeddings and metadata to JSON file", "usage": "ai-trainer export --output <FILE> [--format <FORMAT>]", "options": [ { "flag": "--output <FILE>", "description": "Where to write the export. The path is confined to the install directory: a path outside it is rejected", "required": true }, { "flag": "--format <FORMAT>", "description": "full (every embedding vector, largest file), compact (metadata and commands, embedding vectors dropped), stats (counts and metrics only, no commands and no vectors)", "default": "full" }, { "flag": "--json", "description": "Emit the export result as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer export --output data/model_export.json", "sudo ai-trainer export --output data/model_compact.json --format compact", "sudo ai-trainer export --output data/model_stats.json --format stats --json" ] }, { "name": "snapshot", "description": "Save current model as versioned snapshot", "usage": "ai-trainer snapshot --snapshot-version <VERSION>", "options": [ { "flag": "-s, --snapshot-version <VERSION>", "description": "Version label using only ASCII letters, digits, '.', '-' and '_', for example 1.0.0", "required": true }, { "flag": "--json", "description": "Emit the snapshot name, version and embedding count as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer snapshot --snapshot-version 1.0.0", "sudo ai-trainer snapshot -s 1.1.0-beta", "sudo ai-trainer snapshot --snapshot-version 1.0.0 --json" ] }, { "name": "list-snapshots", "description": "List all saved model snapshots", "usage": "ai-trainer list-snapshots", "options": [ { "flag": "--json", "description": "Emit the snapshot list as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-trainer list-snapshots", "ai-trainer list-snapshots --json" ] }, { "name": "status", "description": "Display current model status and statistics", "usage": "ai-trainer status", "options": [ { "flag": "--json", "description": "Emit the model status as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-trainer status", "ai-trainer status --json" ] }, { "name": "download-model", "description": "Download the ONNX embeddings model and tokenizer, or a GGUF model for the local LLM", "usage": "ai-trainer download-model [--llm [default|small|large|xlarge|xlarge-hq]] [--show-models] [--all] [--output-dir <DIR>] [--force] [--allow-unverified-model]", "options": [ { "flag": "--llm [SIZE]", "description": "Download a GGUF model for the local LLM. Sizes: small (Qwen3-1.7B Q4_K_S, ~1.0 GB), default (Qwen3-1.7B Q4_K_M, ~1.1 GB), large (Phi-3.5-mini, ~2.3 GB), xlarge (Qwen3-8B Q4_K_M, ~4.8 GB, tuned for speed), xlarge-hq (Qwen3-8B Q5_K_M, ~5.6 GB, tuned for quality). The value may be omitted", "default": "default (when --llm is given with no value)" }, { "flag": "--all", "description": "Download the ONNX embeddings model (all-MiniLM-L6-v2) and the default GGUF model in one go" }, { "flag": "--show-models", "description": "List what is already downloaded and what is available, with sizes. Downloads nothing" }, { "flag": "--output-dir <DIR>", "description": "Directory the model files are written to", "default": "models/" }, { "flag": "-f, --force", "description": "Re-download and overwrite files that already exist" }, { "flag": "--allow-unverified-model", "description": "Acknowledge that no SHA-256 hash is pinned. Downloads proceed either way and print a warning; this flag only records the opt-in" }, { "flag": "--json", "description": "Emit the download or inventory result as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer download-model", "sudo ai-trainer download-model --llm", "sudo ai-trainer download-model --llm small", "sudo ai-trainer download-model --llm large", "sudo ai-trainer download-model --llm xlarge", "sudo ai-trainer download-model --llm xlarge-hq", "sudo ai-trainer download-model --all", "sudo ai-trainer download-model --output-dir models", "sudo ai-trainer download-model --force", "sudo ai-trainer download-model --show-models" ] } ] }, { "category": "Model Training", "commands": [ { "name": "train", "description": "Train AI model from command metadata (full retraining)", "usage": "ai-trainer train --data <FILE> [--database <DB_PATH>]", "options": [ { "flag": "--data <FILE>", "description": "Training data JSON. The file shipped with Kodachi is data/training-data.json", "required": true }, { "flag": "--database <DB_PATH>", "description": "Embedding database to write", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the training metrics as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer train --data data/training-data.json", "sudo ai-trainer train --data data/training-data.json --json" ] }, { "name": "incremental", "description": "Update model incrementally with new command data", "usage": "ai-trainer incremental --new-data <FILE> [--database <DB_PATH>]", "options": [ { "flag": "--new-data <FILE>", "description": "JSON file with the new commands to fold in. The file shipped with Kodachi is data/incremental-training-data.json", "required": true }, { "flag": "--database <DB_PATH>", "description": "Embedding database to update. It must already exist: `incremental` adds to a trained model, it does not create one", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the incremental metrics as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer incremental --new-data data/incremental-training-data.json", "sudo ai-trainer incremental --new-data data/incremental-training-data.json --json" ] } ] }, { "category": "Validation & Testing", "commands": [ { "name": "validate", "description": "Validate model accuracy against test dataset", "usage": "ai-trainer validate --test-data <FILE> [--threshold <THRESHOLD>]", "options": [ { "flag": "--test-data <FILE>", "description": "Test dataset JSON. The file shipped with Kodachi is data/test-cases.json", "required": true }, { "flag": "--threshold <THRESHOLD>", "description": "Accuracy the run must reach to be reported as a pass, between 0.0 and 1.0", "default": "0.85" }, { "flag": "--database <DB_PATH>", "description": "Embedding database to validate against", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the validation metrics as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-trainer validate --test-data data/test-cases.json", "ai-trainer validate --test-data data/test-cases.json --threshold 0.90", "ai-trainer validate --test-data data/test-cases.json --threshold 0.2 --json" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format <FORMAT>", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter <FIELD1,FIELD2>", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields <FIELD_LIST>", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit <NUMBER>", "description": "Limit number of results returned" }, { "flag": "--offset <NUMBER>", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir <PATH>", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port <PORT>", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level <LEVEL>", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config <FILE>", "description": "Use custom configuration file" }, { "flag": "--timeout <SECS>", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "3": "Permission denied", "2": "Invalid arguments", "0": "Success", "4": "Network error", "5": "File not found", "1": "General error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:42.742434194Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-trainer", "description": "Usage examples for ai-trainer", "categories": [ { "id": "1_model_training", "title": "Model Training", "description": "Retrain the command-embedding model from scratch. The training corpus that ships with Kodachi is data/training-data.json.", "examples": [ { "command": "sudo ai-trainer train --data data/training-data.json", "description": "Rebuild the model from the shipped training corpus", "expectedOutput": "The number of commands trained, the vocabulary size and the embedding count, then the database path that was written", "notes": "Needs root (it rewrites the embedding database in the install directory) and a prior `online-auth` login. This REPLACES the existing model." }, { "command": "sudo ai-trainer train --data data/training-data.json --database data/embeddings-test.db", "description": "Train into a separate database instead of the live one", "expectedOutput": "The same training summary, written to the database path you named", "notes": "Needs root and a prior `online-auth` login. Use this to try a training run without touching data/embeddings.db, which is the one the AI actually reads." }, { "command": "sudo ai-trainer train --data data/training-data.json --json", "description": "Train and capture the metrics for a pipeline", "expectedOutput": "Envelope with the training metrics", "notes": "Needs root and a prior `online-auth` login." } ] }, { "id": "2_incremental_training", "title": "Incremental Training", "description": "Fold new commands into a model that already exists, instead of retraining from scratch. The incremental corpus that ships with Kodachi is data/incremental-training-data.json.", "examples": [ { "command": "sudo ai-trainer incremental --new-data data/incremental-training-data.json", "description": "Add the new commands to the existing model", "expectedOutput": "The count of new embeddings added and the new total", "notes": "Needs root and a prior `online-auth` login. Requires an already-trained database: run `train` first." }, { "command": "sudo ai-trainer incremental --new-data data/incremental-training-data.json --json", "description": "Incremental update with a machine-readable result", "expectedOutput": "Envelope with the incremental training metrics", "notes": "Needs root and a prior `online-auth` login." } ] }, { "id": "3_validation", "title": "Validation", "description": "Score the trained model against a labelled test set. `validate` is read-only: no root, no authentication. The test set that ships with Kodachi is data/test-cases.json.", "examples": [ { "command": "ai-trainer validate --test-data data/test-cases.json", "description": "Check the model against the shipped test cases", "expectedOutput": "The measured accuracy and whether it passed the 0.85 default threshold", "notes": "--threshold defaults to 0.85. A freshly trained model on the small shipped test set can score below that: a fail here is a threshold statement, not a crash." }, { "command": "ai-trainer validate --test-data data/test-cases.json --threshold 0.90", "description": "Demand 90 percent accuracy instead of the default 85", "expectedOutput": "The measured accuracy and a pass or fail against 0.90", "notes": "--threshold is a fraction between 0.0 and 1.0, not a percentage." }, { "command": "ai-trainer validate --test-data data/test-cases.json --threshold 0.2 --json", "description": "A low-bar smoke check for CI, machine-readable", "expectedOutput": "Envelope with the accuracy and the pass or fail verdict", "notes": "0.2 is deliberately permissive: it only proves the model loads and classifies, it does not prove quality." }, { "command": "ai-trainer validate --test-data data/test-cases.json --database data/embeddings-test.db --json", "description": "Validate a candidate database before promoting it", "expectedOutput": "Envelope with the accuracy of the database you named" } ] }, { "id": "4_model_export", "title": "Model Export", "description": "Dump the trained model to a JSON file. --output is confined to the install directory: a path outside it is rejected.", "examples": [ { "command": "sudo ai-trainer export --output data/model_export.json", "description": "Export the whole model, embedding vectors included", "expectedOutput": "data/model_export.json written, with the command metadata and every embedding vector", "notes": "Needs root and a prior `online-auth` login. The full format is the largest: every vector is serialized." }, { "command": "sudo ai-trainer export --output data/model_compact.json --format compact", "description": "Export without the embedding vectors to keep the file small", "expectedOutput": "data/model_compact.json with the commands and metadata but no vectors", "notes": "Needs root and a prior `online-auth` login. compact DROPS the embedding vectors, so the file cannot rebuild the model, only describe it." }, { "command": "sudo ai-trainer export --output data/model_stats.json --format stats --json", "description": "Export only the counts and metrics", "expectedOutput": "data/model_stats.json with the embedding count, vocabulary size and metrics, and nothing else", "notes": "Needs root and a prior `online-auth` login. stats drops BOTH the commands and the vectors." } ] }, { "id": "5_snapshots", "title": "Snapshots", "description": "Save and list versioned copies of the trained model, so a bad training run can be identified and compared.", "examples": [ { "command": "sudo ai-trainer snapshot --snapshot-version 1.0.0", "description": "Freeze the current model under a version label", "expectedOutput": "The snapshot name, its version and the number of embeddings captured", "notes": "Needs root and a prior `online-auth` login. Take a snapshot BEFORE a retrain if you may want to compare against the old model." }, { "command": "sudo ai-trainer snapshot -s 1.1.0-beta --json", "description": "Snapshot with the short flag and a machine-readable result", "expectedOutput": "Envelope with the snapshot name, version and embedding count", "notes": "Needs root and a prior `online-auth` login." }, { "command": "ai-trainer list-snapshots", "description": "See every snapshot that has been taken", "expectedOutput": "One line per snapshot with its version and metadata" }, { "command": "ai-trainer list-snapshots --json", "description": "The snapshot list as JSON", "expectedOutput": "Envelope with the snapshot array" } ] }, { "id": "6_download", "title": "Model Download", "description": "Fetch the model files the AI engine needs: the all-MiniLM-L6-v2 ONNX embeddings model, and a GGUF model for the local LLM. NOTE: no SHA-256 hash is currently pinned for any of these files, so their integrity is NOT verified after download. Every download prints a warning saying so.", "examples": [ { "command": "sudo ai-trainer download-model", "description": "Download the ONNX embeddings model and its tokenizer", "expectedOutput": "all-MiniLM-L6-v2.onnx and tokenizer.json written to models/, preceded by the no-pinned-hash warning", "notes": "Needs root (writes into the install directory) and a prior `online-auth` login. Needs network access. The download is NOT hash-verified: no hash is pinned for this file." }, { "command": "sudo ai-trainer download-model --llm", "description": "Download the default local LLM (Qwen3-1.7B Q4_K_M, about 1.1 GB)", "expectedOutput": "The GGUF file written to models/, preceded by the no-pinned-hash warning", "notes": "Needs root, network access and a prior `online-auth` login. Best balance of quality, speed and size for CPU inference. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm small", "description": "Download the smallest local LLM (Qwen3-1.7B Q4_K_S, about 1.0 GB)", "expectedOutput": "The small GGUF file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. Choose this on systems with under 4 GB of free RAM. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm large", "description": "Download the mid-size local LLM (Phi-3.5-mini, about 2.3 GB)", "expectedOutput": "The large GGUF file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. Better reasoning and a 128K trained context. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm xlarge", "description": "Download the 8B model tuned for speed (Qwen3-8B Q4_K_M, about 4.8 GB)", "expectedOutput": "The Qwen3-8B Q4_K_M file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. 4-bit quantization, for 8 GB RAM and up: faster tokens per second, lower quality than xlarge-hq. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm xlarge-hq", "description": "Download the 8B model tuned for quality (Qwen3-8B Q5_K_M, about 5.6 GB)", "expectedOutput": "The Qwen3-8B Q5_K_M file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. 5-bit quantization, recommended on 16 GB RAM and up: the best local-LLM quality in the catalog, roughly 15 percent slower than xlarge. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --all", "description": "Download the ONNX embeddings model and the default GGUF in one go", "expectedOutput": "Both the ONNX files and the default GGUF written to models/", "notes": "Needs root, network access and a prior `online-auth` login. This is the complete first-time setup. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --output-dir models", "description": "Download into a directory you choose instead of the default", "expectedOutput": "The model files written to the directory you named", "notes": "Needs root, network access and a prior `online-auth` login. --output-dir defaults to models/, so this only matters if you want a different location." }, { "command": "sudo ai-trainer download-model --force", "description": "Re-download the ONNX model even though the files are already there", "expectedOutput": "The existing files are overwritten with a fresh download", "notes": "Needs root, network access and a prior `online-auth` login. Overwrites: use it when a file is suspected to be truncated or corrupt." }, { "command": "ai-trainer download-model --show-models", "description": "See what is already downloaded and what is available", "expectedOutput": "The model inventory: each catalog entry with its size and whether it is present on disk", "notes": "Downloads nothing, so it needs neither root nor authentication." }, { "command": "ai-trainer download-model --show-models --json", "description": "The model inventory as JSON", "expectedOutput": "Envelope listing the downloaded and available models" } ] }, { "id": "7_status", "title": "Status", "description": "Check whether a trained model exists and what is in it. `status` is read-only: no root, no authentication.", "examples": [ { "command": "ai-trainer status", "description": "Show whether the model is trained and how big it is", "expectedOutput": "The database path, the embedding count and the model statistics, or a clear message that no model has been trained yet" }, { "command": "ai-trainer status --json", "description": "The model status as JSON for the dashboard", "expectedOutput": "Envelope with the model status and statistics" } ] } ], "quickReference": [ "ai-trainer --help", "ai-trainer --version", "ai-trainer --info --json", "ai-trainer --examples", "ai-trainer status", "ai-trainer validate --test-data data/test-cases.json", "ai-trainer download-model --show-models", "sudo ai-trainer train --data data/training-data.json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } }, { "name": "routing-switch", "path": "/opt/kodachi/dashboard/hooks/routing-switch", "timestamp": "2026-07-21T01:54:43Z", "file_info": { "size": 10082048, "sha256": "875b6e38ba047ab609e3213ab4c2e10490749f8368d1f5d797444d631ef2e4fc" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "configuration": "Uses online-auth get-card for the Kodachi VPN credentials. VPNGate servers cost nothing, and browsing them (vpngate-fetch/list/export) needs no authentication, but connecting to one (vpngate-connect) still goes through the online-auth gate because it rewrites your routing. Every `providers` verb requires authentication.", "connection_limit": "One active connection at a time", "copyright": "Ā© 2026 Kodachi OS", "description": "System-wide traffic routing through various proxy protocols", "features": [ "System-wide traffic routing through proxy protocols", "Support for OpenVPN, WireGuard, and Dante SOCKS5", "Support for Tor, Shadowsocks, V2Ray, and Xray protocols", "Support for Mieru/Mita and Hysteria2 protocols", "Automatic protocol scoring and selection", "DNS leak prevention with multiple modes", "Metric-based and direct routing options", "External configuration file support", "IPv4/IPv6 dual-stack support", "QR code generation for mobile clients", "VPNGate free VPN integration (100+ public servers; browsing is auth-free, vpngate-connect requires authentication)", "External VPN Providers sub-tree (routing-switch providers): 20 verbs over a user-editable catalog of commercial and free providers (VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad-WG), with credential storage, custom config import, latency benchmarking, and random/fastest pick", "Microsocks SOCKS5 server mode: share this machine's active tunnel with other devices on the LAN", "Comprehensive logging and monitoring" ], "license": "Proprietary", "name": "routing-switch", "security_features": [ "Input validation: All inputs are validated and sanitized", "Rate limiting: Built-in rate limiting for network operations", "Authentication: Secure authentication with certificate pinning", "Encryption: TLS 1.3 for all network communications", "Kill switch controls: health-control handles leak response; Direct routing prefers the TUN path", "DNS protection: Multiple DNS modes to prevent leaks" ], "state_file": "./results/routing-switch-state.json", "supported_protocols": [ "OpenVPN", "WireGuard", "Dante", "Tor", "Shadowsocks", "V2Ray", "Xray-VLESS", "Xray-VLESS-Reality", "Xray-Trojan", "Xray-VMess", "Mita/Mieru", "Hysteria2", "VPNGate (free public servers)" ], "system_requirements": { "dependencies": "OpenSSL, libcurl, tun2socks (for most protocols), redsocks (for Tor)", "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:43.277795595Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "routing-switch", "rustVersion": "1.70.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:43.372883596Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "CONNECTION COMMANDS", "commands": [ { "description": "Connect to a proxy protocol (openvpn, wireguard use native routing; tor uses redsocks and must be layered on an active tunnel; dante, shadowsocks, v2ray, xray-*, mita, hysteria2 use tun2socks). Requires root and a prior online-auth login.", "examples": [ "sudo routing-switch connect wireguard", "sudo routing-switch connect openvpn --config /path/to/vpn.ovpn --force", "sudo routing-switch connect wireguard && sudo routing-switch connect tor", "sudo routing-switch connect shadowsocks --no-tun" ], "name": "connect", "options": [ { "description": "Use an external config file instead of the auth card (.ovpn / .conf for OpenVPN and WireGuard, card-native services.<proto> JSON for the rest)", "flag": "--config <FILE>" }, { "description": "Force the IPv4 endpoint of a dual-stack protocol (conflicts with --ipv6)", "flag": "--ipv4" }, { "description": "Force the IPv6 endpoint of a dual-stack protocol (conflicts with --ipv4)", "flag": "--ipv6" }, { "description": "Disconnect the currently active protocol first, then connect this one. It does NOT stack two VPNs. Not needed for `connect tor`, which layers on the active tunnel by design", "flag": "--force" }, { "default": "auto", "description": "DNS routing: auto (default, DNS flows through the tunnel), hybrid (VPN server DNS bypasses the tunnel), strict (ALL DNS through the tunnel), system (ALL DNS bypasses the tunnel: LEAKS, debugging only)", "flag": "--dns-mode <MODE>" }, { "description": "Keep private/LAN networks off the VPN so local devices stay reachable", "flag": "--exclude-private" }, { "description": "Run the proxy client without a TUN device: system routing is untouched and you point apps at the local SOCKS5 port by hand. Supported by the tun2socks protocols only, `connect tor --no-tun` is rejected", "flag": "--no-tun" }, { "description": "Metric-based routing: keeps the original route as a fallback. LESS SECURE, traffic can leak to the clear net if the TUN drops. Default is direct routing", "flag": "--metric" }, { "description": "Skip the IPv4-forwarding / NAT / MASQUERADE checks before connecting", "flag": "--skip-prerequisites" }, { "description": "DANGER: keep the connection alive even when an IPv6 leak is detected. The default is fail-closed (the connection is torn down). With this flag your real IPv6 address stays exposed", "flag": "--allow-ipv6-leak" } ], "requires_sudo": true, "usage": "sudo routing-switch connect <PROTOCOL> [OPTIONS]" }, { "description": "Disconnect the current proxy connection and restore normal routing", "examples": [ "sudo routing-switch disconnect", "sudo routing-switch disconnect --force --clean-firewall" ], "name": "disconnect", "options": [ { "description": "Kill the protocol processes outright and skip the graceful cleanup checks", "flag": "--force" }, { "description": "Also flush the iptables rules (Docker/KVM chains are preserved). Use when the network stays stuck after a normal disconnect. REQUIRES AUTHENTICATION: it tears down the kill-switch rules, so unlike a plain disconnect it is not auth-exempt", "flag": "--clean-firewall" } ], "requires_sudo": true, "usage": "sudo routing-switch disconnect [OPTIONS]" }, { "description": "Show the current connection status (auth-exempt, but needs sudo to read privileged system state)", "examples": [ "sudo routing-switch status", "sudo routing-switch status --detailed --json" ], "name": "status", "options": [ { "description": "Add the exact Connected Since timestamp to the normal status block", "flag": "--detailed" } ], "requires_sudo": true, "usage": "sudo routing-switch status [OPTIONS]" } ] }, { "category": "INFORMATION COMMANDS", "commands": [ { "description": "Display current DNS server information (auth-exempt)", "examples": [ "routing-switch dns-info", "routing-switch dns-info --json" ], "name": "dns-info", "options": [], "requires_sudo": false, "usage": "routing-switch dns-info [OPTIONS]" }, { "description": "Display the Tor DNS and SOCKS endpoints. Kodachi's Tor is VPN-side: its SOCKS5 lives on the worker (10.0.0.1:9050 over WireGuard, 172.16.0.1:9050 over OpenVPN), never on 127.0.0.1", "examples": [ "routing-switch tor-dns-info", "routing-switch tor-dns-info --json" ], "name": "tor-dns-info", "options": [], "requires_sudo": false, "usage": "routing-switch tor-dns-info [OPTIONS]" }, { "description": "Display VPS server information (hostname, IP, stats)", "examples": [ "routing-switch vps-info", "routing-switch vps-info --detailed" ], "name": "vps-info", "options": [ { "description": "Include CPU load, memory usage, uptime and connection counts", "flag": "--detailed" } ], "requires_sudo": false, "usage": "routing-switch vps-info [OPTIONS]" }, { "description": "List available protocols with their security/speed scores (auth-exempt)", "examples": [ "routing-switch list-protocols", "routing-switch list-protocols --detailed --sort-by-security" ], "name": "list-protocols", "options": [ { "description": "Show the full scoring breakdown per protocol, not just the overall score", "flag": "--detailed" }, { "description": "Probe each protocol's endpoint for real instead of scoring from the auth card alone (slower, more accurate, needs network)", "flag": "--test" }, { "description": "Hide protocols the auth card does not provide", "flag": "--available-only" }, { "description": "Sort by security score (conflicts with --sort-by-speed)", "flag": "--sort-by-security" }, { "description": "Sort by speed score (conflicts with --sort-by-security)", "flag": "--sort-by-speed" } ], "requires_sudo": false, "usage": "routing-switch list-protocols [OPTIONS]" } ] }, { "category": "TESTING COMMANDS", "commands": [ { "description": "Test one protocol's endpoint (or `all`) without touching routing. Reads the auth card, so it needs authentication", "examples": [ "routing-switch test-protocol wireguard", "routing-switch test-protocol all --json" ], "name": "test-protocol", "options": [ { "description": "Run the longer test set (latency and throughput checks) instead of a plain reachability probe", "flag": "--extended" } ], "requires_sudo": false, "usage": "routing-switch test-protocol <PROTOCOL|all> [OPTIONS]" }, { "description": "Measure TCP connection latency for all available protocols. Requires authentication because it reads auth-card endpoints", "examples": [ "routing-switch benchmark", "routing-switch benchmark --iterations 5 --json" ], "name": "benchmark", "options": [ { "description": "Number of test iterations per protocol (default: 3). More iterations means slower but steadier numbers", "flag": "--iterations <N>" } ], "requires_sudo": false, "usage": "routing-switch benchmark [OPTIONS]" } ] }, { "category": "CONFIGURATION COMMANDS", "commands": [ { "description": "Export protocol configurations to files. Requires authentication", "examples": [ "routing-switch export-config wireguard", "routing-switch export-config all --path /tmp/vpn-configs/" ], "name": "export-config", "options": [ { "description": "Directory to write the configs to (default: ./results/configs/). Created if it does not exist", "flag": "-p, --path <PATH>" }, { "description": "WARNING: writes the real passwords and keys into the exported files", "flag": "--include-credentials" } ], "requires_sudo": false, "usage": "routing-switch export-config [PROTOCOL|all] [OPTIONS]" }, { "description": "Show a protocol's configuration. Requires authentication", "examples": [ "routing-switch showconfig wireguard", "routing-switch showconfig dante --mask-sensitive" ], "name": "showconfig", "options": [ { "description": "Redact passwords, keys and credential-bearing URLs so the output is safe to share or log", "flag": "--mask-sensitive" } ], "requires_sudo": false, "usage": "routing-switch showconfig [PROTOCOL|all] [OPTIONS]" }, { "description": "Show a protocol's configuration as a connection URL (ss://, socks5://, ...). Requires authentication", "examples": [ "routing-switch showconfigurl shadowsocks", "routing-switch showconfigurl all --json" ], "name": "showconfigurl", "options": [], "requires_sudo": false, "usage": "routing-switch showconfigurl [PROTOCOL|all] [OPTIONS]" }, { "description": "Show a protocol's configuration as a QR code for mobile clients. Requires authentication", "examples": [ "routing-switch showconfigqr wireguard", "routing-switch showconfigqr shadowsocks --ipv4 --ipv6 --save-files" ], "name": "showconfigqr", "options": [ { "description": "Generate the IPv4 QR code (this is the default for dual-stack protocols)", "flag": "--ipv4" }, { "description": "Generate the IPv6 QR code. Can be combined with --ipv4 to emit both", "flag": "--ipv6" }, { "description": "Do not re-read the generated QR to verify it (faster, for debugging)", "flag": "--skip-validation" }, { "description": "Fail the whole operation if any generated QR code fails validation", "flag": "--strict-validation" }, { "description": "Also write the QR codes as PNG files into ./results/qr-codes/", "flag": "--save-files" } ], "requires_sudo": false, "usage": "routing-switch showconfigqr [PROTOCOL|all] [OPTIONS]" }, { "description": "Validate QR code configurations against the auth card (by file, by stdin, or by protocol). Requires authentication", "examples": [ "routing-switch validate-qr shadowsocks_ipv4.png", "echo 'ss://...' | routing-switch validate-qr --stdin" ], "name": "validate-qr", "options": [ { "description": "Path to a QR image to decode. Equivalent to passing the filename positionally. If the file is not in the current directory, ./results/qr-codes/ is searched", "flag": "-f, --file <FILE>" }, { "description": "Read the QR payload (the URL) from stdin instead of an image", "flag": "--stdin" }, { "description": "Round-trip check: generate a QR for the protocol and confirm it decodes back to the same config", "flag": "--test-readability" } ], "requires_sudo": false, "usage": "routing-switch validate-qr [PROTOCOL|<FILE>.png|all] [OPTIONS]" } ] }, { "category": "MANAGEMENT COMMANDS", "commands": [ { "description": "Score the available protocols, pick the best one, and connect to it. Requires authentication", "examples": [ "sudo routing-switch auto-select", "sudo routing-switch auto-select --min-security 90" ], "name": "auto-select", "options": [ { "default": "80", "description": "Reject protocols scoring below this security threshold, 0 to 100 (default: 80)", "flag": "--min-security <SCORE>" }, { "description": "Weight speed above the other factors when ranking", "flag": "--prefer-speed" } ], "requires_sudo": true, "usage": "sudo routing-switch auto-select [OPTIONS]" }, { "description": "Reset all routing to the system default state. DESTRUCTIVE: drops the active tunnel, so you are back on the clear net afterwards. Auth-exempt on purpose (it must work when the network is down)", "examples": [ "sudo routing-switch reset", "sudo routing-switch reset --force" ], "name": "reset", "options": [ { "description": "Reset even when the stored state says a connection is still active or the teardown reports errors", "flag": "--force" } ], "requires_sudo": true, "usage": "sudo routing-switch reset [OPTIONS]" }, { "description": "Clean up orphaned protocol processes and leftover resources. Auth-exempt", "examples": [ "sudo routing-switch cleanup", "sudo routing-switch cleanup --thorough" ], "name": "cleanup", "options": [ { "description": "Deeper sweep: also removes stale TUN devices, routes and iptables rules, not just stray processes. Can disturb an active connection, so run it after disconnecting", "flag": "--thorough" } ], "requires_sudo": true, "usage": "sudo routing-switch cleanup [OPTIONS]" }, { "description": "Diagnose and repair a half-broken routing state (cleanup, route restore, DNS reset). The 'my internet is stuck' command. Auth-exempt", "examples": [ "sudo routing-switch recover", "sudo routing-switch recover --force" ], "name": "recover", "options": [ { "description": "Run the recovery even when routing-switch believes the state is healthy. DESTRUCTIVE: drops any active tunnel and restores the clear-net default route", "flag": "--force" } ], "requires_sudo": true, "usage": "sudo routing-switch recover [OPTIONS]" }, { "description": "Check and fix the network prerequisites for VPN connections (IPv4 forwarding, NAT MASQUERADE). Fixes only what is wrong. Auth-exempt", "examples": [ "sudo routing-switch check-prerequisites", "sudo routing-switch check-prerequisites --ipv6 --json" ], "name": "check-prerequisites", "options": [ { "description": "Also check (and enable, if the system supports it) the IPv6 forwarding prerequisites", "flag": "--ipv6" } ], "requires_sudo": true, "usage": "sudo routing-switch check-prerequisites [OPTIONS]" } ] }, { "category": "MICROSOCKS SERVER MANAGEMENT", "commands": [ { "description": "Run a SOCKS5 server on this machine so other devices on the LAN can ride its active tunnel. Connect a protocol FIRST, then enable this. Requires authentication", "examples": [ "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'", "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' --port 30051" ], "name": "microsocks-enable", "options": [ { "description": "SOCKS5 username the client devices must present (required)", "flag": "-u, --username <USERNAME>", "required": true }, { "description": "SOCKS5 password (required). The listener binds 0.0.0.0, so use a strong one", "flag": "-p, --password <PASSWORD>", "required": true }, { "description": "Listening port. Omit to auto-pick the first free port in the 30050-30054 range", "flag": "--port <PORT>" } ], "requires_sudo": true, "usage": "sudo routing-switch microsocks-enable -u <USERNAME> -p <PASSWORD> [--port PORT]" }, { "description": "Stop the microsocks SOCKS5 server. Requires authentication", "examples": [ "sudo routing-switch microsocks-disable", "sudo routing-switch microsocks-disable --json" ], "name": "microsocks-disable", "options": [], "requires_sudo": true, "usage": "sudo routing-switch microsocks-disable" }, { "description": "Show the microsocks server status (running, port, PID, uptime). Auth-exempt", "examples": [ "sudo routing-switch microsocks-status", "sudo routing-switch microsocks-status --json" ], "name": "microsocks-status", "options": [], "requires_sudo": false, "usage": "sudo routing-switch microsocks-status [OPTIONS]" } ] }, { "category": "VPNGATE FREE VPN", "commands": [ { "description": "Fetch the VPNGate public server list into the local cache (auth-exempt, refreshes hourly)", "examples": [ "routing-switch vpngate-fetch", "routing-switch vpngate-fetch --json" ], "name": "vpngate-fetch", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-fetch [OPTIONS]" }, { "description": "List the cached VPNGate servers with filtering and sorting (auth-exempt). The index it prints is what vpngate-connect and vpngate-export take", "examples": [ "routing-switch vpngate-list", "routing-switch vpngate-list --country JP --sort speed -l 10" ], "name": "vpngate-list", "options": [ { "description": "Filter by country name or code (for example JP, Japan, US)", "flag": "-c, --country <COUNTRY>" }, { "default": "score", "description": "score (default, highest first), speed (highest first), ping (lowest first), sessions (lowest first, i.e. least crowded)", "flag": "-s, --sort <CRITERIA>" }, { "description": "Show only the first N results after filtering and sorting", "flag": "-l, --limit <N>" } ], "requires_sudo": false, "usage": "routing-switch vpngate-list [OPTIONS]" }, { "description": "Connect to a VPNGate server by index (OpenVPN, public vpn/vpn credentials). REQUIRES AUTHENTICATION: it rewrites routes, DNS and firewall like any other connect. Only VPNGate BROWSING (fetch/list/export) is auth-free", "examples": [ "sudo routing-switch vpngate-connect 5", "sudo routing-switch vpngate-connect 12 --force" ], "name": "vpngate-connect", "options": [ { "description": "Disconnect the currently active connection first", "flag": "--force" }, { "description": "Skip the IPv4-forwarding / NAT / MASQUERADE checks before connecting", "flag": "--skip-prerequisites" } ], "requires_sudo": true, "usage": "sudo routing-switch vpngate-connect <INDEX> [OPTIONS]" }, { "description": "Export one cached VPNGate server's OpenVPN config as a standalone .ovpn file (auth-exempt)", "examples": [ "routing-switch vpngate-export 1", "routing-switch vpngate-export 5 --json" ], "name": "vpngate-export", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-export <INDEX> [OPTIONS]" }, { "description": "Export every cached VPNGate server as a .ovpn file into results/vpngate-configs (auth-exempt)", "examples": [ "routing-switch vpngate-export-all", "routing-switch vpngate-export-all --json" ], "name": "vpngate-export-all", "options": [], "requires_sudo": false, "usage": "routing-switch vpngate-export-all [OPTIONS]" }, { "description": "External VPN Providers sub-tree (20 verbs) over a user-editable catalog of commercial and free providers (VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad-WG). EVERY providers verb requires authentication, and every cache-writing verb requires root. Run `routing-switch providers --help` for the per-verb flags", "examples": [ "routing-switch providers list", "sudo routing-switch providers fetch vpngate --force", "routing-switch providers list-profiles vpngate --country jp --limit 5", "sudo routing-switch providers connect-fastest vpngate --country jp --force" ], "name": "providers", "options": [ { "description": "Show the catalog with cache freshness; re-read the catalog JSON after editing dashboard/hooks/config/vpn-providers-public-api.json", "flag": "list | refresh-catalog" }, { "description": "Fetch a provider's profile list into the cache. --force bypasses the cache TTL. Needs root", "flag": "fetch <ID> [--force]" }, { "description": "Browse the cached profiles, filtered by 2-letter country code and/or transport protocol substring (udp, tcp, openvpn, wireguard)", "flag": "list-profiles <ID> [-c|--country CC] [-p|--protocol PROTO] [-l|--limit N]" }, { "description": "Print one profile's raw config body. Lazily fetches on a cache miss, so it needs root", "flag": "get-profile <ID> <PROFILE_ID>" }, { "description": "Connect through a provider profile, auto-injecting any stored credentials. Needs root", "flag": "connect <ID> <PROFILE_ID> [--force] [--skip-prerequisites]" }, { "description": "Pick a random profile from the provider's cache (optionally country-filtered) and connect. Needs root", "flag": "connect-random <ID> [--country CC] [--force]" }, { "description": "Pick the fastest profile (benchmarked latency first, then provider-reported speed, then load) and connect. Needs root", "flag": "connect-fastest <ID> [--country CC] [--force]" }, { "description": "Latency-probe the cached profiles and store the result so connect-fastest can use it. Manual only, never auto-runs. Needs root", "flag": "benchmark <ID> [--country CC] [--top N] [--concurrency N] [--timeout S]" }, { "description": "Manage per-provider VPN account credentials (never the dashboard login). Values are sealed with AES-256-GCM. Set and delete need root", "flag": "credentials-list | credentials-set <ID> --field k=v | credentials-delete <ID>" }, { "description": "Import your own OpenVPN / WireGuard / Shadowsocks / V2Ray / Hysteria2 config as a custom profile (import needs root); validate-config previews the detection without writing", "flag": "import-config --name N (--file F | --text T) [--protocol-hint P] | validate-config" }, { "description": "Remove imported custom profiles and their stored credentials. Irreversible, no confirmation prompt. Needs root", "flag": "delete-custom-profile <PROFILE_ID> | delete-custom-profiles-bulk (--id ID... | --all)" }, { "description": "Fill in a cached profile's missing country (via ip-fetch geo) or its missing IPv4 (via DNS), writing back to the cache. Needs root", "flag": "resolve-country <ID> <PROFILE_ID> [--force] | resolve-ip <ID> <PROFILE_ID> | resolve-ips <ID> [--concurrency N]" }, { "description": "Drop a provider's cached index and configs, or every provider's with --all. Credentials are NEVER touched. Needs root", "flag": "clear-cache [<ID>] [--all]" } ], "requires_sudo": false, "usage": "routing-switch providers <SUBCOMMAND> [OPTIONS]" } ] } ], "description": "System-wide traffic routing through various proxy protocols", "environmentVariables": [ { "default": "info", "description": "Set logging level (default: info)", "name": "RUST_LOG", "values": "error, warn, info, debug, trace" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Force output format: text (default) or json", "flag": "-o, --output-format <FORMAT>" } ], "name": "routing-switch", "usage": "routing-switch [OPTIONS] <COMMAND>" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:43.467750957Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Connect to a proxy protocol. Every connect verb needs root (it rewrites routes, DNS and iptables) and needs a prior online-auth login: without one you get 'Authentication required'. Only one connection is active at a time; add --force to replace an existing one. The one exception is `connect tor`, which LAYERS on an active tunnel and therefore does not take --force.", "examples": [ { "command": "sudo routing-switch connect openvpn", "description": "Connect via OpenVPN", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Requires OpenVPN configuration in auth card" }, { "command": "sudo routing-switch connect wireguard", "description": "Connect via WireGuard", "expectedOutput": "Successfully connected to WireGuard server", "notes": "Ultra-fast, modern VPN protocol" }, { "command": "sudo routing-switch connect dante", "description": "Connect via Dante SOCKS5 proxy", "expectedOutput": "Successfully connected to Dante server", "notes": "Dante rides the shared tun_routing device, so it clashes with any other tun2socks protocol (shadowsocks, v2ray, xray-*, mita, hysteria2). If one of those is already up, disconnect first, or pass --force (which drops the existing connection before dialing)." }, { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect tor", "description": "Route traffic through Tor - VPN-only, layered on an active Kodachi tunnel", "expectedOutput": "Layering Tor on the active wireguard tunnel ... Successfully routing traffic through Tor", "notes": "Kodachi's Tor SOCKS proxy is bound to the VPN network only - never exposed on a public IP, because a public Tor SOCKS port gets abused as an open proxy. So `connect tor` is NOT a standalone command: connect ANY Kodachi protocol FIRST (WireGuard, OpenVPN, or a proxy protocol - Shadowsocks/V2Ray/Xray/Hysteria2/Mita), then `connect tor` layers Tor on that tunnel (the underlay is kept, not disconnected). Running `connect tor` with no tunnel up is refused with on-screen guidance. Easier alternative for WireGuard/OpenVPN: set your browser's SOCKS5 proxy to 172.16.0.1:9050 (over OpenVPN) or 10.0.0.1:9050 (over WireGuard)." }, { "command": "sudo routing-switch connect shadowsocks", "description": "Connect via Shadowsocks", "expectedOutput": "Successfully connected to Shadowsocks server", "notes": "Optimized for bypassing censorship" }, { "command": "sudo routing-switch connect v2ray", "description": "Connect via V2Ray VMess", "expectedOutput": "Successfully connected to V2Ray server", "notes": "tun2socks protocol: local SOCKS5 is allocated from 30005-30009. Conflicts with any other tun2socks protocol on tun_routing." }, { "command": "sudo routing-switch connect xray-vless", "description": "Connect via Xray VLESS TLS", "expectedOutput": "Successfully connected to Xray VLESS server", "notes": "Lightweight, fast protocol with TLS" }, { "command": "sudo routing-switch connect xray-vless-reality", "description": "Connect via Xray VLESS Reality", "expectedOutput": "Successfully connected to Xray VLESS Reality server", "notes": "Most advanced censorship resistance" }, { "command": "sudo routing-switch connect xray-trojan", "description": "Connect via Xray Trojan", "expectedOutput": "Successfully connected to Xray Trojan server", "notes": "Mimics HTTPS traffic" }, { "command": "sudo routing-switch connect xray-vmess", "description": "Connect via Xray VMess", "expectedOutput": "Successfully connected to Xray VMess server", "notes": "VMess over the Xray core: local SOCKS5 is allocated from 30010-30014. Conflicts with any other tun2socks protocol on tun_routing." }, { "command": "sudo routing-switch connect mita", "description": "Connect via Mieru/Mita protocol", "expectedOutput": "Successfully connected to Mita server", "notes": "Anti-censorship protocol" }, { "command": "sudo routing-switch connect hysteria2", "description": "Connect via Hysteria2 protocol", "expectedOutput": "Successfully connected to Hysteria2 server", "notes": "UDP-based, high-performance anti-censorship protocol" } ], "id": "basic_connections", "title": "BASIC CONNECTIONS" }, { "description": "Connect a custom profile with --config instead of the auth card. OpenVPN/WireGuard take standard text bodies; v2ray/xray/shadowsocks/hysteria2/mita take the card-native services.<proto> JSON object (a custom profile is just a card service slice).", "examples": [ { "command": "sudo routing-switch connect openvpn --config /home/user/vpn.ovpn", "description": "Connect using external OpenVPN config file", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Supports standard .ovpn configuration files" }, { "command": "sudo routing-switch connect wireguard --config /path/to/wg0.conf", "description": "Connect using external WireGuard config", "expectedOutput": "Successfully connected to WireGuard server", "notes": "Uses standard WireGuard .conf format" }, { "command": "sudo routing-switch connect shadowsocks --config /path/to/shadowsocks-profile.json", "description": "Connect a custom Shadowsocks profile", "expectedOutput": "Successfully connected to Shadowsocks server", "notes": "File is the card-native services.shadowsocks JSON object (method, password, port, ipv4{host,url})" }, { "command": "sudo routing-switch connect v2ray --config /path/to/v2ray-profile.json", "description": "Connect a custom V2Ray (VMess) profile", "expectedOutput": "Successfully connected to V2Ray server", "notes": "File is the card-native services.v2ray JSON object (uuid, port, network, path, security, alterId, ipv4{host,url})" }, { "command": "sudo routing-switch connect xray-vless-reality --config /path/to/xray-profile.json", "description": "Connect a custom Xray profile (xray-vless / xray-vless-reality / xray-trojan / xray-vmess)", "expectedOutput": "Successfully connected to Xray VLESS Reality server", "notes": "File is the card-native services.xray JSON object (domain, protocols{vless|trojan|vmess}, reality_public_key)" }, { "command": "sudo routing-switch connect hysteria2 --config /path/to/hysteria2-profile.json", "description": "Connect a custom Hysteria2 profile", "expectedOutput": "Successfully connected to Hysteria2 server", "notes": "File is the card-native services.hysteria2 JSON object (password, port, protocol, obfs_type, obfs_password, ipv4{host,url})" }, { "command": "sudo routing-switch connect mita --config /path/to/mita-profile.json", "description": "Connect a custom Mita/Mieru profile", "expectedOutput": "Successfully connected to Mita server", "notes": "File is the card-native services.mita JSON object (username, password, port, protocol, mtu, multiplexing, ipv4{host,url})" }, { "command": "sudo routing-switch connect openvpn --config ./vpn.ovpn --force", "description": "Force connection with external config", "expectedOutput": "Disconnecting existing... Connected via external config", "notes": "Combines --config with other flags like --force" }, { "command": "sudo routing-switch connect shadowsocks --config ~/configs/ss.json --no-tun", "description": "External config in no-TUN mode", "expectedOutput": "Shadowsocks SOCKS5 proxy ready at localhost:30000", "notes": "Use external config for manual proxy setup" } ], "id": "external_config", "title": "EXTERNAL CONFIGURATION FILES" }, { "description": "Explicitly choose the IPv4 or the IPv6 endpoint of a protocol. --ipv4 and --ipv6 are mutually exclusive (clap rejects both together). If an IPv6 leak is detected while connecting, routing-switch fails closed and tears the connection down; --allow-ipv6-leak is the only way to override that, and it is documented in DNS MODES AND SECURITY below.", "examples": [ { "command": "sudo routing-switch connect dante --ipv4", "description": "Force IPv4 connection to Dante", "expectedOutput": "Connected via IPv4" }, { "command": "sudo routing-switch connect dante --ipv6", "description": "Force IPv6 connection to Dante", "expectedOutput": "Connected via IPv6", "notes": "Requires IPv6 support" }, { "command": "sudo routing-switch connect shadowsocks --ipv4", "description": "Connect Shadowsocks over IPv4", "expectedOutput": "Shadowsocks connected via IPv4" }, { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect tor --ipv6", "description": "Layer Tor on an active WireGuard tunnel and use the worker's IPv6 Tor SOCKS endpoint", "expectedOutput": "Layering Tor on the active wireguard tunnel ... Tor SOCKS reached over the IPv6 endpoint", "notes": "UNDERLAY REQUIRED: `connect tor` on its own is refused. Kodachi's Tor SOCKS proxy is bound to the VPN network only (never exposed on a public IP), so a Kodachi tunnel (wg0, tun0 or tun_routing) must already be up. --ipv6 picks the card's IPv6 Tor endpoint, so both the underlay and the worker need working IPv6." }, { "command": "sudo routing-switch connect xray-vless --ipv6", "description": "Use IPv6 for Xray VLESS", "expectedOutput": "Xray VLESS connected via IPv6" }, { "command": "sudo routing-switch connect hysteria2 --ipv4", "description": "Connect Hysteria2 over IPv4", "expectedOutput": "Hysteria2 connected via IPv4" }, { "command": "sudo routing-switch connect hysteria2 --ipv6", "description": "Connect Hysteria2 over IPv6", "expectedOutput": "Hysteria2 connected via IPv6", "notes": "Requires IPv6 support" } ], "id": "ip_version", "title": "IPV4/IPV6 SELECTION" }, { "description": "Check and manage network prerequisites for VPN connections", "examples": [ { "command": "sudo routing-switch check-prerequisites", "description": "Check and fix network prerequisites", "expectedOutput": "āœ“ IPv4 forwarding: Already enabled (correct)\nāœ—ā†’āœ“ NAT MASQUERADE: Fixed", "notes": "Fixes only what's wrong, preserves correct settings" }, { "command": "sudo routing-switch check-prerequisites --ipv6", "description": "Check prerequisites for IPv6 connections", "expectedOutput": "āœ“ IPv6 forwarding: Enabled", "notes": "Only enables IPv6 if system supports it" }, { "command": "sudo routing-switch check-prerequisites --json", "description": "Get prerequisites status in JSON format", "expectedOutput": "{\"command\":\"check-prerequisites\",\"data\":{\"prerequisites\":{\"checks\":[...],\"ready\":true}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "sudo routing-switch connect shadowsocks", "description": "Connect with automatic prerequisites check", "expectedOutput": "Checking network prerequisites...\nāœ“ All checks passed\n\nConnecting to shadowsocks...", "notes": "Prerequisites are checked by default" }, { "command": "sudo routing-switch connect shadowsocks --skip-prerequisites", "description": "Connect without prerequisites check", "expectedOutput": "Connecting to shadowsocks...", "notes": "Skips prerequisites for backward compatibility" }, { "command": "sudo routing-switch connect wireguard --force", "description": "Force reconnection with prerequisites check", "expectedOutput": "Checking network prerequisites...\nForcing new connection...", "notes": "Prerequisites persist after disconnect for other VPN tools" } ], "id": "prerequisites", "title": "NETWORK PREREQUISITES" }, { "description": "Check and monitor connection status", "examples": [ { "command": "sudo routing-switch status", "description": "Show current connection status", "expectedOutput": "Connection Status: CONNECTED\nā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”\nSource: Kodachi VPS card\nProtocol: wireguard\nServer: ...\nUptime: 0h 42m 11s\nTUN Device: wg0", "notes": "Requires sudo for accurate results (reads privileged system state). No online-auth login needed: status is auth-exempt." }, { "command": "sudo routing-switch status --detailed", "description": "Status plus the exact timestamp the connection was established", "expectedOutput": "Connection Status: CONNECTED\nā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”ā”\nSource: Kodachi VPS card\nProtocol: wireguard\nServer: ...\nUptime: 0h 42m 11s\nTUN Device: wg0\nConnected Since: 2026-07-13T09:12:41Z", "notes": "--detailed adds the Connected Since line on top of the normal status block. Everything else is the same." }, { "command": "sudo routing-switch status --json", "description": "Get status in JSON format", "expectedOutput": "{\"command\":\"status\",\"data\":{\"connected\":true,\"protocol\":\"wireguard\",\"connected_since\":\"...\",\"server\":\"...\",\"tun_device\":\"wg0\",\"uptime\":\"...\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "sudo routing-switch status --json-pretty", "description": "Pretty-printed JSON status", "expectedOutput": "Formatted JSON with connection details" }, { "command": "sudo routing-switch status --json-human", "description": "Human-readable JSON status", "expectedOutput": "Enhanced JSON output with descriptions" } ], "id": "status", "title": "CONNECTION STATUS" }, { "description": "Control DNS routing for security and compatibility (DEFAULT: auto mode)", "examples": [ { "command": "sudo routing-switch connect wireguard", "description": "DEFAULT: Auto mode (no special DNS routing)", "expectedOutput": "DNS handled naturally through tunnel", "notes": "DEFAULT safe mode - DNS flows through tunnel like all traffic. Note: May not work with all protocols" }, { "command": "sudo routing-switch connect wireguard --dns-mode auto", "description": "Auto mode: DNS flows naturally through tunnel (explicit)", "expectedOutput": "DNS handled naturally through tunnel", "notes": "Same as omitting --dns-mode; explicit form for scripting" }, { "command": "sudo routing-switch connect wireguard --dns-mode hybrid", "description": "Hybrid mode: VPN server DNS bypasses tunnel", "expectedOutput": "Using hybrid DNS mode: VPN server DNS bypasses, others through tunnel", "notes": "āš ļø WARNING: May cause internet loss! Use 'sudo routing-switch recover' to restore connectivity. Good balance of security and reliability for home/office use when you need LAN access" }, { "command": "sudo routing-switch connect wireguard --dns-mode strict", "description": "Strict mode: ALL DNS through tunnel", "expectedOutput": "Using strict DNS mode: Maximum security", "notes": "Most secure, may fail if VPN server uses hostname" }, { "command": "sudo routing-switch connect wireguard --dns-mode system", "description": "System mode: DNS bypasses tunnel", "expectedOutput": "WARNING: System DNS mode - DNS queries will leak!", "notes": "āš ļø NOT SECURE - DNS leaks! Use only for debugging" }, { "command": "sudo routing-switch connect wireguard --allow-ipv6-leak", "description": "Keep the connection up even when an IPv6 leak is detected (default is fail-closed)", "expectedOutput": "IPv6 leak detected ... continuing anyway because --allow-ipv6-leak was passed", "notes": "DANGER: this is the one flag that deliberately weakens leak protection. By default routing-switch terminates the connection the moment it sees an IPv6 leak, so your real IPv6 address cannot escape. With --allow-ipv6-leak the connection is kept and your real IPv6 address stays reachable to every site you visit. Use it only on a host with no usable IPv6, and only when you accept the deanonymisation risk." }, { "command": "sudo routing-switch connect wireguard --exclude-private", "description": "Exclude private networks from VPN", "expectedOutput": "Private networks will bypass VPN tunnel", "notes": "Keep LAN access while using VPN" }, { "command": "sudo routing-switch connect wireguard --dns-mode hybrid --exclude-private", "description": "Hybrid DNS with private network exclusion", "expectedOutput": "Using hybrid DNS mode with local network access", "notes": "Good for home/office use when you need LAN access" } ], "id": "dns_modes", "title": "DNS MODES AND SECURITY" }, { "description": "Choose between Direct (preferred tunnel route) or Metric (with fallback) routing", "examples": [ { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect tor", "description": "DEFAULT: Direct routing mode (MOST SECURE), Tor layered on WireGuard", "expectedOutput": "Using DIRECT routing: TUN route preferred; original route kept as high-metric recovery", "notes": "āœ… RECOMMENDED, strongest default, paired with leak checks and kill-switch controls. UNDERLAY REQUIRED: `connect tor` on its own is refused, Kodachi's Tor SOCKS proxy is VPN-side only. Connect WireGuard, OpenVPN or a proxy protocol first." }, { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect tor --metric", "description": "Metric routing mode (LESS SECURE, has fallback), Tor layered on WireGuard", "expectedOutput": "Using METRIC routing: Original route kept as backup", "notes": "āš ļø WARNING: can leak traffic if the TUN fails, use only if you need failover. UNDERLAY REQUIRED: `connect tor` on its own is refused, a Kodachi tunnel (wg0, tun0 or tun_routing) must already be up." }, { "command": "sudo routing-switch connect shadowsocks", "description": "Direct mode for Shadowsocks (default)", "expectedOutput": "Direct routing: Shadowsocks TUN route is preferred", "notes": "Strongest default; leak checks and health controls decide failure handling" }, { "command": "sudo routing-switch connect dante --metric", "description": "Metric mode for corporate VPN scenarios", "expectedOutput": "Metric routing: Fallback to original connection if VPN drops", "notes": "Use for work VPNs where you need automatic failover" }, { "command": "sudo routing-switch connect xray-vless --metric --exclude-private", "description": "Metric mode with LAN access preserved", "expectedOutput": "Failover routing with local network bypass", "notes": "Corporate setup: VPN with failover + LAN access" } ], "id": "routing_modes", "title": "ROUTING MODES - SECURITY vs FAILOVER" }, { "description": "Disconnect and restore normal routing", "examples": [ { "command": "sudo routing-switch disconnect", "description": "Disconnect current proxy", "expectedOutput": "Successfully disconnected" }, { "command": "sudo routing-switch disconnect --force", "description": "Force disconnect even if issues", "expectedOutput": "Force disconnected", "notes": "Kills all processes forcefully" }, { "command": "sudo routing-switch disconnect --clean-firewall", "description": "Disconnect and clean all firewall rules", "expectedOutput": "Disconnected and firewall rules cleaned", "notes": "Use when network is stuck after disconnect due to lingering iptables rules" }, { "command": "sudo routing-switch disconnect --force --clean-firewall", "description": "Force disconnect with complete firewall cleanup", "expectedOutput": "Force disconnected, all firewall rules flushed", "notes": "Emergency recovery - resets all iptables rules (preserves Docker/KVM chains)" }, { "command": "sudo routing-switch disconnect --json", "description": "Disconnect with JSON output", "expectedOutput": "{\"command\":\"disconnect\",\"data\":{\"status\":\"disconnected\",\"message\":\"...\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "disconnect", "title": "DISCONNECTION" }, { "description": "Understanding --force behavior and which protocols can layer together.\nPROTOCOL TYPES: native VPNs own their interface (openvpn -> tun0, wireguard -> wg0). Tor is redsocks based (iptables NAT, no interface of its own). Everything else is tun2socks based and shares ONE device, tun_routing: shadowsocks, dante, v2ray, xray-vless, xray-vless-reality, xray-trojan, xray-vmess, mita, hysteria2.\nCOMPATIBILITY: native + Tor layers cleanly, and a proxy protocol + Tor layers cleanly. Two tun2socks protocols never do, they fight over tun_routing.\nRECOMMENDED LAYERING: connect WireGuard or OpenVPN (or one proxy protocol) FIRST, then `connect tor` on top. --force is not needed for that, Tor-over-VPN is allowed through the single-connection guard on purpose. Use --force only when you want to REPLACE the active connection with a different one. Always re-test connectivity after layering.", "examples": [ { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect tor", "description": "Creates LAYERED connection: Tor-over-WireGuard āœ“ (no --force needed)", "expectedOutput": "ā†’ connect tor detects the active WireGuard tunnel and layers on it\n ā†’ WireGuard's wg0 stays up; Tor SOCKS reached at 10.0.0.1:9050 via wg0\n ā†’ Tor's iptables rules redirect traffic on top", "notes": "LAYERED: connect tor keeps the VPN as its underlay (does NOT disconnect it). Traffic: App ā†’ Tor (redsocks) ā†’ WireGuard ā†’ Internet. Required: the worker Tor is VPN-only." }, { "command": "sudo routing-switch connect openvpn && sudo routing-switch connect tor", "description": "Creates LAYERED connection: Tor-over-OpenVPN āœ“ (no --force needed)", "expectedOutput": "ā†’ connect tor detects the active OpenVPN tunnel and layers on it\n ā†’ Traffic: Your App ā†’ Tor (redsocks) ā†’ OpenVPN (tun0) ā†’ Internet\n ā†’ Tor SOCKS reached at 172.16.0.1:9050 via tun0", "notes": "connect tor keeps OpenVPN as its underlay. Tor uses iptables NAT, no interface conflict with tun0. The worker Tor is VPN-only - it cannot be connected standalone." }, { "command": "sudo routing-switch connect shadowsocks && sudo routing-switch connect tor", "description": "Creates LAYERED connection: Tor-over-proxy āœ“ (works for shadowsocks/v2ray/xray/hysteria2/mita)", "expectedOutput": "ā†’ connect tor detects the active proxy tunnel (tun_routing) and layers on it\n ā†’ Traffic: Your App ā†’ Tor (redsocks) ā†’ Shadowsocks ā†’ Internet\n ā†’ Tor SOCKS reached at 172.16.0.1:9050 via tun_routing", "notes": "connect tor keeps the proxy protocol as its underlay. Works the same for all proxy protocols (shadowsocks/v2ray/xray/hysteria2/mita) - they all ride the tun2socks tun_routing device. The underlay's own uplink to its worker is auto-excluded from the Tor redirect so the tunnel is not broken." }, { "command": "sudo routing-switch connect shadowsocks && sudo routing-switch connect dante", "description": "REFUSED: two tun2socks protocols cannot both be up āœ—", "expectedOutput": "ā†’ Error: Already connected via shadowsocks. Use 'routing-switch disconnect' first or use --force flag", "notes": "All tun2socks protocols (shadowsocks, dante, v2ray, xray-*, mita, hysteria2) share the same tun_routing device, so they cannot coexist. Adding --force does NOT stack them: it disconnects shadowsocks first and then connects dante." }, { "command": "sudo routing-switch connect wireguard && sudo routing-switch connect openvpn --force", "description": "REPLACE the active connection: --force disconnects WireGuard, then dials OpenVPN", "expectedOutput": "ā†’ Existing wireguard connection detected\n ā†’ Disconnecting it (--force)\n ā†’ Successfully connected to OpenVPN server", "notes": "This is what --force is actually for: swapping one connection for another. It does NOT stack two VPNs. Without --force the second connect is refused with 'another connection is active'." } ], "id": "force_reconnect", "title": "FORCE FLAG & PROTOCOL COMPATIBILITY" }, { "description": "Check DNS configuration", "examples": [ { "command": "routing-switch dns-info", "description": "Show current DNS servers", "expectedOutput": "IPv4: <VPN_IP>:53, IPv6: [<VPN_IPv6>]:53" }, { "command": "routing-switch dns-info --json", "description": "DNS info in JSON format", "expectedOutput": "{\"command\":\"dns-info\",\"data\":{\"ipv4\":{\"host\":\"<VPN_IP>\",\"port\":53},\"ipv6\":{\"host\":\"<VPN_IPv6>\",\"port\":53}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "dns_info", "title": "DNS INFORMATION" }, { "description": "Check Tor DNS and SOCKS configuration", "examples": [ { "command": "routing-switch tor-dns-info", "description": "Show Tor DNS and SOCKS endpoints", "expectedOutput": "DNS: dns://<VPS_IP>:9054#Tor-DNS", "notes": "Resolves both regular and .onion domains" }, { "command": "routing-switch tor-dns-info --json", "description": "Tor DNS info in JSON format", "expectedOutput": "{\"command\":\"tor-dns-info\",\"data\":{\"ipv4\":{\"dns_url\":\"dns://...\",\"socks_url\":\"socks5://...\"}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "tor_dns_info", "title": "TOR DNS INFORMATION" }, { "description": "Display VPS server details and statistics", "examples": [ { "command": "routing-switch vps-info", "description": "Show basic VPS information", "expectedOutput": "Hostname: <type>-<random>, IPv4: <VPS_IP>" }, { "command": "routing-switch vps-info --detailed", "description": "Show detailed VPS stats", "expectedOutput": "CPU Load, Memory Usage, Uptime, Network Connections", "notes": "Includes CPU load, memory, uptime, and connection stats" }, { "command": "routing-switch vps-info --json", "description": "VPS info in JSON format", "expectedOutput": "{\"command\":\"vps-info\",\"data\":{\"hostname\":\"...\",\"cpu_load\":{...},\"memory\":{...},\"card_type\":\"...\",\"generation_t\":\"...\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "vps_info", "title": "VPS SERVER INFORMATION" }, { "description": "List available protocols with scores", "examples": [ { "command": "routing-switch list-protocols", "description": "List all available protocols", "expectedOutput": "WireGuard (Score: 96.5), OpenVPN (Score: 94.0)..." }, { "command": "routing-switch list-protocols --json", "description": "Protocol list in JSON", "expectedOutput": "{\"command\":\"list-protocols\",\"data\":{\"protocols\":[{\"name\":\"wireguard\",\"overall_score\":96.5,\"available\":true,...}],\"scoring\":{...}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "routing-switch list-protocols --detailed", "description": "Show the full scoring breakdown per protocol, not just the overall score", "expectedOutput": "wireguard overall 96.5 security 98.0 speed 99.0 stability 95.0 available yes" }, { "command": "routing-switch list-protocols --test", "description": "Probe each protocol's endpoint for real instead of scoring from the card alone", "expectedOutput": "Testing connectivity ... wireguard [OK] 12ms, shadowsocks [OK] 45ms, v2ray [FAIL]", "notes": "Slower (it opens a connection per protocol) but far more accurate than the static scores. Needs network access." }, { "command": "routing-switch list-protocols --available-only", "description": "Show only available protocols", "expectedOutput": "Available: WireGuard, Tor, Shadowsocks", "notes": "Based on auth card" }, { "command": "routing-switch list-protocols --sort-by-security", "description": "Sort by security score", "expectedOutput": "1. WireGuard (98.0), 2. OpenVPN (95.0)..." }, { "command": "routing-switch list-protocols --sort-by-speed", "description": "Sort by speed score", "expectedOutput": "1. WireGuard (99.0), 2. Shadowsocks (85.0)..." } ], "id": "list_protocols", "title": "PROTOCOL LISTING" }, { "description": "Automatically select best protocol", "examples": [ { "command": "sudo routing-switch auto-select", "description": "Auto-select best protocol", "expectedOutput": "Selected WireGuard (best overall score)" }, { "command": "sudo routing-switch auto-select --min-security 90", "description": "Auto-select with minimum security", "expectedOutput": "Selected OpenVPN (security: 95.0)" }, { "command": "sudo routing-switch auto-select --prefer-speed", "description": "Prioritize speed in selection", "expectedOutput": "Selected WireGuard (fastest protocol)" }, { "command": "sudo routing-switch auto-select --json", "description": "Auto-select with JSON output", "expectedOutput": "{\"command\":\"auto-select\",\"data\":{\"selected\":\"wireguard\",\"reason\":\"best overall score (95.5)\",\"status\":\"connected\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "auto_select", "title": "AUTO-SELECTION" }, { "description": "Local SOCKS5 port allocation reference. When a tun2socks protocol connects it picks the first free port in its own reserved range on 127.0.0.1:\nShadowsocks 30000-30004, V2Ray 30005-30009, Xray VMess 30010-30014, Xray VLESS 30015-30019, VLESS Reality 30020-30024, Xray Trojan 30025-30029, Mieru/Mita 30030-30034, Tor 30035-30039, Dante 30040-30044, Hysteria2 30045-30049, microsocks 30050-30054.\nThe ranges are high (30000+) so they never collide with system services, and each protocol gets its own so two of them can never fight over a port.\nTRAFFIC FLOW (tun2socks protocols): application -> tun_routing interface -> tun2socks -> 127.0.0.1:<PORT> -> protocol client -> remote server.\nNATIVE VPNs are different: WireGuard uses the UDP port from its config (typically 51820) and OpenVPN the TCP/UDP port from its config (typically 1194). Neither uses tun2socks or a local SOCKS5 port.\nKODACHI TOR is VPN-side, not local: its SOCKS5 lives on the worker at 172.16.0.1:9050 over OpenVPN and 10.0.0.1:9050 over WireGuard.", "examples": [ { "command": "sudo routing-switch connect shadowsocks --no-tun", "description": "See the local SOCKS5 port a tun2socks protocol actually took", "expectedOutput": "Shadowsocks SOCKS5 proxy ready at localhost:30000", "notes": "No-TUN mode is the mode that prints the allocated port, because that port is the whole point of it. In normal (TUN) mode the port is internal plumbing between tun2socks and the protocol client, and you never need it." }, { "command": "sudo routing-switch connect v2ray --no-tun --json", "description": "Get the allocated local SOCKS5 port back as JSON (no-TUN mode reports it explicitly)", "expectedOutput": "{\"command\":\"connect\",\"data\":{\"local_proxy_address\":\"127.0.0.1\",\"local_proxy_port\":30005,\"protocol\":\"v2ray\",\"mode\":\"no-tun\"},...}" } ], "id": "port_usage", "title": "PORT USAGE INFORMATION" }, { "description": "Different JSON output options", "examples": [ { "command": "sudo routing-switch status --json", "description": "Compact JSON output", "expectedOutput": "{\"command\":\"connect\",\"data\":{\"status\":\"connected\",\"protocol\":\"tor\",\"tun_device\":\"...\",\"server\":\"...\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Requires sudo for accurate results" }, { "command": "sudo routing-switch status --json-pretty", "description": "Pretty-printed JSON", "expectedOutput": "{\n \"command\": \"status\",\n \"data\": {\n \"connected\": true,\n \"protocol\": \"tor\",\n ...\n },\n \"errors\": [],\n \"metadata\": {...},\n \"status\": \"success\",\n \"timestamp\": \"...\",\n \"version\": \"<VERSION>\",\n \"warnings\": []\n}" }, { "command": "sudo routing-switch status --json-human", "description": "Human-enhanced JSON", "expectedOutput": "JSON with descriptions and metadata" }, { "command": "routing-switch list-protocols --json --json-pretty", "description": "Pretty JSON protocol list", "expectedOutput": "Formatted JSON array of protocols" } ], "id": "json_formats", "title": "JSON OUTPUT FORMATS" }, { "description": "Test protocol performance", "examples": [ { "command": "routing-switch benchmark", "description": "Benchmark all protocols (3 iterations default)", "expectedOutput": "Measured TCP connection latency for each available protocol", "notes": "This command measures reachability latency only; it does not claim download or upload throughput" }, { "command": "routing-switch benchmark --iterations 5", "description": "Benchmark with custom iteration count", "expectedOutput": "Five measured TCP connection latency probes per protocol", "notes": "More iterations = more accurate results" }, { "command": "routing-switch benchmark --json", "description": "Benchmark results in JSON", "expectedOutput": "{\"command\":\"benchmark\",\"data\":{\"results\":[{\"protocol\":\"wireguard\",\"avg_latency_ms\":42,\"successful_probes\":3}],\"iterations\":3},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "benchmark", "title": "BENCHMARKING" }, { "description": "Probe a protocol's endpoint without touching routing. Reads the endpoints from the auth card, so it needs a prior online-auth login.", "examples": [ { "command": "routing-switch test-protocol tor", "description": "Test whether the worker's Tor SOCKS endpoint is reachable", "expectedOutput": "Tor: SOCKS5 endpoint <worker_ip>:9050 reachable", "notes": "Does not change routing. The endpoint comes from the auth card's Tor socks_url, so it is the worker address (VPN-side), never 127.0.0.1. Without a tunnel up it will simply report unreachable, which is expected." }, { "command": "routing-switch test-protocol shadowsocks --extended", "description": "Extended protocol test", "expectedOutput": "Shadowsocks: Connected, Latency: 45ms, Throughput: OK" }, { "command": "routing-switch test-protocol all", "description": "Test all available protocols", "expectedOutput": "Testing: Tor [OK], Shadowsocks [OK], V2Ray [FAIL]..." }, { "command": "routing-switch test-protocol wireguard --json", "description": "Test with JSON output", "expectedOutput": "{\"command\":\"test-protocol\",\"data\":{\"protocol\":\"wireguard\",\"status\":\"ok\",\"available\":true,\"connectivity\":true,\"latency_ms\":12},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "test_protocol", "title": "TESTING PROTOCOLS" }, { "description": "Run a proxy client without creating a TUN device, so system traffic is untouched and only the apps you point at the local SOCKS5 port go through it.\nConfigure the client by hand: Firefox -> Settings -> Network Settings -> Manual proxy -> SOCKS5 host 127.0.0.1, port <the allocated port>. Chrome/Chromium: start it with --proxy-server=\"socks5://127.0.0.1:30000\".\n--no-tun works for the tun2socks protocols (shadowsocks, dante, v2ray, xray-*, mita, hysteria2). It does NOT work for `connect tor`: Kodachi's Tor is redsocks/iptables based and rejects --no-tun outright (see the tor entry below).", "examples": [ { "command": "sudo routing-switch connect shadowsocks --no-tun", "description": "Start Shadowsocks SOCKS5 proxy without TUN", "expectedOutput": "Shadowsocks SOCKS5 proxy ready at localhost:30000", "notes": "Configure browser/app manually with localhost:30000" }, { "command": "sudo routing-switch connect dante --no-tun", "description": "Connect to Dante SOCKS5 without routing traffic", "expectedOutput": "Dante proxy: host:port, username, password", "notes": "Direct connection to remote Dante server" }, { "command": "sudo routing-switch connect wireguard && routing-switch tor-dns-info", "description": "Use Kodachi's Tor as a manual proxy: connect a VPN, then read the Tor SOCKS endpoint and point your app at it", "expectedOutput": "SOCKS: socks5://10.0.0.1:9050 (over WireGuard) or socks5://172.16.0.1:9050 (over OpenVPN)", "notes": "`connect tor --no-tun` is NOT supported and fails with 'Tor via redsocks does not support no-TUN mode'. Kodachi's Tor is redsocks/iptables based, and its SOCKS5 lives on the worker inside the VPN network (10.0.0.1:9050 over WireGuard, 172.16.0.1:9050 over OpenVPN), never on 127.0.0.1. So the manual-proxy path for Tor is: connect a Kodachi VPN, then set your browser's SOCKS5 proxy to that worker address." }, { "command": "sudo routing-switch connect v2ray --no-tun --json", "description": "V2Ray proxy in manual mode with JSON output", "expectedOutput": "{\"command\":\"connect\",\"data\":{\"local_proxy_address\":\"127.0.0.1\",\"local_proxy_port\":30005,\"protocol\":\"v2ray\",\"mode\":\"no-tun\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "V2Ray client runs, no system routing" }, { "command": "sudo routing-switch connect xray-vless --no-tun", "description": "Xray VLESS proxy for manual configuration", "expectedOutput": "Xray SOCKS5 proxy ready at localhost:30015" }, { "command": "sudo routing-switch disconnect", "description": "Stop the proxy (works for both TUN and no-TUN modes)", "expectedOutput": "Proxy stopped" } ], "id": "no_tun_mode", "title": "NO-TUN MODE (MANUAL PROXY)" }, { "description": "Export and display protocol configurations", "examples": [ { "command": "routing-switch export-config", "description": "Export all configurations to default location", "expectedOutput": "Exported 9 configuration(s) to ./results/configs/", "notes": "Creates timestamped config files" }, { "command": "routing-switch export-config wireguard", "description": "Export specific protocol configuration", "expectedOutput": "Exported 1 configuration(s) to ./results/configs/\n - wireguard: wireguard_20250817_143022.conf" }, { "command": "routing-switch export-config all --path /tmp/vpn-configs/", "description": "Export all configs to custom path", "expectedOutput": "Exported 9 configuration(s) to /tmp/vpn-configs/", "notes": "Creates directory if it doesn't exist" }, { "command": "routing-switch export-config shadowsocks --include-credentials", "description": "Export with credentials included", "expectedOutput": "Exported 1 configuration(s) to ./results/configs/", "notes": "āš ļø WARNING: Contains sensitive passwords" }, { "command": "routing-switch export-config --json", "description": "Export with JSON output showing results", "expectedOutput": "{\"command\":\"export-config\",\"data\":{\"exported_count\":9,\"export_directory\":\"./results/configs/\",\"files\":[...]},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "routing-switch showconfig wireguard", "description": "Display WireGuard configuration", "expectedOutput": "{\"command\":\"showconfig\",\"data\":{\"protocol\":\"wireguard\",\"config\":{\"available\":true,\"config_content\":\"[Interface]\\nPrivateKey = ...\",\"masked\":false,\"name\":\"wireguard\",\"status\":\"available\"},\"masked\":false},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Masks sensitive data by default" }, { "command": "routing-switch showconfig all --json-pretty", "description": "Show all protocol configs in pretty JSON", "expectedOutput": "Formatted JSON with all available protocol configurations" }, { "command": "routing-switch showconfig dante --mask-sensitive", "description": "Show config with passwords hidden", "expectedOutput": "{\"command\":\"showconfig\",\"data\":{\"protocol\":\"dante\",\"config\":{\"username\":\"dante_user\",\"password\":\"***REDACTED***\",\"ipv4_url\":\"socks5://dante_user:***REDACTED***@...\",...},\"masked\":true},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Safe for sharing/logging" }, { "command": "routing-switch showconfigurl shadowsocks", "description": "Get Shadowsocks connection URL", "expectedOutput": "ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTp6TDQ4cVYx...@<VPN_IP>:8388#Shadowsocks-IPv4", "notes": "URL can be imported into mobile apps" }, { "command": "routing-switch showconfigurl dante --json", "description": "Get SOCKS5 URLs in JSON format", "expectedOutput": "{\"ipv4\": \"socks5://user:pass@<VPN_IP>:1080\", \"ipv6\": \"socks5://user:pass@[<VPN_IPv6>]:1080\"}" }, { "command": "routing-switch showconfigurl all", "description": "Get URLs for all available protocols", "expectedOutput": "Protocol Connection URLs:\n\nshadowsocks:\n ipv4: ss://...\n\ndante:\n ipv4: socks5://..." }, { "command": "routing-switch showconfigqr wireguard", "description": "Generate QR code for WireGuard config", "expectedOutput": "[QR Code ASCII Art]\n\nURL: wireguard://base64_encoded_config", "notes": "Scan with WireGuard mobile app" }, { "command": "routing-switch showconfigqr shadowsocks", "description": "Generate IPv4 QR code for Shadowsocks (default)", "expectedOutput": "[QR Code ASCII Art]\n\nURL: ss://...", "notes": "Shows IPv4 QR code by default for dual-stack protocols" }, { "command": "routing-switch showconfigqr shadowsocks --ipv6", "description": "Generate IPv6 QR code for Shadowsocks", "expectedOutput": "[QR Code ASCII Art]\n\nURL: ss://...", "notes": "Use --ipv6 flag to show IPv6 QR for dual-stack protocols" }, { "command": "routing-switch showconfigqr shadowsocks --skip-validation", "description": "Generate QR without validation (faster)", "expectedOutput": "[QR Code ASCII Art]\n\nāš  Validation skipped", "notes": "Skips automatic QR validation for debugging" }, { "command": "routing-switch showconfigqr all --strict-validation", "description": "Generate all QR codes with strict validation", "expectedOutput": "āœ“ Shadowsocks QR validated\nāœ“ WireGuard QR validated...", "notes": "Fails if any QR code validation fails" }, { "command": "routing-switch showconfigqr dante --json", "description": "Get QR data in JSON format", "expectedOutput": "{\"command\":\"showconfigqr\",\"data\":{\"protocol\":\"dante\",\"qr\":{\"content_type\":\"image/png\",\"format\":\"ipv4\",\"protocol\":\"dante\",\"qr_code\":\"<base64-png>\",\"url\":\"socks5://...\",\"validated\":true}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "JSON includes the URL for QR generation" }, { "command": "routing-switch showconfigqr shadowsocks --save-files", "description": "Generate QR code and save as PNG file", "expectedOutput": "[QR Code ASCII Art]\n\nāœ“ IPv4 QR code files saved to ./results/qr-codes/", "notes": "Saves clean PNG file: shadowsocks_ipv4.png" }, { "command": "routing-switch showconfigqr shadowsocks --ipv6 --save-files", "description": "Generate IPv6 QR code and save as PNG file", "expectedOutput": "[QR Code ASCII Art]\n\nāœ“ IPv6 QR code files saved to ./results/qr-codes/", "notes": "Saves clean PNG file: shadowsocks_ipv6.png" }, { "command": "routing-switch showconfigqr shadowsocks --ipv4 --ipv6 --save-files", "description": "Generate both IPv4 and IPv6 QR codes", "expectedOutput": "[QR Code ASCII Art]\n\nāœ“ IPv4 and IPv6 QR code files saved to ./results/qr-codes/", "notes": "Saves both shadowsocks_ipv4.png and shadowsocks_ipv6.png" }, { "command": "routing-switch showconfigqr all --save-files --json-pretty", "description": "Generate all QR codes with pretty JSON output", "expectedOutput": "Pretty-formatted JSON with QR data and file paths", "notes": "Creates clean PNG files for all available protocols, supports all JSON formats" }, { "command": "routing-switch showconfigqr wireguard --save-files --json-human", "description": "Save QR file with human-enhanced JSON output", "expectedOutput": "{\"command\":\"showconfigqr\",\"data\":{\"protocol\":\"wireguard\",\"qr\":{\"qr_code\":\"<base64-png>\",\"saved_file_path\":\"./results/qr-codes/wireguard.png\",...}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "VPN protocols use single filename (no IP version suffix)" } ], "id": "config_export", "title": "CONFIGURATION EXPORT AND DISPLAY" }, { "description": "Validate QR codes against auth card", "examples": [ { "command": "routing-switch validate-qr shadowsocks_ipv4.png", "description": "Validate QR code from image file (NEW: direct filename)", "expectedOutput": "āœ“ QR valid: Shadowsocks (confidence: 98.5%)", "notes": "Smart detection: automatically finds file in current dir or results/qr-codes/" }, { "command": "routing-switch validate-qr dante_ipv4.png", "description": "Validate QR code from results/qr-codes directory", "expectedOutput": "āœ“ QR valid: Dante (confidence: 96.2%)", "notes": "Automatically looks in ./results/qr-codes/ if not found in current directory" }, { "command": "routing-switch validate-qr --file shadowsocks_qr.png", "description": "Validate QR code using explicit --file flag (legacy syntax)", "expectedOutput": "āœ“ QR valid: Shadowsocks (confidence: 98.5%)", "notes": "Both direct filename and --file flag work identically" }, { "command": "echo 'ss://...' | routing-switch validate-qr --stdin", "description": "Validate QR URL from stdin", "expectedOutput": "āœ“ Protocol: shadowsocks\nāœ“ Config matches auth card", "notes": "Useful for clipboard validation" }, { "command": "routing-switch validate-qr all", "description": "Validate all generated QR codes", "expectedOutput": "Validating all QR codes...\nāœ“ shadowsocks_ipv4.png: valid\nāœ“ wireguard.png: valid", "notes": "Checks all QR codes in results/qr-codes/" }, { "command": "routing-switch validate-qr --test-readability shadowsocks", "description": "Test QR code readability", "expectedOutput": "Testing QR readability...\nāœ“ QR code is readable", "notes": "Round-trip test of QR generation" }, { "command": "routing-switch validate-qr qr_code.png --json", "description": "JSON validation output", "expectedOutput": "{\"command\":\"validate-qr\",\"data\":{\"is_valid\":true,\"protocol\":\"shadowsocks\",\"confidence_score\":0.985,\"config_data\":{...}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Machine-readable validation results" } ], "id": "qr_validation", "title": "QR CODE VALIDATION" }, { "description": "Recover from a broken or half-torn-down connection. reset, cleanup, recover and a plain disconnect are all auth-exempt on purpose: they have to work when the network (and therefore online-auth) is down.", "examples": [ { "command": "sudo routing-switch disconnect --force", "description": "Force disconnect stuck connection", "expectedOutput": "Force killed all processes, routes restored", "notes": "Use when normal disconnect fails" }, { "command": "sudo routing-switch reset", "description": "Reset all routing to default", "expectedOutput": "Routing reset to system defaults", "notes": "Emergency recovery command" }, { "command": "sudo routing-switch reset --force", "description": "Reset routing even when the state file says something is still connected", "expectedOutput": "Forcing reset ... Routing reset to system defaults", "notes": "DESTRUCTIVE: tears down the active tunnel, its routes and its DNS overrides without asking. Your traffic goes back to the clear-net default route, so you are NOT anonymised afterwards. Use only when a normal disconnect will not complete." }, { "command": "sudo routing-switch cleanup", "description": "Clean up orphaned processes", "expectedOutput": "Cleaned up 2 orphaned tun2socks processes" }, { "command": "sudo routing-switch cleanup --thorough", "description": "Deeper sweep: also removes leftover TUN devices, routes and iptables rules, not just stray processes", "expectedOutput": "Thorough cleanup: killed 2 orphaned processes, removed tun_routing, dropped 6 stale iptables rules", "notes": "Heavier than plain cleanup and can disturb an active connection, so run it after disconnecting." }, { "command": "sudo routing-switch recover", "description": "Automatically diagnose and fix routing issues, restore network settings", "expectedOutput": "System recovered, ready for new connection", "notes": "Performs comprehensive recovery including cleanup, route restoration, and DNS reset" }, { "command": "sudo routing-switch recover --force", "description": "Run the recovery even when routing-switch thinks nothing is wrong", "expectedOutput": "Forced recovery: cleanup, routes restored, DNS reset, ready for new connection", "notes": "DESTRUCTIVE: drops any active tunnel and restores the clear-net default route, so you lose VPN/Tor protection. This is the last-resort 'my internet is stuck' command." } ], "id": "error_recovery", "title": "ERROR RECOVERY" }, { "description": "Turn this Kodachi box into a SOCKS5 proxy server so other devices on your LAN can ride its active tunnel.\nWORKFLOW: 1) connect routing-switch to any protocol (WireGuard, OpenVPN, V2Ray, Shadowsocks, Hysteria2, ...). 2) `microsocks-enable` with a username and password. 3) On the other device, set SOCKS5 host = this machine's LAN IP, port = the listening port (30050-30054), plus those credentials. All of that device's traffic then leaves through this machine's tunnel.\nmicrosocks-enable and microsocks-disable need root AND a prior online-auth login. microsocks-status is auth-exempt.\nSECURITY: the listener binds 0.0.0.0, so anything that can reach this host on that port can try to use it. Pick a strong password, and disable the server when you are done.", "examples": [ { "command": "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'", "description": "Enable microsocks server with auto port detection", "expectedOutput": "Microsocks server started on port 30050, listening on all interfaces", "notes": "Automatically selects available port from 30050-30054 range. Used when Kodachi acts as a server. After connecting routing-switch to any service (WireGuard, V2Ray, etc.), enable microsocks so other PCs on your network can connect through this machine using the listening microsocks port. Strong credentials recommended for security." }, { "command": "sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' --port 30051", "description": "Enable with specific port", "expectedOutput": "Microsocks server started on port 30051", "notes": "Use when you need a specific port number within the 30050-30054 range" }, { "command": "sudo routing-switch microsocks-status", "description": "Check microsocks server status", "expectedOutput": "Status: Running, Port: 30050, PID: 12345", "notes": "Requires sudo for accurate results (reads privileged state)" }, { "command": "sudo routing-switch microsocks-status --json", "description": "Check status in JSON format", "expectedOutput": "{\"command\":\"microsocks-status\",\"data\":{\"status\":\"running\",\"running\":true,\"port\":30050,\"pid\":12345,\"listening_address\":\"0.0.0.0\",\"username\":\"...\",\"started_at\":\"...\",\"uptime_seconds\":...},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "sudo routing-switch microsocks-disable", "description": "Stop microsocks server", "expectedOutput": "Microsocks server stopped successfully" }, { "command": "sudo routing-switch connect wireguard && sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'", "description": "Complete server workflow: bring up a tunnel, then share it over SOCKS5", "expectedOutput": "Successfully connected to WireGuard server\nMicrosocks server started on port 30050, listening on all interfaces", "notes": "The other device then points its SOCKS5 client at socks5://microkodachi-8273:<password>@<this-machine-LAN-IP>:30050 (for example 192.168.1.100:30050). Its traffic leaves through this machine's WireGuard tunnel. Order matters: enable microsocks AFTER the tunnel is up." } ], "id": "microsocks_server", "title": "MICROSOCKS SERVER MODE" }, { "description": "Use the free VPNGate public server pool.\nAUTH: browsing is auth-free (vpngate-fetch, vpngate-list, vpngate-export, vpngate-export-all all work on a fresh shell). `vpngate-connect` is NOT auth-free: it mutates routes, DNS and firewall exactly like `connect`, so it goes through the same online-auth gate and needs root. The servers themselves cost nothing, the auth gate is Kodachi's, not VPNGate's.", "examples": [ { "command": "routing-switch vpngate-fetch", "description": "Fetch VPNGate server list from public API", "expectedOutput": "Fetched 150 VPNGate servers", "notes": "Downloads and caches server list (refreshes every hour)" }, { "command": "routing-switch vpngate-list", "description": "List all cached VPNGate servers", "expectedOutput": "Index Flag Country IP Speed Ping Score Sessions", "notes": "Shows servers sorted by score (default)" }, { "command": "routing-switch vpngate-list --country JP --sort speed -l 10", "description": "List top 10 Japanese servers by speed", "expectedOutput": "10 servers shown, filtered by country: JP", "notes": "Filter by country name or code, sort by speed/ping/score/sessions" }, { "command": "routing-switch vpngate-list --country US --sort ping", "description": "List US servers sorted by lowest ping", "expectedOutput": "Servers sorted by ping latency" }, { "command": "routing-switch vpngate-list --sort sessions -l 10", "description": "List the 10 least congested servers (fewest active VPN sessions)", "expectedOutput": "Servers sorted by session count, lowest first", "notes": "--sort accepts score (default, highest first), speed (highest first), ping (lowest first) and sessions (LOWEST first, i.e. least crowded)." }, { "command": "sudo routing-switch vpngate-connect 5", "description": "Connect to VPNGate server at index 5", "expectedOutput": "Successfully connected to <server> via openvpn", "notes": "Uses OpenVPN with the public vpn/vpn credentials. REQUIRES AUTHENTICATION: unlike vpngate-fetch/list/export, this one establishes a connection, so it goes through the online-auth gate and needs root. Index comes from vpngate-list, so fetch and list first." }, { "command": "sudo routing-switch vpngate-connect 12 --force", "description": "Force connect to server 12 (disconnect existing first)", "expectedOutput": "Force connected to VPNGate server" }, { "command": "sudo routing-switch vpngate-connect 3 --skip-prerequisites", "description": "Connect without running the network prerequisite checks first", "expectedOutput": "Connecting to VPNGate server 3 (prerequisite checks skipped)", "notes": "Skips the IPv4-forwarding / NAT / MASQUERADE checks. Only use it if you know those are already correct: on a box that is not set up, the connection can come up half-broken." }, { "command": "routing-switch vpngate-fetch --json", "description": "Fetch servers with JSON output", "expectedOutput": "{\"command\":\"vpngate-fetch\",\"data\":{\"status\":\"success\",\"server_count\":150,\"cache_file\":\"...\",\"fetched_at\":\"...\"},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "routing-switch vpngate-list --json-pretty", "description": "List servers in pretty JSON format", "expectedOutput": "Pretty-printed JSON array of servers" }, { "command": "routing-switch vpngate-export 1", "description": "Export top server's OpenVPN config as .ovpn file", "expectedOutput": "Exported: JP Japan (1.2.3.4) -> results/vpngate-configs/1_jp_1-2-3-4.ovpn", "notes": "Includes embedded vpn/vpn credentials for standalone use" }, { "command": "routing-switch vpngate-export-all", "description": "Export all cached servers as .ovpn files", "expectedOutput": "Exported 99 VPNGate configs to results/vpngate-configs", "notes": "Bulk export for use in external OpenVPN clients" }, { "command": "routing-switch vpngate-export 5 --json", "description": "Export server #5 config with JSON output", "expectedOutput": "{\"command\":\"vpngate-export\",\"data\":{\"action\":\"vpngate-export\",\"file\":\"...\",\"server\":{\"index\":5,\"country\":\"...\",\"country_code\":\"...\",\"flag\":\"...\",\"ip\":\"...\",\"speed\":\"...\",\"ping\":...,\"score\":...}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" } ], "id": "vpngate_free_vpn", "title": "VPNGATE FREE VPN" }, { "description": "Browse, fetch, and connect through commercial and free third-party VPN providers (VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad-WG).\nThis is the largest surface in routing-switch: 20 verbs under `routing-switch providers`. Run `routing-switch providers --help` for the full list.\nAUTH: EVERY `providers` verb requires a prior online-auth login, including the read-only ones (list, list-profiles, get-profile). The catalog and the fetched configs are curated content, not open scrape targets.\nSUDO: any verb that writes the provider cache needs root, because the cache lives under dashboard/hooks/cache/vpn-providers/<id>/ which is root-owned in /opt. That is fetch, get-profile (it lazily fetches on a cache miss), import-config, delete-custom-profile, delete-custom-profiles-bulk, resolve-country, resolve-ip, resolve-ips, benchmark, clear-cache, credentials-set, credentials-delete, and all three connect verbs. Only `list`, `list-profiles`, `credentials-list`, `refresh-catalog` and `validate-config` are pure reads.", "examples": [ { "command": "routing-switch providers list", "description": "Show every provider in the catalog with cache freshness", "expectedOutput": "VPN Provider Catalog ... vpngate ... riseup ... nordvpn", "notes": "Reads dashboard/hooks/config/vpn-providers-public-api.json (user-editable)" }, { "command": "routing-switch providers list --json", "description": "Same list in machine-readable JSON for the GUI / scripts", "expectedOutput": "{\"command\":\"providers-list\",\"data\":{\"schema_version\":\"1.1.0\",\"catalog_path\":\"...\",\"provider_count\":13,\"providers\":[{\"id\":\"vpngate\",\"tier\":\"tier_a\",...}]},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "sudo routing-switch providers fetch vpngate", "description": "Fetch the live profile list for a provider into the cache", "expectedOutput": "āœ“ Fetched N profiles for 'vpngate' (cached at ...)", "notes": "Hits the provider's public endpoint. Cache lives at /opt/kodachi/dashboard/hooks/cache/vpn-providers/<id>/" }, { "command": "sudo routing-switch providers fetch vpngate --force", "description": "Bypass the per-provider cache TTL and always re-fetch", "expectedOutput": "Refetches and overwrites the cache", "notes": "Use this when you specifically want fresh data (e.g. after edits to the catalog endpoints)." }, { "command": "routing-switch providers list-profiles vpngate", "description": "Browse cached profiles for a provider (table view)", "expectedOutput": "# Display name | Flag | CC | Remote | Protocol | Port | Load" }, { "command": "routing-switch providers list-profiles vpngate --country jp --limit 5", "description": "Filter to top 5 Japanese profiles", "expectedOutput": "5 profiles, all CC=JP", "notes": "Country code is 2-letter ISO, lowercase." }, { "command": "routing-switch providers list-profiles nordvpn --protocol wireguard --limit 20", "description": "Filter a provider's profiles by transport protocol", "expectedOutput": "20 profiles, all Protocol=wireguard", "notes": "--protocol (-p) is a substring match against the profile's transport: udp, tcp, openvpn, wireguard. Combine it with --country (-c) and --limit (-l)." }, { "command": "routing-switch providers list-profiles vpngate --json-pretty", "description": "JSON form (the GUI's primary surface)", "expectedOutput": "{\"command\":\"providers-list-profiles\",\"data\":{\"provider_id\":\"vpngate\",\"profile_count\":99,\"country_filter\":null,\"protocol_filter\":null,\"profiles\":[...]},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}" }, { "command": "sudo routing-switch providers get-profile vpngate 1_219-100-37-203 > /tmp/jp.ovpn", "description": "Dump a single profile's .ovpn content to stdout (or pipe to a file)", "expectedOutput": "(raw .ovpn body)", "notes": "Needs root: on a cache miss it lazily fetches the profile and writes it into the root-owned provider cache. profile_id format is provider-specific, see `providers list-profiles --json`. The body is the actual OpenVPN config text, so you can feed it to `routing-switch connect openvpn --config /tmp/jp.ovpn`." }, { "command": "routing-switch providers refresh-catalog", "description": "Re-read the catalog JSON after editing it on disk", "expectedOutput": "āœ“ Catalog reloaded ...", "notes": "Use this after manually editing vpn-providers-public-api.json (add custom providers, change endpoints) without restarting anything." }, { "command": "sudo routing-switch connect openvpn --config /tmp/jp.ovpn --force", "description": "Connect using a profile previously fetched via `providers get-profile`", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "The catalog provides the profile metadata; the connect command does the actual handshake. For paid-tier providers, use `providers credentials-set <id>` first, then `providers connect <id> <profile_id>` which auto-injects auth-user-pass." }, { "command": "sudo routing-switch providers credentials-set nordvpn --field username=foo --field password=bar", "description": "Save NordVPN service credentials (separate from the dashboard login)", "expectedOutput": "āœ“ Saved 2 credential field(s) for 'nordvpn'", "notes": "Stored at ~/.config/kodachi/vpn-credentials.json with mode 0600, values sealed with AES-256-GCM (machine-bound key). credentials-list shows which providers are configured." }, { "command": "routing-switch providers credentials-list", "description": "Show which providers have stored credentials (values are never printed)", "expectedOutput": "VPN Provider Credentials ... nordvpn ... yes (username,password)" }, { "command": "sudo routing-switch providers connect nordvpn pl150-nordvpn-com_udp", "description": "Connect via a provider profile, auto-injecting saved credentials into auth-user-pass", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Equivalent to: get-profile -> patch auth-user-pass -> connect openvpn --config <tempfile>. Re-execs in the same routing-switch process so all the connect prerequisites still run." }, { "command": "sudo routing-switch providers import-config --name 'My VPN' --file /tmp/my.ovpn", "description": "Phase 5: import your own .ovpn / .conf / JSON / YAML config as a custom profile", "expectedOutput": "āœ“ Imported custom profile ... Protocol: openvpn ... Connect with: routing-switch providers connect custom <id>", "notes": "Auto-detects OpenVPN / WireGuard / Shadowsocks / V2Ray / Hysteria2. Validation produces warnings, never blockers." }, { "command": "sudo routing-switch providers credentials-set custom/my-vpn-20260522 --field username=foo --field password=bar", "description": "Save the VPN account username/password for an imported OpenVPN profile (Proton VPN and most commercial providers)", "expectedOutput": "āœ“ Saved 2 credential field(s) for custom profile 'my-vpn-20260522'", "notes": "Needed when the imported .ovpn has a bare `auth-user-pass` line. `connect custom <id>` then builds the auth-user-pass file automatically. The dashboard's Import panel does this for you." }, { "command": "sudo routing-switch providers import-config --name 'WG Peer' --text \"$(cat ~/wg.conf)\" --protocol-hint wireguard", "description": "Import inline text with an explicit protocol hint (overrides auto-detect)", "expectedOutput": "āœ“ Imported custom profile ... Protocol: wireguard", "notes": "Needs root: the imported profile is written into the root-owned custom-provider cache. --file and --text are mutually exclusive." }, { "command": "routing-switch providers list-profiles custom", "description": "Browse the configs you've imported", "expectedOutput": "Provider: custom ... Profiles: N" }, { "command": "sudo routing-switch providers delete-custom-profile my-vpn-20260520143000", "description": "Remove a previously-imported custom profile", "expectedOutput": "āœ“ Deleted custom profile '...'", "notes": "Needs root (it removes files from the root-owned cache). Irreversible: the imported config body is gone, re-import it if you still need it." }, { "command": "sudo routing-switch providers delete-custom-profiles-bulk --id my-vpn-20260520143000 --id work-vpn-20260601090000 --json", "description": "Delete several imported custom profiles in one root invocation", "expectedOutput": "{\"command\":\"providers-delete-custom-profiles-bulk\",\"data\":{\"deleted\":[\"my-vpn-20260520143000\",\"work-vpn-20260601090000\"],\"failed\":[]},...}", "notes": "--id is repeatable. Any credentials stored under custom/<id> are wiped with the profile. Irreversible. --id and --all are mutually exclusive." }, { "command": "sudo routing-switch providers delete-custom-profiles-bulk --all --json", "description": "Delete EVERY imported custom profile", "expectedOutput": "{\"command\":\"providers-delete-custom-profiles-bulk\",\"data\":{\"deleted\":[\"my-vpn-...\",\"work-vpn-...\"],\"failed\":[]},...}", "notes": "DESTRUCTIVE and irreversible: wipes every config you ever imported, plus their stored credentials. There is no confirmation prompt. This is what the dashboard's 'Delete all' bulk action calls." }, { "command": "sudo routing-switch providers credentials-delete nordvpn", "description": "Delete the stored credentials for one provider", "expectedOutput": "āœ“ Deleted stored credentials for 'nordvpn'", "notes": "Only removes the credentials, the cached profiles stay (use `providers clear-cache <id>` for those). After this, `providers connect nordvpn <profile>` fails until you run credentials-set again. For an imported profile the id is the custom/<profile_id> form." }, { "command": "routing-switch providers validate-config --text \"vless://uuid@example.com:8443?type=tcp#NY\" --json", "description": "CV-3 dry-run: preview detected protocol + endpoint + warnings without writing to cache", "expectedOutput": "{\"command\":\"providers-validate-config\",\"data\":{\"detected_protocol\":\"v2ray\",\"remote_host\":\"example.com\",\"remote_port\":8443,\"transport\":\"tcp\",\"warnings\":[],\"hint_used\":false},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Validates URI schemes (vmess/vless/trojan/ss/hysteria2/tuic), Clash YAML, sing-box JSON, and plain OpenVPN/WireGuard bodies. Always warnings, never blockers." }, { "command": "sudo routing-switch providers resolve-country riseup vpn12-nyc_udp_1194", "description": "Look up the country for a cached profile via ip-fetch (skips if already tagged)", "expectedOutput": "āœ“ Resolved country for riseup/vpn12-nyc_udp_1194: us (United States)", "notes": "Pass --force to re-verify even if a country is already set (Verify mode)." }, { "command": "sudo routing-switch providers resolve-ip riseup vpn12-nyc_udp_1194", "description": "DNS-resolve the profile's hostname to an IPv4 and store in remote_ip", "expectedOutput": "āœ“ riseup/vpn12-nyc_udp_1194 resolved vpn12-nyc.riseup.net ā†’ 198.252.153.x", "notes": "Uses `getent hosts` for resolution so it honors /etc/hosts overrides." }, { "command": "sudo routing-switch providers resolve-ips riseup --concurrency 8", "description": "Bulk DNS-resolve every cached profile in a provider that's missing an IP", "expectedOutput": "āœ“ N resolved out of M (failed: K)", "notes": "Bounded parallelism via tokio::sync::Semaphore so we don't hammer the resolver." }, { "command": "sudo routing-switch providers connect-random vpngate --country jp --force", "description": "Pick a random profile (optionally filtered by country) and connect", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Useful for VPN Gate where load is largely uniform and randomness gives crowd-cover." }, { "command": "sudo routing-switch providers connect-fastest vpngate --country jp --force", "description": "Pick the fastest profile and connect (lowest measured latency if you've benchmarked; otherwise highest speed_bps)", "expectedOutput": "Successfully connected to OpenVPN server", "notes": "Prefers latency_ms from `providers benchmark`. Without a benchmark, falls back to provider-reported speed_bps then lowest load." }, { "command": "sudo routing-switch providers benchmark vpngate --country jp --top 20 --concurrency 8 --timeout 3 --json", "description": "User-triggered latency probe: pings each cached server (ICMP, falling back to TCP-connect) and stores latency_ms. Manual only, same UX as ip-fetch's cache refresh.", "expectedOutput": "{\"command\":\"providers-benchmark\",\"data\":{\"provider_id\":\"vpngate\",\"tested\":20,\"succeeded\":18,\"failed\":2,\"elapsed_ms\":5200,\"timeout_secs\":3,\"concurrency\":8,\"fastest\":{\"profile_id\":\"1_219-100-37-203\",\"latency_ms\":42}},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Never auto-runs. `connect-fastest` will prefer benchmarked profiles once latency is stored." }, { "command": "sudo routing-switch providers clear-cache riseup --json", "description": "Drop the on-disk cache for one provider (index + configs/). Credentials are NOT touched.", "expectedOutput": "{\"command\":\"providers-clear-cache\",\"data\":{\"provider_id\":\"riseup\",\"removed\":true},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Symmetric with `providers fetch`. Use --all to wipe every cached provider." }, { "command": "sudo routing-switch providers clear-cache --all --json", "description": "Bulk wipe: remove every cached provider's index + configs in one shot", "expectedOutput": "{\"command\":\"providers-clear-cache\",\"data\":{\"scope\":\"all\",\"providers_cleared\":9},\"errors\":[],\"metadata\":{...},\"status\":\"success\",\"timestamp\":\"...\",\"version\":\"<VERSION>\",\"warnings\":[]}", "notes": "Used by the dashboard \"Clear all\" bulk action. Idempotent." } ], "id": "external_vpn_providers", "title": "EXTERNAL VPN PROVIDERS" } ], "description": "System-wide traffic routing through various proxy protocols", "name": "routing-switch", "quickReference": [ "sudo routing-switch connect <PROTOCOL> - Connect (openvpn, wireguard, dante, tor, shadowsocks, v2ray, xray-vless, xray-vless-reality, xray-trojan, xray-vmess, mita, hysteria2)", "sudo routing-switch disconnect - Disconnect and restore normal routing", "sudo routing-switch status --detailed - Check connection status (sudo needed for accurate results)", "routing-switch list-protocols - Show available protocols with scores", "sudo routing-switch recover - Emergency: diagnose and restore routing when the network is stuck", "routing-switch providers <VERB> - External VPN providers, the largest surface here (20 verbs: list, fetch, list-profiles, get-profile, connect, connect-random, connect-fastest, benchmark, import-config, validate-config, credentials-set/list/delete, delete-custom-profile(s), resolve-country/ip/ips, refresh-catalog, clear-cache). Run `routing-switch providers --help`.", "connect tor is NOT standalone: a Kodachi tunnel must be up first, e.g. `sudo routing-switch connect wireguard && sudo routing-switch connect tor`", "Use --json / --json-pretty / --json-human for machine-readable output, --verbose for details", "AUTH (online-auth login) REQUIRED for: connect, auto-select, vpngate-connect, disconnect --clean-firewall, microsocks-enable/disable, showconfig/showconfigurl/showconfigqr, export-config, validate-qr, test-protocol, benchmark, and EVERY providers verb", "AUTH-FREE: status, dns-info, tor-dns-info, vps-info, check-prerequisites, list-protocols, plain disconnect, reset, cleanup, recover, microsocks-status, and VPNGate BROWSING (vpngate-fetch / vpngate-list / vpngate-export / vpngate-export-all). VPNGate servers are free, but `vpngate-connect` still needs authentication because it changes your routing." ] }, "errors": [], "metadata": { "executionTime": 2, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:43.668827232Z", "version": "9.8.4 (build 320)", "warnings": [] } } ] }