Shell integration

The `spai` Command

spai is the primary interface to spaiSH. It works from any shell — bash, zsh, fish, or any POSIX-compatible shell.

Your existing shell and workflow are completely unchanged. spai is an additional command, not a replacement. Regular shell commands never pass through AI.

$ ls -la          # normal shell, no AI involved
$ git status      # same
$ spai explain why my build failed   # only this goes through spaid

Usage

spai <natural language query>

Examples

# System administration
spai nginx keeps returning 502, find out why
spai show me what's using the most disk space
spai which process is listening on port 3000

# File operations
spai find all log files modified in the last 24 hours
spai compress everything in ~/Downloads older than 30 days

# Development
spai why did my last git push fail
spai explain what this Makefile does
spai set up a python virtual environment for this project

# Diagnostics
spai my wifi keeps dropping, check what's wrong
spai why is this machine running slow right now

Flags

spai --dry-run "clean up old docker images"   # show plan, never execute
spai --local "explain this log file"          # force local model
spai --legal                                  # print disclaimer and exit
spai --help                                   # usage information
spai !!                                       # analyse the last failed command

How It Works

You run spai <query>
spai connects to the spaid daemon via Unix socket
spaid adds system context (current directory, recent history, git state)
spaid routes the request to your configured AI provider
The AI proposes a plan — one or more commands
spaid classifies each command by permission tier
Commands that require confirmation are shown to you before running
You confirm, and the commands execute
Output streams back to your terminal
You’re back at your normal prompt

First Run

On first run, spaiSH shows a one-time disclaimer:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  spaiSH — experimental personal project
  Not affiliated with any AI provider or Linux distribution.
  You are responsible for your API key usage and costs.
  Run 'spai --legal' for full disclaimer and license.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is shown once and never again.

Installation

Requirements

Linux (any modern distribution)
systemd (for the user service)
An AI provider API key or Ollama running locally

Install

curl -fsSL https://get.spaish.dev/install.sh | bash

No root required. The installer:

Downloads spai and spaid binaries to ~/.local/bin/
Creates default config at ~/.config/spaish/spaid.toml
Registers spaid as a systemd user service
Prints next steps

Configure your AI provider

Set your API key as an environment variable. Add to ~/.bashrc or ~/.zshrc:

export SPAI_API_KEY="your-key-here"

Then edit ~/.config/spaish/spaid.toml to point at your provider’s endpoint and set your model name.

Using a local model instead

Install Ollama and pull a model:

# Install Ollama (see ollama.com for instructions)
ollama pull qwen2.5-coder   # recommended for system tasks

spaiSH will automatically use Ollama if no API key is set and Ollama is running.

Uninstall

curl -fsSL https://get.spaish.dev/uninstall.sh | bash

Removes all binaries, config, and the systemd service. Your shell rc file is cleaned up.

Managing the Daemon

systemctl --user status spaid     # check if running
systemctl --user restart spaid    # restart
systemctl --user stop spaid       # stop
journalctl --user -u spaid -f     # live logs