Binary reference

ai-admin

AI system administration and maintenance

Version10.0.3Size8.0MBAuthorWarith Al Maawali <warith@digi77.com>LicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ai-admin
Version	10.0.3
Build Date	Not disclosed
Rust Version	1.82.0
File Size	8.0MB
Author	Warith Al Maawali <warith@digi77.com>
License	Proprietary
Category	Kodachi Binary
Description	AI system administration and maintenance
Git Commit	unknown
Metadata Generated	2026-11-13T16:19:36Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

5a23f2cbbf1a9368572414c0467e6f3b7779dff1314b67b8528732a73a6f4fb7

Features

#	Feature
1	SQLite database backup, restore, and integrity checking
2	Schema migration to the current database version
3	Diagnostics report: database, performance, disk usage, integrity
4	Performance tuning: VACUUM/ANALYZE, index rebuild, old-record cleanup
5	JSON output on every command for dashboard and automation use

Security Features

Feature	Description
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core
Authentication	Not provided by cli-core (see online-auth)
Encryption	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

`db`

Database management operations

Usage:

ai-admin db <backup|restore|integrity-check|migrate|info> [OPTIONS]

Options:

backup --output <FILE>: Copy the database to FILE, confined to the execution folder
restore --backup, -b <FILE>: Overwrite the live database with FILE (destructive; the current file is copied to <db path>.pre-restore first)
integrity-check: Run SQLite PRAGMA integrity_check, exits non-zero on failure
migrate: Apply any pending schema migrations
info: Show path, size, schema version, integrity and fragmentation

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

`diagnostics`

Run system diagnostics

Usage:

ai-admin diagnostics [--full] [--json]

Options:

--full: Add the SQLite integrity check to the report (slower, exits non-zero when integrity fails)

Examples:

ai-admin diagnostics

ai-admin diagnostics --json

ai-admin diagnostics --full

ai-admin diagnostics --full --json-human

`tune`

Performance tuning and optimization

Usage:

ai-admin tune <optimize|rebuild-index|cleanup> [OPTIONS]

Options:

optimize: Run SQLite VACUUM and ANALYZE to reclaim space and refresh stats
rebuild-index: Rebuild the database indexes
cleanup --days <DAYS>: Delete records older than DAYS (destructive and irreversible)

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

Operational Scenarios

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

Scenario 1: Quick Start

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).

Step 1: See whether the AI database is healthy right now

ai-admin diagnostics

Expected Output: Text report with Database (status, size, fragmentation), Performance (connection and query time), and Disk Usage (database, temp, total)

Step 2: Show the database path, size, schema version and integrity

ai-admin db info

Expected Output: Path, Size in MB, schema Version, Integrity OK or FAILED, Fragmentation %

Note

Requires a login (the dashboard's login, or sudo online-auth authenticate), or the command exits with 'Authentication failed'.

Step 3: Take a copy of the AI database before doing anything risky

ai-admin db backup --output ai-db-backup.db

Expected Output: Backup created, with the resolved path, size in MB and a SHA-256 checksum

Note

--output is required and is confined to the ai-admin execution folder.

Step 4: Reclaim space and refresh query planner statistics

ai-admin tune optimize

Expected Output: Optimization result with the space reclaimed

Scenario 2: Database Inspection and Migration

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.

Step 1: Show database path, size, schema version and integrity

ai-admin db info

Expected Output: Path, Size in MB, schema Version, Integrity OK or FAILED, Fragmentation %

Step 2: Same information as machine-readable JSON

ai-admin db info --json

Expected Output: JSON with exists, path, size_bytes, size_mb, version, integrity_ok, fragmentation_percent

Note

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.

Step 3: Run SQLite PRAGMA integrity_check on the AI database

ai-admin db integrity-check

Expected Output: Status OK plus size, page count and fragmentation, or a FAILED status listing each corruption issue found

Note

Exits non-zero when integrity fails, so it can gate a script.

Step 4: Apply any pending schema migrations

ai-admin db migrate

Expected Output: Previous version, Current version, and the number of migrations applied

Note

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.

Scenario 3: Backup and Restore

Copy the AI database out before a risky change, and put it back after. Backup paths are confined to the ai-admin execution folder.

Step 1: Create a verified copy of the AI database

ai-admin db backup --output ai-db-backup.db

Expected Output: Backup created, with the resolved path, size in MB and a SHA-256 checksum

Note

--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.

Step 2: Back up into a subfolder and capture the result for a script

ai-admin db backup --output backups/ai-db-2026-07.db --json

Expected Output: JSON with backup_path, size_bytes, size_mb, created_at, checksum

Note

The subfolder is created if missing, still inside the execution folder.

Step 3: Replace the live AI database with a backup

ai-admin db restore --backup ai-db-backup.db

Expected Output: Restored, showing the source backup and the target database

Note

DESTRUCTIVE: this overwrites the live database. The current file is first copied to <db path>.pre-restore, and the backup is rejected if it fails its integrity or schema check.

Step 4: Restore using the short flag, with indented JSON output

ai-admin db restore -b ai-db-backup.db --json-pretty

Expected Output: Indented JSON with status 'restored', backup_path and database_path

Note

DESTRUCTIVE: overwrites the live database. -b is the short form of --backup.

Scenario 4: System Diagnostics

One report covering four sections: database, performance, disk usage, and (with --full) integrity. diagnostics is the only command here that does not require authentication.

Step 1: Run the standard three-section health report

ai-admin diagnostics

Expected Output: Database (status, size, fragmentation), Performance (connection and query time), Disk Usage (database, temp files, total)

Step 2: Add the SQLite integrity check to the report

ai-admin diagnostics --full

Expected Output: The three standard sections plus an Integrity Check section, PASSED or FAILED with the issues listed

Note

Exits non-zero if the integrity check fails. Slower than the plain run because it reads every database page.

Step 3: Machine-readable report for the dashboard or a monitor

ai-admin diagnostics --json

Expected Output: JSON with database, performance and disk_usage objects (integrity is omitted unless --full is passed)

Step 4: Full report as readable, formatted JSON

ai-admin diagnostics --full --json-human

Expected Output: Formatted JSON with database, performance, disk_usage and integrity {passed, issues}

Scenario 5: Performance Tuning

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.

Step 1: Reclaim free pages and refresh query planner statistics

ai-admin tune optimize

Expected Output: Optimization result with the space reclaimed

Note

Runs SQLite VACUUM and ANALYZE. VACUUM rewrites the whole file, so it needs free disk roughly equal to the current database size.

Step 2: Rebuild the database indexes after heavy churn

ai-admin tune rebuild-index

Expected Output: Confirmation that the indexes were rebuilt

Step 3: Remove records older than the default retention window

ai-admin tune cleanup

Expected Output: Cleanup result with the number of records removed

Note

DESTRUCTIVE: deleted records are gone. --days defaults to 30. Back up first with 'ai-admin db backup' if the history matters.

Step 4: Aggressive cleanup, keeping only the last week, output as JSON

ai-admin tune cleanup --days 7 --json

Expected Output: JSON with the cleanup statistics and records removed

Note

DESTRUCTIVE and irreversible. A short window discards recent AI feedback and learning history.

Step 5: Optimize and capture the result in a maintenance script

ai-admin tune optimize --json

Expected Output: JSON with the optimization statistics

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
78	This CPU has no AVX2 support, which the Kodachi AI tools need