AI Shell

Setup

The minimum supported Node.js version is v22.

1. Install AI Shell:

   npm install -g @arcasilesgroup/ai-shell

2. Run the provider wizard:

   ai config

   Pick your provider (OpenAI, NaN Builders, OpenRouter, Groq, Together, Ollama, LM Studio, llama.cpp, or your own endpoint), paste your API key, and the wizard lists the real models from your endpoint (GET /v1/models) and runs a connection test before saving.

   You can also configure everything by hand in ~/.ai-shell, a plain INI file:

   PROVIDER=nan
   API_KEY=sk-...
   API_ENDPOINT=https://api.nan.builders/v1
   MODEL=qwen3.8-flash

   Any OpenAI-compatible API works (/v1/chat/completions). With local servers (Ollama, LM Studio, llama.cpp) the key can be any value.

   Legacy OPENAI_KEY / OPENAI_API_ENDPOINT keys are still read if you already have them; on write, they are saved under the new names.

3. Check anytime that your configuration works:

   ai config test

Usage

ai <prompt>

For example:

ai list all log files

You get the suggested command and can choose to run it, edit it, ask for a revision, or copy it.

Special characters

Some shells treat characters like ? or * specially. If you get strange behavior, wrap the prompt in quotes:

ai 'what is my ip address'

Chat mode

ai chat

A continuous conversation in your terminal; history stays in memory until you exit.

Silent mode (skip explanations)

ai -s list all log files

or as a saved preference:

ai config set SILENT_MODE=true

Language

ai config set LANGUAGE=es

Available keys: en, es, zh-Hans, zh-Hant, fr, de, it, pt, ru, uk, tr, ar, id, vi, jp, ko.

Action icons

The run/revise menu is plain by default — clack's cursor and color already mark the selection. If your terminal uses a Nerd Font (e.g. brew install font-jetbrainsmono-nerd-font), you can opt into glyphs:

ai config set ICONS=nerd

Privacy

• The CLI runs 100% on your machine. Prompts travel only from your terminal to the endpoint you configure.
• No telemetry, no middle backend, no accounts.
• Executed commands are appended to your own .zsh_history / .bash_history.

Built and maintained with ai-engineering

This repository is built and maintained with ai-engineering — the governance framework for AI-assisted development by Arcasiles Group. Quality gates, security scanning, and risk management run locally through git hooks and in CI:

uv tool install ai-engineering
ai-eng init          # this machine, and this repository if you say yes
just check           # the exact gate CI runs

The rules of the house are in CONSTITUTION.md and AGENTS.md; release versions come from changesets and publish through CI with OIDC provenance — never from a laptop.

Updating

ai update

Contributing

Bugs and feature requests in Issues. Setup details in CONTRIBUTING.md.

Credits

• Based on BuilderIO/ai-shell (MIT), whose legal attribution is kept in LICENSE.