{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:12Z", "binary_name": "ai-admin" }, "binary": { "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" } } } }