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