Binary reference
online-auth
Secure online authentication client for Kodachi OS
File Information
| Property | Value |
|---|---|
| Binary Name | online-auth |
| Version | 10.0.3 |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 9.2MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Kodachi Binary |
| Description | Secure online authentication client for Kodachi OS |
| Git Commit | unknown |
| Metadata Generated | 2026-11-13T16:20:38Z |
| Binary Timestamp | Unknown |
| JSON Data | View Raw JSON |
SHA256 Checksum
8988573a8e73c64cf3b5b7daef98e400d8f978bcd2945f4b9bda2ccf0c82dd93
Features
| # | Feature |
|---|---|
| 1 | Authentication over HTTPS, validated against the system CA bundle |
| 2 | Session management with automatic heartbeat |
| 3 | API key synchronization |
| 4 | User group and status checking |
| 5 | Comprehensive logging and error handling |
| 6 | Multi-language architecture integration |
| 7 | Encrypted HTTPS communications |
| 8 | Real-time status monitoring |
| 9 | Automatic retry mechanisms |
Security Features
| Feature | Description |
|---|---|
| Authentication | Not provided by cli-core (see online-auth) |
| Encryption | Not provided by cli-core |
| Input Validation | Argument parsing via clap; per-command validation is the consumer's responsibility |
| Rate Limiting | Not provided by cli-core |
System Requirements
| Requirement | Value |
|---|---|
| OS | Linux (Debian-based) |
| Privileges | root/sudo for system operations |
| Dependencies | OpenSSL, libcurl |
Global Options
| Flag | Description |
|---|---|
-h, --help |
Print help information |
-v, --version |
Print version information |
-n, --info |
Display detailed information |
-e, --examples |
Show usage examples |
--json |
Output in JSON format |
-o, --output-format <FORMAT> |
Force output format (text|json) |
--json-pretty |
Pretty-print JSON output with indentation |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--json-filter <FIELD1,FIELD2> |
Return only specified JSON fields (comma-separated) |
--fields <FIELD_LIST> |
Select specific fields to include in output (comma-separated) |
--limit <NUMBER> |
Limit number of results returned |
--offset <NUMBER> |
Skip first N results (for pagination) |
-d, --work-dir <PATH> |
Working directory (defaults to auto-detected base directory) |
--port <PORT> |
Set custom port number (1024-65535) |
--log-level <LEVEL> |
Set log level (error|warn|info|debug) |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--config <FILE> |
Use custom configuration file |
--timeout <SECS> |
Set operation timeout in seconds (optional; no default applied) |
Commands
API Management
sync-api-key
Manually sync API key with server
Usage:
online-auth sync-api-key [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth sync-api-key
sudo online-auth sync-api-key --json
Authentication
authenticate
Authenticate with the server
Usage:
online-auth authenticate [OPTIONS]
Options:
--keep-alive, -k: Keep the session alive with automatic heartbeats--relogin: Re-authenticate automatically when the session expires (implies --keep-alive)--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
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
check-login
Check if currently logged in
Usage:
online-auth check-login [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth check-login
online-auth check-login --json
logout
End the current session
Usage:
online-auth logout [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth logout
sudo online-auth logout --json
check-if-blocked
Check if user ID is blocked
Usage:
online-auth check-if-blocked [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth check-if-blocked
online-auth check-if-blocked --json
get-ids
Show user and session IDs
Usage:
online-auth get-ids [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth get-ids
online-auth get-ids --json
check-all-status
Show all status information at once
Usage:
online-auth check-all-status [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth check-all-status
online-auth check-all-status --json
Heartbeat
send-heartbeat
Send a single heartbeat
Usage:
online-auth send-heartbeat [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth send-heartbeat
sudo online-auth send-heartbeat --json
send-heartbeat-with-retry
Send heartbeat with retry
Usage:
online-auth send-heartbeat-with-retry [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth send-heartbeat-with-retry
sudo online-auth send-heartbeat-with-retry --json
start-heartbeat
Start automatic heartbeat service
Usage:
online-auth start-heartbeat [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth start-heartbeat
sudo online-auth start-heartbeat --json
stop-heartbeat
Stop automatic heartbeat service
Usage:
online-auth stop-heartbeat [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth stop-heartbeat
sudo online-auth stop-heartbeat --json
check-heartbeat
Check if heartbeat service is running
Usage:
online-auth check-heartbeat [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth check-heartbeat
online-auth check-heartbeat --json
Information
get-card
Get user card URL
Usage:
online-auth get-card [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth get-card
online-auth get-card --json
which-group
Check which account group you belong to (Free, Premium, or Custom)
Usage:
online-auth which-group [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
online-auth which-group
online-auth which-group --json
License
activate-license
Activate a license key for premium features
Usage:
online-auth activate-license [OPTIONS]
Options:
--stdin-key: Read one license key from stdin without exposing it in argv--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
printf '%s\n' '<LICENSE_KEY>' | sudo online-auth activate-license --stdin-key
printf '%s\n' '<LICENSE_KEY>' | sudo online-auth activate-license --stdin-key --json
release-license
Release license to allow transfer to another device
Usage:
online-auth release-license [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth release-license
sudo online-auth release-license --json
license-status
Check current license status and details
Usage:
online-auth license-status [OPTIONS]
Options:
--reveal-key: Reveal the complete license key in this command output (sensitive)--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth license-status
sudo online-auth license-status --json
sudo online-auth license-status --reveal-key --json
dismiss-message
Dismiss an admin popup message for this device (records dismissal server-side)
Usage:
online-auth dismiss-message [OPTIONS]
Options:
--message-id, -m <MESSAGE_ID>: UUID of the admin message to dismiss (read it from license-status admin_messages[].id)--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
ADMIN_MESSAGE_ID=$(sudo online-auth license-status --json | jq -r '.admin_messages[0].id') && sudo online-auth dismiss-message --message-id "$ADMIN_MESSAGE_ID"
ADMIN_MESSAGE_ID=$(sudo online-auth license-status --json | jq -r '.admin_messages[0].id') && sudo online-auth dismiss-message -m "$ADMIN_MESSAGE_ID" --json
Permission Guard
enable-permission-guard
Enable permission guard daemon to monitor and fix file permissions
Usage:
online-auth enable-permission-guard [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth enable-permission-guard
sudo online-auth enable-permission-guard --json
disable-permission-guard
Disable permission guard daemon
Usage:
online-auth disable-permission-guard [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth disable-permission-guard
sudo online-auth disable-permission-guard --json
permission-guard-status
Check permission guard daemon status
Usage:
online-auth permission-guard-status [OPTIONS]
Options:
--json: Print the result envelope as compact JSON--json-pretty: Print the result envelope as indented JSON--json-human: Print colorized, jq-style JSON (implies --json)
Examples:
sudo online-auth permission-guard-status
sudo online-auth permission-guard-status --json
Operational Scenarios
Scenario-oriented workflows generated from the binary's built-in -e --json examples.
Scenario 1: Authentication Management
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.
Step 1: Log in to Kodachi Cloud and create a session
sudo online-auth authenticate
Note
Needs network access. Without sudo the hardware ID is computed from non-root sources and will not match the registered device.
Step 2: Log in and capture the result for a script
sudo online-auth authenticate --json
Step 3: Authenticate and enable auto-heartbeat
sudo online-auth authenticate --keep-alive
Step 4: Authenticate with auto-relogin on disconnection
sudo online-auth authenticate --relogin
Note
Automatically enables heartbeat (--keep-alive) and re-authenticates when session expires
Step 5: Authenticate with explicit heartbeat and auto-relogin
sudo online-auth authenticate --keep-alive --relogin
Note
Both flags can be used together for clarity
Step 6: Check whether a valid session exists right now
online-auth check-login
Note
Exits non-zero when there is no session, which is what makes the 'check-login || authenticate' idiom work.
Step 7: End the current session and clear the local session state
sudo online-auth logout
Note
Also stops an active keep-alive heartbeat.
Step 8: Ask the server whether this device or user is blocked
online-auth check-if-blocked
Step 9: One-shot summary: login state, group, heartbeat and block status
online-auth check-all-status
Note
This is the call the dashboard makes to paint the auth indicator.
Scenario 2: User Information
Identity and account information
Step 1: Show user and session IDs
online-auth get-ids
Step 2: Get IDs in JSON format
online-auth get-ids --json
Step 3: Check account group (Free, Premium, or Custom)
online-auth which-group
Step 4: Get user card URL
online-auth get-card
Scenario 3: Heartbeat Management
Session keepalive and heartbeat operations
Step 1: Send a single heartbeat
sudo online-auth send-heartbeat
Step 2: Send heartbeat with retry logic
sudo online-auth send-heartbeat-with-retry
Step 3: Start automatic heartbeat service
sudo online-auth start-heartbeat
Step 4: Stop automatic heartbeat service
sudo online-auth stop-heartbeat
Step 5: Check if heartbeat service is running
online-auth check-heartbeat
Scenario 4: Permission Guard Management
Control permission guard daemon for file permission monitoring
Step 1: Start permission guard daemon to monitor file permissions
sudo online-auth enable-permission-guard
Note
Ensures files maintain correct ownership and prevents root-owned files in user directories
Step 2: Stop permission guard daemon
sudo online-auth disable-permission-guard
Note
Stops automatic permission monitoring and correction
Step 3: Check if permission guard daemon is running
sudo online-auth permission-guard-status
Step 4: Enable permission guard with JSON output
sudo online-auth enable-permission-guard --json
Note
Useful for automation scripts and monitoring
Step 5: Get permission guard status in JSON format
sudo online-auth permission-guard-status --json
Scenario 5: API Management
API key synchronization and management
Step 1: Manually sync API key with server
sudo online-auth sync-api-key
Step 2: Sync API key with JSON output
sudo online-auth sync-api-key --json
Scenario 6: Program Information
Version and program details
Step 1: Show version number
online-auth --version
Step 2: Show detailed program information
online-auth --info
Step 3: Show help information
online-auth --help
Step 4: Show usage examples
online-auth --examples
Scenario 7: Workflow Combinations
Complete authentication workflows
Step 1: Authenticate and check group
sudo online-auth authenticate && online-auth which-group
Note
Useful for setup scripts
Step 2: Auth with heartbeat and get card
sudo online-auth authenticate --keep-alive && online-auth get-card
Step 3: Check login or authenticate if needed
online-auth check-login || sudo online-auth authenticate
Note
Ensures authenticated state
Scenario 8: Troubleshooting
Debug and error resolution
Step 1: Check connection status
online-auth check-login --json
Step 2: Refresh API credentials
sudo online-auth sync-api-key
Note
Use when authentication fails
Step 3: Reset authentication
sudo online-auth logout && sudo online-auth authenticate
Step 4: Restart heartbeat service
sudo online-auth stop-heartbeat && sudo online-auth start-heartbeat
Scenario 9: Advanced Options
Session behavior 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.
Step 1: Log in the way the dashboard does: keep-alive plus automatic re-login when the session expires
sudo online-auth authenticate --relogin --json
Note
--relogin implies --keep-alive, so passing both is redundant but harmless.
Step 2: Send one heartbeat with the built-in retry policy instead of failing on the first network hiccup
sudo online-auth send-heartbeat-with-retry --json
Note
The retry policy is internal to this command; there is no global --retry option.
Scenario 10: JSON Output
Working with JSON formatted responses
Step 1: Extract status from JSON
sudo online-auth authenticate --json | jq '.status'
Step 2: Extract the anonymous secure hash ID from JSON (sensitive value)
online-auth get-ids --json | jq '.data.anon_secure_hash_id'
Step 3: Get all status data as JSON
online-auth check-all-status --json | jq '.data'
Note
Useful for monitoring scripts
Step 4: Read the license envelope indented, without piping it through jq
sudo online-auth license-status --json-pretty
Step 5: Colorized, jq-style JSON for reading at a terminal
sudo online-auth permission-guard-status --json-human
Note
--json-human implies JSON mode. Use --json, not --json-human, when piping to a parser.
Scenario 11: License Management
License activation, status, and transfer operations
Step 1: Activate a license key for premium features
printf '%s\n' '<LICENSE_KEY>' | sudo online-auth activate-license --stdin-key
Note
Key format: XXXX-XXXX-XXXX-XXXX-XXXX (24 chars with dashes)
Step 2: Activate license with JSON output
printf '%s\n' '<LICENSE_KEY>' | sudo online-auth activate-license --stdin-key --json
Step 3: Check current license status and details
sudo online-auth license-status
Step 4: Get license status in JSON format
sudo online-auth license-status --json
Note
Useful for scripting and automation
Step 5: Reveal the complete license key for an explicit local display
sudo online-auth license-status --reveal-key --json
Note
Do not log, pipe, or retain this output
Step 6: Release license to transfer to another device
sudo online-auth release-license
Note
Use when moving to new hardware or reinstalling
Step 7: Release license with JSON confirmation
sudo online-auth release-license --json
Step 8: Read the ID of the admin message currently shown on this device
sudo online-auth license-status --json | jq -r '.admin_messages[0].id'
Note
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.
Step 9: Dismiss an admin popup message so the server stops sending it to this device
sudo online-auth dismiss-message --message-id "3f2a91c4-77b8-4d0e-9a11-6c5f0d2e8b31"
Note
--message-id (-m) is required and must be the UUID from license-status admin_messages[].id. The dismissal is per device, not per user.
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
NO_COLOR |
Disable all colored output when set | unset | 1|true|yes (any value disables color) |
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error (with --json, the error's code field names its kind) |
| 2 | Invalid arguments |
| 7 | Authentication required or failed |