gladiaio · egenthon-cmd · Jul 6, 2026 · Jul 6, 2026
diff --git a/README.md b/README.md
@@ -16,6 +16,55 @@ powershell -c "irm https://github.com/gladiaio/gladia-cli/releases/latest/downlo
 
 Other platforms: [GitHub releases](https://github.com/gladiaio/gladia-cli/releases).
 
+The installer prompts to set up shell tab completion when run interactively. To skip the prompt (e.g. in CI), set `GLADIA_NO_COMPLETION_PROMPT=1`.
+
+## Shell completion
+
+When you install via `install.sh` or `install.ps1`, the script asks whether to configure tab completion for your shell. You can also set it up manually:
+
+```bash
+gladia completion --help
+```
+
+### bash
+
+Requires the [bash-completion](https://github.com/scop/bash-completion) package (on macOS: `brew install bash-completion@2`).
+
+```bash
+# current session
+source <(gladia completion bash)
+
+# persistent (user directory)
+mkdir -p ~/.local/share/bash-completion/completions
+gladia completion bash > ~/.local/share/bash-completion/completions/gladia
+```
+
+### zsh
+
+```bash
+mkdir -p ~/.zsh/completions
+gladia completion zsh > ~/.zsh/completions/_gladia
+
+# add to ~/.zshrc if not already present:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -U compinit; compinit
+```
+
+### fish
+
+```bash
+mkdir -p ~/.config/fish/completions
+gladia completion fish > ~/.config/fish/completions/gladia.fish
+```
+
+### PowerShell
+
+```powershell
+gladia completion powershell | Out-File -Append -Encoding utf8 $PROFILE
+```
+
+Restart your shell after installing completions.
+
 ## Install (from source)
 
 ```bash
@@ -53,32 +102,33 @@ export GLADIA_API_KEY=your_key
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `transcribe <source>` | Transcribe an audio |
-| `auth set <key>` | Save API key to `~/.gladia` |
-| `languages` | List supported ISO 639-1 codes |
+| Command               | Description                                                 |
+| --------------------- | ----------------------------------------------------------- |
+| `transcribe <source>` | Transcribe an audio                                         |
+| `auth set <key>`      | Save API key to `~/.gladia`                                 |
+| `languages`           | List supported ISO 639-1 codes                              |
+| `completion <shell>`  | Generate shell tab completion (bash, zsh, fish, powershell) |
 
 ## Flags (`transcribe`)
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `-o`, `--output` | `text` | Output: `text`, `json`, `json-full`, `srt`, `vtt` |
-| `--language` | — | Expected language(s), comma-separated (`en` or `en,fr,de`); narrows detection, does not enable code switching |
-| `--cs`, `--code-switching` | off | Re-detect language on each utterance (mixed-language audio; solaria-1 only) |
-| `--diarize` | off | **Optional.** Identify speakers in the transcript |
-| `--model` | — | STT model: `solaria-1` or `solaria-3`. Solaria-3 accepts at most one `--language` (`en`, `fr`, `de`, `es`, or `it`) and does not support code switching. |
-| `-v`, `--verbose` | off | Show progress while polling |
+| Flag                       | Default | Description                                                                                                                                              |
+| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-o`, `--output`           | `text`  | Output: `text`, `json`, `json-full`, `srt`, `vtt`                                                                                                        |
+| `--language`               | —       | Expected language(s), comma-separated (`en` or `en,fr,de`); narrows detection, does not enable code switching                                            |
+| `--cs`, `--code-switching` | off     | Re-detect language on each utterance (mixed-language audio; solaria-1 only)                                                                              |
+| `--diarize`                | off     | **Optional.** Identify speakers in the transcript                                                                                                        |
+| `--model`                  | —       | STT model: `solaria-1` or `solaria-3`. Solaria-3 accepts at most one `--language` (`en`, `fr`, `de`, `es`, or `it`) and does not support code switching. |
+| `-v`, `--verbose`          | off     | Show progress while polling                                                                                                                              |
 
 **Global flag** (any command): `--gladia-key` — API key if not in env or `~/.gladia`
 
 ## Language
 
-| Goal | What to run |
-|------|-------------|
-| Auto-detect | `transcribe <source>` |
-| Constrain detection | `--language en,fr,de` (no code switching) |
-| Code switching | `--cs` or `--code-switching` (+ optional `--language` hints) |
+| Goal                | What to run                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| Auto-detect         | `transcribe <source>`                                        |
+| Constrain detection | `--language en,fr,de` (no code switching)                    |
+| Code switching      | `--cs` or `--code-switching` (+ optional `--language` hints) |
 
 - **`--language`** — limits which language(s) Gladia considers (`en,fr,de` is a hint list, not per-utterance switching).
 - **`--cs`** / **`--code-switching`** — turns on per-utterance language detection. Add `--language` to restrict which languages may appear. Not available with `solaria-3`.

diff --git a/install.ps1 b/install.ps1
@@ -38,6 +38,68 @@ function Add-ToUserPath {
     }
 }
 
+function Write-CompletionHints {
+    Write-Host ''
+    Write-Host 'Shell tab completion is available. To set up manually:'
+    Write-Host '  gladia completion --help'
+    Write-Host '  gladia completion powershell'
+}
+
+function Install-PowerShellCompletions {
+    param(
+        [string]$GladiaExe
+    )
+
+    $profilePath = $PROFILE
+    $profileDir = Split-Path -Parent $profilePath
+    if (-not (Test-Path $profileDir)) {
+        New-Item -ItemType Directory -Path $profileDir -Force | Out-Null
+    }
+    if (-not (Test-Path $profilePath)) {
+        New-Item -ItemType File -Path $profilePath -Force | Out-Null
+    }
+
+    $marker = '# gladia-cli completions'
+    if (Test-Path $profilePath) {
+        $existing = Get-Content -Path $profilePath -Raw -ErrorAction SilentlyContinue
+        if ($existing -and $existing.Contains($marker)) {
+            Write-Host "PowerShell completion already configured in $profilePath"
+            Write-Host 'Restart your terminal for completion to take effect.'
+            return
+        }
+    }
+
+    $completion = & $GladiaExe completion powershell
+    Add-Content -Path $profilePath -Value "`n$marker"
+    Add-Content -Path $profilePath -Value $completion
+    Write-Host "Wrote PowerShell completion to $profilePath"
+    Write-Host 'Restart your terminal for completion to take effect.'
+}
+
+function Maybe-PromptCompletions {
+    param(
+        [string]$GladiaExe
+    )
+
+    if ($env:GLADIA_NO_COMPLETION_PROMPT) {
+        Write-CompletionHints
+        return
+    }
+
+    if ([Console]::IsInputRedirected -or [Console]::IsOutputRedirected) {
+        Write-CompletionHints
+        return
+    }
+
+    $reply = Read-Host 'Install shell tab completion? [y/N]'
+    if ($reply -match '^[yY]') {
+        Install-PowerShellCompletions -GladiaExe $GladiaExe
+    }
+    else {
+        Write-CompletionHints
+    }
+}
+
 $arch = Get-Arch
 $tag = Get-LatestTag
 
@@ -72,6 +134,8 @@ try {
     $installed = Join-Path $installDir $BinaryName
     Write-Host "Installed gladia to $installed"
     Write-Host "Restart your terminal if gladia is not found"
+
+    Maybe-PromptCompletions -GladiaExe $installed
 }
 finally {
     Remove-Item -Recurse -Force $tmpdir -ErrorAction SilentlyContinue

diff --git a/install.sh b/install.sh
@@ -61,6 +61,127 @@ install_binary() {
   fi
 }
 
+gladia_bin() {
+  if command -v "${BINARY}" >/dev/null 2>&1; then
+    command -v "${BINARY}"
+  else
+    printf '%s\n' "${install_dir}/${BINARY}"
+  fi
+}
+
+print_completion_hints() {
+  echo ""
+  echo "Shell tab completion is available. To set up manually:"
+  echo "  gladia completion --help"
+  echo "  gladia completion bash   # requires bash-completion package"
+  echo "  gladia completion zsh"
+  echo "  gladia completion fish"
+}
+
+install_fish_completions() {
+  gladia_cmd="$(gladia_bin)"
+  mkdir -p "${HOME}/.config/fish/completions"
+  "${gladia_cmd}" completion fish > "${HOME}/.config/fish/completions/gladia.fish"
+  echo "Wrote fish completion to ~/.config/fish/completions/gladia.fish"
+  echo "Restart your shell for completion to take effect."
+}
+
+install_zsh_completions() {
+  gladia_cmd="$(gladia_bin)"
+  mkdir -p "${HOME}/.zsh/completions"
+  "${gladia_cmd}" completion zsh > "${HOME}/.zsh/completions/_gladia"
+
+  zshrc="${ZDOTDIR:-${HOME}}/.zshrc"
+  if [ -f "${zshrc}" ] && grep -q '# gladia-cli completions' "${zshrc}" 2>/dev/null; then
+    echo "Updated zsh completion at ~/.zsh/completions/_gladia"
+    echo "Restart your shell for completion to take effect."
+    return 0
+  fi
+
+  if [ ! -f "${zshrc}" ]; then
+    : > "${zshrc}"
+  fi
+
+  cat >> "${zshrc}" <<'EOF'
+
+# gladia-cli completions
+fpath=(~/.zsh/completions $fpath)
+autoload -U compinit; compinit
+EOF
+  echo "Wrote zsh completion to ~/.zsh/completions/_gladia"
+  echo "Restart your shell for completion to take effect."
+}
+
+install_bash_completions() {
+  gladia_cmd="$(gladia_bin)"
+  target=""
+
+  if [ -d "${HOME}/.local/share/bash-completion" ]; then
+    mkdir -p "${HOME}/.local/share/bash-completion/completions"
+    target="${HOME}/.local/share/bash-completion/completions/gladia"
+  elif command -v brew >/dev/null 2>&1; then
+    brew_prefix="$(brew --prefix 2>/dev/null || true)"
+    if [ -n "${brew_prefix}" ] && [ -d "${brew_prefix}/etc/bash_completion.d" ]; then
+      target="${brew_prefix}/etc/bash_completion.d/gladia"
+    fi
+  fi
+
+  if [ -n "${target}" ]; then
+    "${gladia_cmd}" completion bash > "${target}"
+    echo "Wrote bash completion to ${target}"
+    echo "Restart your shell for completion to take effect."
+    return 0
+  fi
+
+  echo "Could not find a bash-completion directory."
+  echo "Install the bash-completion package, then run:"
+  echo "  gladia completion bash > ~/.local/share/bash-completion/completions/gladia"
+  echo "Or add to your shell rc:"
+  echo "  source <(gladia completion bash)"
+}
+
+install_completions() {
+  shell_name="$(basename "${SHELL:-}")"
+  case "${shell_name}" in
+    fish)
+      install_fish_completions
+      ;;
+    zsh)
+      install_zsh_completions
+      ;;
+    bash)
+      install_bash_completions
+      ;;
+    *)
+      echo "Unknown shell (${shell_name}). Run: gladia completion --help"
+      print_completion_hints
+      ;;
+  esac
+}
+
+maybe_prompt_completions() {
+  if [ -n "${GLADIA_NO_COMPLETION_PROMPT:-}" ]; then
+    print_completion_hints
+    return 0
+  fi
+  if [ ! -t 0 ] || [ ! -t 1 ]; then
+    print_completion_hints
+    return 0
+  fi
+
+  printf "Install shell tab completion? [y/N] "
+  reply=""
+  read -r reply || true
+  case "${reply}" in
+    [yY]|[yY][eE][sS])
+      install_completions
+      ;;
+    *)
+      print_completion_hints
+      ;;
+  esac
+}
+
 os="$(detect_os)"
 arch="$(detect_arch)"
 tag="$(fetch_latest_tag)"
@@ -98,3 +219,5 @@ else
   echo "Installed ${BINARY} to ${install_dir}/${BINARY}"
   echo "Ensure ${install_dir} is in your PATH"
 fi
+
+maybe_prompt_completions