{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:38Z", "binary_name": "online-auth" }, "binary": { "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 ", "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 ", "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 " }, { "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-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 , 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 " }, { "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": [] } } }