Add shell autocomplete support for openai CLI

[alpnix]

Summary

Implements #843 by adding comprehensive shell autocomplete for the openai CLI, matching the functionality found in popular CLIs like GitHub CLI and Stripe CLI.

Changes

New Files:

• src/openai/cli/_completion.py - Completion script generator for all shells
• COMPLETION.md - Comprehensive usage and installation documentation

Modified:

• src/openai/cli/_cli.py - Added completion subcommand integration

Features

Supported Shells

• Bash (Linux, macOS, WSL)
• Zsh (macOS default, Linux)
• Fish (cross-platform)
• PowerShell (Windows, cross-platform)

Usage

# Generate completion script
openai completion bash
openai completion zsh
openai completion fish
openai completion powershell

# Show installation instructions
openai completion bash --instructions

# Quick install (bash example)
eval "$(openai completion bash)"

What Gets Autocompleted

• Top-level commands (api, chat, audio, models, etc.)
• Global flags (--api-key, --organization, --help, etc.)
• Subcommands (context-aware)
• Shell types for the completion command itself

Implementation Details

• Zero external dependencies - uses native shell completion frameworks
• Follows established patterns from gh and stripe CLIs
• Lightweight (< 400 lines total)
• Easy to extend for future commands
• Works seamlessly with existing CLI structure

Testing

# Syntax validation
python3 -m py_compile src/openai/cli/_completion.py

# Generate and inspect
openai completion bash | head -20

# Install and test tab completion
eval "$(openai completion bash)"
openai <TAB>

Installation Instructions

Each shell has simple installation:

Bash:

eval "$(openai completion bash)"  # Quick
# Or: openai completion bash > ~/.openai-completion.bash

Zsh:

eval "$(openai completion zsh)"  # Quick
# Or: openai completion zsh > ~/.zsh/completions/_openai

Fish:

openai completion fish > ~/.config/fish/completions/openai.fish

PowerShell:

openai completion powershell | Out-String | Invoke-Expression

Example Usage

$ openai <TAB>
api  chat  audio  models  files  fine-tuning  embeddings  images  completions  completion

$ openai --<TAB>
--api-key  --organization  --api-base  --api-version  --help  --version

$ openai completion <TAB>
bash  zsh  fish  powershell

Benefits

• Faster workflow - No need to remember exact command names
• Discoverability - See available commands and flags
• Reduced typos - Tab completion ensures correct syntax
• Better UX - Matches user expectations from other popular CLIs

Closes #843

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98df1c1746

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Call completion handler with parsed arguments

The new completion_handler requires a positional args, but this subparser never sets args_model, so _main() follows the no-model path and calls parsed.func() with zero arguments. As a result, any openai completion ... invocation raises TypeError instead of printing a completion script or instructions, making the new command unusable for all shells.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Complete only valid top-level CLI commands

The Bash completion candidates include chat, audio, models, etc. as top-level commands, but the parser only registers api, tools, and completion at the top level. This causes tab completion to suggest commands that immediately fail and omits tools, so the generated completion script is inaccurate for normal CLI usage.

Useful? React with 👍 / 👎.