feat: add shell completions for bash, zsh and fish

.goreleaser.yaml

@@ -39,6 +39,8 @@ archives:
       - README.md
       - CHANGELOG.md
       - docs/aiterm.1
+      - src: completions/*
+        dst: completions
 
 checksum:
   name_template: checksums.txt

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Ship a man page for aiterm in release archives.
+- Shell completions for bash, zsh and fish in `completions/`, shipped in
+  the release archives. See the README's Shell completions section for
+  how to enable them.
 
 ## [0.2.0] - 2026-10-04
 

README.md

@@ -73,6 +73,37 @@ cd aiterm
 go build -o aiterm .
 ```
 
+## Shell completions
+
+Completion scripts for bash, zsh and fish live in `completions/` and are
+included in the release archives. They complete the flag names; `-timeout`
+also suggests a few durations. Everything after the flags is the request,
+so there is nothing to complete there.
+
+For bash, copy the script into your completion directory and start a new
+shell:
+
+```bash
+sudo cp completions/aiterm.bash /etc/bash_completion.d/aiterm
+```
+
+On macOS with Homebrew the directory is `/usr/local/etc/bash_completion.d/`
+(or `/opt/homebrew/etc/bash_completion.d/` on Apple silicon).
+
+For zsh, copy the script as `_aiterm` into a directory on your `fpath`:
+
+```bash
+mkdir -p ~/.zsh/completions
+cp completions/_aiterm ~/.zsh/completions/
+autoload -Uz compinit && compinit
+```
+
+For fish, copy the script into your completions directory:
+
+```bash
+cp completions/aiterm.fish ~/.config/fish/completions/
+```
+
 ## Configuration
 
 `aiterm` needs an API key. Flags go before the request and take precedence over
@@ -103,6 +134,8 @@ export AITERM_TIMEOUT="5m"   # optional: give slow local models more time
 
 ## Usage
 
+The full command reference is in the [`aiterm(1)` manual page](docs/aiterm.1).
+
 Pass your request as arguments. Quotes are optional for plain words, but your shell
 expands the arguments before `aiterm` sees them, so quote the request if it contains
 characters such as `*`, `?`, `&`, `|`, `;`, `<`, `>`, `#`, `$` or an apostrophe.
@@ -155,7 +188,6 @@ CodeQL, govulncheck and a GoReleaser snapshot build. Releases are built by
 
 ## Roadmap
 
-- Shell completions for bash, zsh and fish ([#3](https://github.com/Thakay/aiterm/issues/3))
 - An explain option that describes what a command does before you run it ([#5](https://github.com/Thakay/aiterm/issues/5))
 - Anthropic and Gemini models ([#6](https://github.com/Thakay/aiterm/issues/6))
 - Windows support with PowerShell commands ([#7](https://github.com/Thakay/aiterm/issues/7))

completions/_aiterm

@@ -0,0 +1,18 @@
+#compdef aiterm
+#
+# zsh completion for aiterm
+#
+# Install: copy or symlink this file as _aiterm into a directory on your
+# fpath, e.g. ~/.zsh/completions, and run compinit. See the README's Shell
+# completions section for details.
+
+# Flags go before the request, so -A stops offering them once it has started.
+_arguments -S -A '-*' \
+  '-key=[OpenAI API key]:API key:' \
+  '-url=[chat completions endpoint of an OpenAI compatible API]:URL:' \
+  '-model=[model to use]:model:' \
+  '-timeout=[how long to wait for the API]:duration:(30s 2m 5m)' \
+  '-version[print version information and exit]' \
+  '-h[show help information]' \
+  '-help[show help information]' \
+  '*:request:'

completions/aiterm.bash

@@ -0,0 +1,56 @@
+# bash completion for aiterm
+#
+# Install: copy or symlink this file into your bash completion directory,
+# e.g. /etc/bash_completion.d/ or /usr/local/etc/bash_completion.d/ on macOS
+# with Homebrew, and start a new shell. See the README's Shell completions
+# section for details.
+
+_aiterm()
+{
+    local cur prev i
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    case "$prev" in
+        -timeout)
+            COMPREPLY=( $(compgen -W "30s 2m 5m" -- "$cur") )
+            return 0
+            ;;
+        -key|-url|-model)
+            # Free-text values; nothing to complete.
+            return 0
+            ;;
+    esac
+
+    # Flags go before the request. Once the request has started, or after
+    # "--", there is nothing to complete: it is free text.
+    for (( i = 1; i < COMP_CWORD; i++ )); do
+        case "${COMP_WORDS[i]}" in
+            --)
+                return 0
+                ;;
+            -key|-url|-model|-timeout)
+                # Skip the value. bash splits "-flag=value" into "-flag", "="
+                # and "value".
+                if [[ "${COMP_WORDS[i+1]}" == "=" ]]; then
+                    (( i += 2 ))
+                else
+                    (( i++ ))
+                fi
+                ;;
+            -*)
+                ;;
+            *)
+                return 0
+                ;;
+        esac
+    done
+
+    if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-key -url -model -timeout -version -h -help" -- "$cur") )
+    fi
+    return 0
+}
+
+complete -F _aiterm aiterm

completions/aiterm.fish

@@ -0,0 +1,12 @@
+# fish completion for aiterm
+#
+# Install: copy or symlink this file into ~/.config/fish/completions/.
+# See the README's Shell completions section for details.
+
+complete -c aiterm -o key -d 'OpenAI API key' -x
+complete -c aiterm -o url -d 'chat completions endpoint of an OpenAI compatible API' -x
+complete -c aiterm -o model -d 'model to use' -x
+complete -c aiterm -o timeout -d 'how long to wait for the API' -x -a '30s 2m 5m'
+complete -c aiterm -o version -d 'print version information and exit'
+complete -c aiterm -o h -d 'show help information'
+complete -c aiterm -o help -d 'show help information'