ai-cmd

ai-cmd is a focused CLI for turning natural-language terminal questions into a single shell command you can inspect, copy, explain, and optionally run with confirmation.

It is designed for the fast path:

ai "how do I restart nginx"

Instead of a chatty assistant or a full autonomous agent, ai-cmd aims to be the small utility you keep installed because it is quick, predictable, and useful.

Why it exists

Developers regularly know what they want to do in the terminal, but not the exact command for the current machine, shell, or init system.

ai-cmd narrows that gap by:

• generating one best command instead of a long essay
• adapting to Linux, macOS, WSL, and generic Unix-like environments
• explaining what the command does
• classifying command risk before execution
• keeping interactive follow-ups lightweight

Powered by Ottili ONE

This project is part of the Ottili ONE ecosystem — a modular AI system for automating development, business workflows, and operations.

Website: https://ottili.one

Features

• One-shot command generation: ai "<question>"
• Interactive REPL mode: ai
• Session-aware follow-up questions in REPL mode
• Command explanations and platform notes
• Clipboard copy support
• Optional execution with confirmation
• Heuristic risk classification for destructive commands
• First-run configurator for provider, API key, and analytics consent
• Configurable provider abstraction for OpenAI, Anthropic, Google, Ollama, and vLLM
• Workspace-aware command generation based on the current folder
• Opt-in anonymous analytics with separate error reporting
• JSON mode for scripting

Installation

Global install from npm

npm install -g ai-cmd

Local development install

npm install
npm run build
npm link

Configuration

ai-cmd reads configuration from environment variables and optionally from ~/.ai-cmd/config.json.

Environment variables take precedence over the config file.

If required configuration is missing and you launch ai-cmd interactively, a first-run configurator opens and asks for:

• AI provider
• API key
• analytics consent

If you opt in, config.json stores "analytics": true and a random anonymous install id. If you opt out, it stores "analytics": false.

OpenAI

OpenAI remains the default provider:

export AI_API_KEY="your-api-key"
export AI_PROVIDER="openai"
export AI_MODEL="gpt-5.4-mini"
export AI_BASE_URL="https://api.openai.com/v1"
export AI_TIMEOUT_MS="30000"

Anthropic

export AI_PROVIDER="anthropic"
export AI_API_KEY="your-anthropic-key"
export AI_MODEL="claude-sonnet-4-20250514"
export AI_BASE_URL="https://api.anthropic.com/v1"

Google

export AI_PROVIDER="google"
export AI_API_KEY="your-google-ai-key"
export AI_MODEL="gemini-2.5-flash"
export AI_BASE_URL="https://generativelanguage.googleapis.com/v1beta"

Ollama

Use a local Ollama model such as Gemma:

export AI_PROVIDER="ollama"
export AI_MODEL="gemma3:4b"
export AI_BASE_URL="http://localhost:11434/api"

No API key is required for the default local Ollama setup.

vLLM

Use a local or self-hosted OpenAI-compatible vLLM server:

export AI_PROVIDER="vllm"
export AI_MODEL="google/gemma-3-4b-it"
export AI_BASE_URL="http://localhost:8000/v1"

No API key is required for a local vLLM server unless you configured auth yourself.

Example config file

~/.ai-cmd/config.json

{
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "apiKey": "your-api-key",
  "baseUrl": "https://api.openai.com/v1",
  "timeoutMs": 30000,
  "analytics": false
}

Analytics

Analytics are opt-in only.

When enabled, ai-cmd sends anonymous usage events to:

https://tracking.ottili.one/api/aicmd

Usage events include:

• anonymous install count
• CLI starts
• prompt count

Error reports can include:

• prompt
• OS
• version
• timestamp

Regular usage analytics do not store generated command content.

Analytics requests now use a short-lived server-issued session plus proof-of-work. This does not create perfect authentication for a public open-source client, but it makes automated spam substantially harder and gives the server something real to validate.

Server setup notes live in docs/analytics-server.md.

If OpenAI configuration is missing, ai-cmd fails clearly:

Missing AI_API_KEY. Set it in your environment or edit ~/.ai-cmd/config.json. A starter config has been created if it did not already exist.

Usage

One-shot mode

ai "how do I restart nginx"
ai "find all files bigger than 100MB"
ai "show disk usage" --json
ai "remove node_modules and reinstall packages" --exec
ai "find all jpg files" --copy

ai-cmd now inspects the current folder structure and common project files like package.json, Makefile, Cargo.toml, go.mod, and compose files so it can suggest commands that fit the active workspace better.

Interactive mode

ai

Commands available inside the REPL:

• help
• last
• explain
• run
• copy
• clear
• exit

Example session:

ai-cmd > how do I restart nginx
ai-cmd > explain
ai-cmd > run

CLI flags

• --version Show the branded version banner
• --exec Execute the generated command after confirmation
• --yes Skip the normal confirmation step for low and medium risk commands
• --explain Explicitly request explanation details from the provider
• --json Output machine-readable JSON
• --shell <bash|zsh|sh> Hint the active shell
• --copy Copy the generated command to the clipboard
• --no-color Disable colored output
• --debug Print diagnostic context

Safety model

ai-cmd is allowed to execute commands, so the MVP includes a practical safety layer:

• low risk: read-only or status-style commands such as ls -la
• medium risk: service restarts, dependency installs, project-scoped cleanup
• high risk: destructive recursive deletes, disk tools, remote shell pipes, system package removal

Execution rules:

• low and medium risk commands require confirmation unless --yes is used
• high risk commands always require an explicit confirmation phrase
• --yes never bypasses the high-risk confirmation path
• unsupported host OSes can still generate best-effort Unix-style commands, but execution is disabled

Example high-risk confirmation:

Risk: HIGH
This command can delete files recursively outside the current project.
Type EXECUTE HIGH RISK COMMAND to continue:

Supported platforms

• Linux
• macOS
• WSL
• Generic Unix-like systems

Notes:

• Linux service-manager detection prefers systemctl, then service, then rc-service
• macOS service handling prefers launchd-oriented commands
• Native Windows command generation is intentionally limited in this MVP

Architecture

src/
  cli/
  config/
  core/
  exec/
  platform/
  providers/
  safety/
  types/
  utils/
tests/
  integration/
  unit/

Key design choices:

• thin Commander-based CLI layer
• business logic isolated under core/
• provider abstraction isolated under providers/
• platform and service-manager detection isolated under platform/
• execution safety and confirmation logic isolated under safety/
• strict JSON normalization and validation before rendering or execution

Development

npm install
npm run typecheck
npm run lint
npm test
npm run build

Run in development mode:

npm run dev -- "how do I list listening ports"

JSON output

--json prints a structured payload suitable for scripts:

ai "show disk usage" --json

Example shape:

{
  "question": "show disk usage",
  "command": "du -sh .",
  "explanation": "Shows total disk usage for the current directory.",
  "risk": "low",
  "platformNotes": [],
  "assumptions": [],
  "platform": {
    "os": "linux",
    "shell": "bash",
    "serviceManager": "systemctl",
    "cwd": "/work/project",
    "cwdName": "project"
  }
}

Roadmap

• richer shell support
• more precise filesystem-aware risk detection
• Homebrew distribution
• optional standalone binaries
• improved follow-up context handling

License

MIT