Binary reference

ai-cmd

AI-powered command-line interface for natural language command execution

Version10.0.1Size69.1MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ai-cmd
Version	10.0.1
Build Date	Not disclosed
Rust Version	1.82.0
File Size	69.1MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	AI-powered command-line interface for natural language command execution
Git Commit	unknown
Metadata Generated	2026-09-10T20:34:49Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

2ba08c2fb3bd23e701dc8f9afdbac36f0d2918c464a8f56a1aebe8c9ab7f8ba2

Features

#	Feature
1	Natural language to Kodachi command, with a confidence threshold you control
2	Multiple engine tiers: TF-IDF, ONNX, local GGUF LLM, Mistral.rs, GenAI, Claude
3	Every live execution is validated through the ai-gateway policy sandbox
4	Workflow profiles: multi-step operations matched from one sentence
5	Interactive REPL, voice input, and a feedback loop that trains the matcher

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)
`--offset <NUMBER>`	Skip first N results (for pagination)
`--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

Commands

`query`

Process a natural language query and execute the matching command

Usage:

ai-cmd query "<natural language query>"

Options:

--threshold: Confidence threshold for execution, from 0.0 to 1.0
--dry-run: Preview without execution
--auto-execute: Auto-execute an eligible read-only match bound to --expected-intent-id
--expected-intent-id: Stable intent ID from a fresh preview; required with --auto-execute
--alternatives: Number of ranked matches to return, from 1 to 10
--engine: AI engine tier: auto, tfidf, onnx, onnx-classifier, llm, mistral, genai, claude, codex, opencode
--model-path: Relative path to an existing Mistral GGUF model inside the execution directory; auto selects Mistral
--temperature: GenAI sampling temperature 0.0-2.0 (default: 0.7)
--model: Model name for GenAI tier (supports local, OpenAI/Codex, Claude, Gemini, OpenRouter routing)
--tor-proxy: Route cloud providers through Tor proxy
--use: Use a specific GGUF model file from models/ directory
--no-gateway, --skip-gateway: Bypass gateway validation (dry-run only; rejected for live execution)

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

printf '%s' "explain the current network posture" | ai-cmd query - --engine codex --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

`interactive`

Start interactive REPL mode for continuous queries

Usage:

ai-cmd interactive

Options:

--threshold: Confidence threshold for execution, from 0.0 to 1.0
--engine: AI engine tier: auto, tfidf, onnx, onnx-classifier, llm, mistral, genai, claude
--model-path: Relative path to an existing Mistral GGUF model inside the execution directory; auto selects Mistral

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

`feedback`

Submit feedback to improve intent classification

Usage:

ai-cmd feedback "<query>" [OPTIONS]

Options:

--correct-intent: Specify the correct intent ID
--correct-command: Specify the correct command
--comment: Add a comment

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"

`preview`

Preview intent classification without execution

Usage:

ai-cmd preview "<query>"

Options:

--alternatives: Number of ranked matches to show, from 1 to 10

Examples:

ai-cmd preview "check network"

ai-cmd preview "stop tor" --alternatives 5

ai-cmd preview "block internet" --json

`voice`

Voice input mode for natural language queries

Usage:

ai-cmd voice [OPTIONS]

Options:

--continuous: Enable continuous listening mode
--timeout: Timeout for voice input in seconds
--provider: STT provider: auto (detect best available), whisper-cpp, vosk, placeholder
--voice: TTS voice name
--speed: Speech speed (words per minute)
--list-devices: List available audio devices
--check-deps: Check voice engine dependencies

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

`suggest`

Get proactive command suggestions based on usage patterns

Usage:

ai-cmd suggest [OPTIONS]

Options:

--limit: Number of suggestions to show
--proactive: Show proactive suggestions

Examples:

ai-cmd suggest

ai-cmd suggest --limit 10

ai-cmd suggest --proactive

`workflow`

Execute workflow profiles via natural language queries

Usage:

ai-cmd workflow ["<natural language query>"] [--list] [--preview] [--dry-run] [--param KEY=VALUE] [--threshold <0.0-1.0>] [--category <CATEGORY>] [--stats]

Options:

--list, -l: List all available workflow profiles, grouped by category
--preview, -p: Show the matched profile, its steps and the services it touches, without executing anything
--dry-run: Walk the workflow and print the commands it would run, without running them
--param <KEY=VALUE>: Set a profile parameter. Repeat the flag for several parameters.
--threshold <THRESHOLD>: Minimum confidence (0.0 to 1.0) before a query is accepted as a profile match
--category, -c <CATEGORY>: Restrict to one category: privacy, emergency, network, security, system, setup, maintenance, recovery, custom
--stats: Show registry statistics: profile counts, categories, service usage

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

`tiers`

List all AI engine tiers and their availability status

Usage:

ai-cmd tiers [--json]

Examples:

ai-cmd tiers

ai-cmd tiers --json

`tools`

List all callable AI tools with parameter schemas

Usage:

ai-cmd tools [--json]

Examples:

ai-cmd tools

ai-cmd tools --json

`providers`

List available GenAI providers and model configuration

Usage:

ai-cmd providers [--json]

Examples:

ai-cmd providers

ai-cmd providers --json

`model-info`

Show loaded AI model details and configuration

Usage:

ai-cmd model-info [--json]

Examples:

ai-cmd model-info

ai-cmd model-info --json

`policy`

Show current AI policy (intent thresholds, tool allowlist, risk mode)

Usage:

ai-cmd policy [--json]

Examples:

ai-cmd policy

ai-cmd policy --json

`export-intents`

Export all intents as JSON catalog for shared libraries

Usage:

ai-cmd export-intents [--output FILE] [--json]

Options:

--output <FILE>: Write the intent catalog to a relative path inside the execution directory

Examples:

ai-cmd export-intents

ai-cmd export-intents --output intent-catalog.json

ai-cmd export-intents --json

Operational Scenarios

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

Scenario 1: Authentication: Read This First

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.

Step 1: Works without authentication: see which engine tiers are ready

ai-cmd tiers

Expected Output: The tier list with an availability marker against each engine

Step 2: Works without authentication: see what a sentence would match, and what else it nearly matched

ai-cmd preview "block internet" --alternatives 5

Expected Output: The winning intent with its confidence, plus 5 alternative matches

Note

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.

Step 3: Needs authentication, even though --dry-run runs nothing

ai-cmd query "check network connectivity" --dry-run

Expected Output: The matched command and its confidence, with nothing executed. On an unauthenticated shell: "Authentication required. Please authenticate using online-auth first".

Note

Authenticate with online-auth first. This is the most common reason an example here appears to be broken.

Scenario 2: Basic Usage

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.

Step 1: Match a sentence to a Kodachi command without running it

ai-cmd query "check network connectivity" --dry-run

Expected Output: The matched command, its confidence score, and the note that nothing ran

Step 2: Same preview as JSON, for a script or the dashboard

ai-cmd query "what is my ip address" --dry-run --json

Expected Output: JSON with the detected intent, the resolved command and the confidence

Step 3: Match and run: without --dry-run the matched command executes

ai-cmd query "check tor status"

Expected Output: The live output of the command ai-cmd matched, run through the gateway sandbox

Note

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.

Scenario 3: Advanced Query Control

Tighten or loosen the confidence gate, inspect alternatives, and hand execution over to the matcher. query is auth-gated.

Step 1: Demand a stronger match before the command is accepted

ai-cmd query "test dns leak" --threshold 0.8 --dry-run

Expected Output: The preview if confidence is at least 0.8, otherwise a refusal saying the match was too weak

Step 2: See the runners-up, to understand why a sentence matched badly

ai-cmd preview "block internet" --alternatives 5

Expected Output: The best intent plus 5 alternatives, each with a score

Note

preview never executes, and needs no authentication.

Step 3: Run the match through the recovery engine, with no confirmation step and automatic retries

ai-cmd query "check tor status" --auto-execute --threshold 0.9

Expected Output: 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'.

Note

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.

Step 4: Open the REPL and keep asking, without re-typing the flags

ai-cmd interactive --threshold 0.8

Expected Output: An interactive prompt that matches each line you type against the intent catalog

Note

Auth-gated. Exit with Ctrl-D.

Scenario 4: Feedback System

Correct a bad match so the matcher learns from it. Each of these writes a feedback record, and feedback is auth-gated.

Step 1: Tell ai-cmd which intent that sentence should have matched

ai-cmd feedback "check network" --correct-intent network_check

Expected Output: Confirmation that the intent correction was recorded

Step 2: Tell ai-cmd which command that sentence should have produced

ai-cmd feedback "test internet" --correct-command "health-control net-check"

Expected Output: Confirmation that the command correction was recorded

Step 3: Leave a free-text note when the right answer is not obvious

ai-cmd feedback "my ip" --comment "Should show IP address"

Expected Output: Confirmation that the comment was recorded

Note

Feedback feeds ai-learner and ai-trainer, so corrections show up in later matching, not in the current run.

Scenario 5: Voice Input

Speak a command instead of typing it. voice is auth-gated, and needs a working microphone plus an installed speech-to-text provider.

Step 1: Check whether voice can work on this machine at all

ai-cmd voice --check-deps

Expected Output: A dependency report for the speech-to-text and text-to-speech providers

Note

Start here. With no provider installed, ai-cmd falls back to a placeholder engine that recognizes nothing.

Step 2: List the audio input devices ai-cmd can see

ai-cmd voice --list-devices

Expected Output: The available audio capture devices

Step 3: Listen once, match what was said, and act on it

ai-cmd voice

Expected Output: The transcribed sentence and the command it matched

Note

A recognized command EXECUTES. Provider defaults to auto, which picks whisper-cpp, then vosk, then the placeholder.

Step 4: Pin a specific speech-to-text engine and wait longer for speech

ai-cmd voice --provider whisper-cpp --timeout 60

Expected Output: The transcription from whisper-cpp, with up to 60 seconds of listening

Note

--provider accepts auto, whisper-cpp, vosk or placeholder. --timeout is in seconds and defaults to 30.

Step 5: Keep listening and keep acting, until you stop it

ai-cmd voice --continuous

Expected Output: A listening loop that matches each utterance in turn

Note

Continuous mode executes each recognized command without asking. Do not leave it running unattended.

Scenario 6: AI Suggestions

Get command suggestions based on usage patterns

Step 1: Get recent command suggestions

ai-cmd suggest

Expected Output: List of suggested commands

Step 2: Get proactive suggestions

ai-cmd suggest --proactive

Expected Output: Popular or proactive suggestions

Step 3: Limit number of suggestions

ai-cmd suggest --limit 5

Expected Output: Top 5 suggestions

Scenario 7: Interactive Mode

Interactive REPL usage and configuration options

Step 1: Open the REPL and ask for things one line at a time

ai-cmd interactive

Expected Output: A prompt that matches each line you type, shows the command it resolved to, and asks before running anything risky

Note

Auth-gated: authenticate with online-auth first. Exit with Ctrl-D.

Step 2: Demand a stronger match for every line in the session

ai-cmd interactive --threshold 0.8

Expected Output: The same REPL, but lines that match below 0.8 confidence are refused

Step 3: Pin the session to the ONNX semantic matcher

ai-cmd interactive --engine onnx

Expected Output: A REPL that resolves every line through the ONNX tier

Step 4: Run the session against a specific local Mistral GGUF model

ai-cmd interactive --engine mistral --model-path ./models/phi.gguf

Expected Output: A REPL backed by the selected Mistral GGUF model

Note

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

Step 5: Use the cloud Claude tier for the session

ai-cmd interactive --engine claude --threshold 0.7

Expected Output: A REPL that resolves each line through the Claude tier

Note

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.

Scenario 8: AI Engine Tiers

--engine picks which matcher resolves your sentence. Valid values: auto (default), tfidf, onnx, onnx-classifier, llm, mistral, genai, claude, codex, opencode. The local tiers (tfidf, onnx, onnx-classifier) work offline; llm and mistral need a GGUF model on disk; genai, claude, codex and opencode are cloud tiers that send your query text off the machine. Run 'ai-cmd tiers' to see which are actually usable on this install.

Step 1: See which tiers are ready before you pin one

ai-cmd tiers

Expected Output: The tier list with an availability marker, and a setup hint against each tier that is not ready

Note

Needs no authentication.

Step 2: Let ai-cmd pick the best tier that is actually available

ai-cmd query "check tor" --engine auto --dry-run

Expected Output: The preview, plus the tier it settled on

Step 3: Force the offline keyword matcher: fastest, needs no model

ai-cmd query "check tor" --engine tfidf --dry-run

Expected Output: The preview, resolved by TF-IDF keyword scoring

Step 4: Force the offline semantic matcher (sentence embeddings)

ai-cmd query "check tor status" --engine onnx --dry-run

Expected Output: The preview, resolved by embedding similarity

Note

Needs the embedding model downloaded. If it is missing, 'ai-cmd tiers' marks onnx unavailable and the query falls back.

Step 5: Force the ONNX intent classifier instead of the embedding matcher

ai-cmd query "check tor status" --engine onnx-classifier --dry-run

Expected Output: The preview, resolved by direct intent classification

Note

onnx and onnx-classifier are different tiers: one compares embeddings, the other classifies the sentence directly. Both need their model downloaded.

Step 6: Use a local GenAI provider with less creative sampling

ai-cmd query "is my system secure?" --engine genai --model llama3:8b --temperature 0.3 --dry-run

Expected Output: The preview, resolved through the GenAI provider

Note

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

Step 7: Point the local Mistral tier at a specific GGUF file

ai-cmd query "check tor" --engine mistral --model-path ./models/phi.gguf --dry-run

Expected Output: The preview, resolved by the Mistral model at that path

Note

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.

Step 8: Use the GenAI tier against a local Ollama model

ai-cmd query "security audit" --engine genai --model llama3:8b --dry-run

Expected Output: The preview, resolved through the GenAI provider routing

Note

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

Step 9: Send a cloud query through Tor rather than direct

ai-cmd query "detailed analysis" --engine genai --model gpt-4o-mini --tor-proxy --dry-run

Expected Output: The preview, with the provider call routed over the Tor SOCKS proxy

Note

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.

Step 10: Use the Claude cloud tier

ai-cmd query "check tor status" --engine claude --dry-run

Expected Output: The preview, resolved by the Claude tier

Note

Needs an API key and network access, and sends the query text off the machine.

Scenario 9: Tool Calling

Tool-calling queries and tool catalog inspection

Step 1: Tool-calling query in safe dry-run mode

ai-cmd query "what's my tor status and dns config?" --dry-run

Expected Output: Dry-run preview for multi-tool query

Step 2: List all callable tools with JSON metadata

ai-cmd tools --json

Expected Output: JSON tool definitions

Step 3: Show tools grouped by domain

ai-cmd tools

Expected Output: Human-readable tool catalog

Step 4: Print the whole intent catalog to stdout

ai-cmd export-intents

Expected Output: The full intent catalog as JSON on stdout, ready to pipe elsewhere

Note

Add --output <FILE> to write it to a file instead, or --json for an envelope summary rather than the raw catalog. Needs no authentication.

Scenario 10: Security-First Routing

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.

Step 1: A crisp request: resolves on the local fast path

ai-cmd query "check tor status" --dry-run

Expected Output: The matched command with a high confidence score, resolved without any model call

Step 2: An open question: needs a generative tier, not a matcher

ai-cmd query "explain tor routing in detail" --engine mistral --dry-run

Expected Output: A generated explanation from the local model rather than a single matched command

Note

The generative tiers are slower and need a model on disk. Check with 'ai-cmd tiers' before relying on this in a script.

Step 3: A configuration change: always preview before you commit

ai-cmd query "change dns to cloudflare" --dry-run

Expected Output: The dns-switch command that would run, with nothing applied

Note

Dropping --dry-run really does change your resolver. A DNS change can deanonymize you if it points at a provider you did not intend.

Scenario 11: AI Policy

View and manage AI policy configuration including intent thresholds, tool allowlists, and risk mode.

Step 1: Show current AI policy (thresholds, tools, risk mode)

ai-cmd policy

Expected Output: Policy details with intent thresholds and tool list

Step 2: AI policy as JSON for programmatic use

ai-cmd policy --json

Expected Output: JSON with version, thresholds, allowlist, signature status

Scenario 12: Linux System Commands

General-purpose Linux system commands via natural language

Step 1: Disk usage request preview

ai-cmd query "how much disk space" --dry-run

Expected Output: Dry-run preview for disk space command

Step 2: Process listing request preview

ai-cmd query "list running processes" --dry-run

Expected Output: Dry-run preview for process listing command

Step 3: Network port check request preview

ai-cmd query "check if port 80 is open" --dry-run

Expected Output: Dry-run preview for port inspection command

Step 4: Safe preview of package update flow

ai-cmd query "update system packages" --dry-run

Expected Output: Dry-run preview of package update

Note

Remove --dry-run to execute after authentication

Step 5: Network diagnostic request preview

ai-cmd query "ping example.com" --dry-run

Expected Output: Dry-run preview for ping diagnostic

Step 6: Log viewing with explicit TF-IDF engine

ai-cmd query "show system logs" --engine tfidf --dry-run

Expected Output: Dry-run preview using tfidf tier

Step 7: Service management query with strict confidence threshold

ai-cmd query "restart nginx service" --threshold 0.9 --dry-run

Expected Output: Dry-run preview gated by 0.9 threshold

Step 8: Firewall inspection query preview

ai-cmd query "check firewall rules" --dry-run

Expected Output: Dry-run preview for firewall status command

Scenario 13: Confidence Threshold Reference

The --threshold flag controls minimum confidence required for a match. Range: 0.3 to 1.0. Default: 0.6.

Step 1: Minimum threshold for broad matching

ai-cmd query "check tor" --threshold 0.3 --dry-run

Expected Output: Dry-run preview with loose confidence gating

Step 2: Default threshold balance

ai-cmd query "check tor" --threshold 0.6 --dry-run

Expected Output: Dry-run preview with default confidence gating

Step 3: Higher threshold for sensitive operations

ai-cmd query "block internet" --threshold 0.8 --dry-run

Expected Output: Dry-run preview with strict confidence gating

Step 4: Very strict threshold for near-exact matching

ai-cmd query "check tor" --threshold 0.95 --dry-run

Expected Output: Dry-run preview requiring near-exact match

Scenario 14: Workflow Profiles

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.

Step 1: List all available workflow profiles

ai-cmd workflow --list

Expected Output: Profiles grouped by category (privacy, emergency, network, etc.)

Step 2: List only the profiles in one category

ai-cmd workflow --list --category emergency

Expected Output: The emergency profiles and what each one does

Note

--category (-c) accepts exactly: privacy, emergency, network, security, system, setup, maintenance, recovery, custom. Any other value is rejected.

Step 3: Preview privacy workflow profile

ai-cmd workflow "maximum privacy setup" --preview

Expected Output: Workflow details, steps, and services used

Note

Use without --preview to execute after review

Step 4: Preview emergency recovery workflow

ai-cmd workflow "emergency recovery" --preview

Expected Output: Workflow details, steps, and services used

Step 5: Dry-run workflow execution

ai-cmd workflow "setup network" --dry-run

Expected Output: Shows what would be executed without running commands

Step 6: Preview with custom confidence threshold

ai-cmd workflow "tor setup" --threshold 0.7 --preview

Expected Output: Workflow preview if confidence >= 0.7

Step 7: Show workflow registry statistics

ai-cmd workflow --stats

Expected Output: Profile counts, categories, and service usage

Step 8: Preview workflow with custom parameters

ai-cmd workflow "complete anonymity" --param country=us --preview

Expected Output: Workflow with custom parameter values

Note

Pass key=value pairs for profile parameters

Scenario 15: Models, Tiers and Providers

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.

Step 1: List the engine tiers and whether each one is usable

ai-cmd tiers

Expected Output: Each tier with an available or unavailable marker, and a setup hint for the ones that are not ready

Step 2: Same readiness check, as JSON for a health probe

ai-cmd tiers --json

Expected Output: JSON with each tier, its availability and its setup hint

Step 3: Show which models are on disk and which tier each one serves

ai-cmd model-info

Expected Output: The model inventory: paths and availability for the embedding and LLM backends

Note

Run this before a query that pins --engine llm or --engine mistral, so you know the model is really there.

Step 4: Run one query against a specific GGUF file from the models folder

ai-cmd query "check tor" --use Qwen3-1.7B-Q4_K_M.gguf --dry-run

Expected Output: The preview, resolved by that model

Note

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

Step 5: List the provider backends and whether they are configured

ai-cmd providers

Expected Output: Each provider with its status

Step 6: Provider status as JSON, for an automated check

ai-cmd providers --json

Expected Output: JSON with each provider and the fields a health check needs

Scenario 16: Gateway Core Integration

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

Step 1: The normal path: the query is validated through the shared gateway core

ai-cmd query "check tor status" --dry-run --json

Expected Output: The preview together with the policy decision the gateway reached

Step 2: Preview WITHOUT the gateway validation step, to see the raw match

ai-cmd query "check tor status" --no-gateway --dry-run

Expected Output: The matched command with no gateway policy decision attached, and nothing executed

Note

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

Step 3: The same preview-only bypass, spelled with the alias flag

ai-cmd query "test dns leak" --skip-gateway --dry-run

Expected Output: The raw match for a slow command, with nothing executed

Note

--skip-gateway is an alias of --no-gateway and carries the same dry-run-only restriction.

Step 4: Read the policy guard that gates every live execution

ai-cmd policy --json

Expected Output: JSON with the policy version, the intent thresholds, the tool allowlist and the signature status

Note

This is the command to run when an execution was denied and you want to know why. Needs no authentication.

Step 5: Export the whole intent catalog for another tool to consume

ai-cmd export-intents --output intent-catalog.json

Expected Output: The catalog written to intent-catalog.json, with the total intent count

Note

The output path is relative to the current directory. Absolute paths and '..' are rejected. Omit --output to print to stdout.

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
2	Invalid arguments
5	File not found
1	General error
0	Success
3	Permission denied
4	Network error