zshでawsコマンドをエイリアスに設定したらAWS CLIのタブ補完が効かなくなった！その解消方法

コンバンハ、千葉（幸）です。

AWS CLIではタブ補完（command completion）の機能があります。コマンドのやパラメータの一部を入力した状態でTABキーを押すと候補リストを表示してくれるものです。

https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-configure-completion.html

👇ドキュメントから引用した例。aws dynamodbのサブコマンドとしてdを打った後にTABを入力することで、dから始まるサブコマンドのリストが表示されている。

$ aws dynamodb dTAB
delete-backup                        describe-global-table
delete-item                          describe-global-table-settings
delete-table                         describe-limits
describe-backup                      describe-table
describe-continuous-backups          describe-table-replica-auto-scaling
describe-contributor-insights        describe-time-to-live
describe-endpoints

LinuxやMacでは、zsh、bash、tcshといったシェルの種類に応じてプロファイルに適切な記述を行うことでAWS CLIのタブ補完が実現できるようになります。

zshの場合は~/.zshrcに以下のように記述します。^[1]

autoload -Uz compinit && compinit
autoload bashcompinit && bashcompinit
complete -C '/usr/local/bin/aws_completer' aws

別途、~/.zshrcにawsを別名とするエイリアス設定の記述を行った後にこのタブ補完が効かなくなったことがありました。

結果的にsetopt completealiasesを追記することで事象が解決できたので、その内容をまとめます。

環境情報

• zsh 5.9 (arm64-apple-darwin24.0)
• macOS Sequoia 15.5
• aws-cli/2.32.6 Python/3.13.9 Darwin/24.5.0 exe/arm64
• op 2.32.0（今回エイリアスを追加するきっかけになった1passwordのCLI）

何に困っていたのか

変更前の~/.zshrcが以下の内容でした。

autoload -Uz compinit && compinit
autoload bashcompinit && bashcompinit
complete -C '/usr/local/bin/aws_completer' aws

以下のように1行追加しました。

autoload -Uz compinit && compinit
autoload bashcompinit && bashcompinit
+ source /Users/chiba.yukihiro/.config/op/plugins.sh
complete -C '/usr/local/bin/aws_completer' aws

結果、AWS CLIのタブ補完が効かなくなりました。困りました。

追加した行の内訳は？

これは以下のブログで取り上げられている内容に沿ったものです。

https://dev.classmethod.jp/articles/1password-cli-credential/

作業端末上の~/.aws/credentialをなくすために1Password CLIに認証情報を移しました。AWS CLIを実行する際に毎回1Password CLIのShell Pluginを経由させるようプロファイルに設定を加えています。

ここではわたしの名前を入れていますが、もちろん実際のユーザー名にあわせて変更が必要な部分です。

読み込んでいるスクリプトの内訳はこうなっています。

export OP_PLUGIN_ALIASES_SOURCED=1
alias aws="op plugin run -- aws"

op plugin run -- awsのエイリアスとしてawsが設定されています。

どう解消したのか

さらに1行追加しました。

autoload -Uz compinit && compinit
autoload bashcompinit && bashcompinit
+ setopt completealiases
source /Users/chiba.yukihiro/.config/op/plugins.sh
complete -C '/usr/local/bin/aws_completer' aws

ここでは3行目に追加していますが、深い意味はありません。どこに挿入しても問題なく動作しました。

また、ここまで説明の簡素化のため改行や#でのコメントを入れていませんが、もちろんそれらを自由に追加して問題ありません。

とにかく上記の1行を追加後、再度プロファイルを読みすと「AWS CLIのタブ補完」「AWS CLI実行時の1Passwordプラグイン利用」が両立できました。よかったです。

なにが原因でどう解消されたのか

まず、各記述について簡単に説明します。コメントを入れてみました。

# -------------------------------
# Zsh の補完機能の初期化
# -------------------------------
# zsh の標準補完システムを読み込み、補完機能を有効化する。
autoload -Uz compinit && compinit

# Bash 互換の補完機能（bash-completion 形式）を利用可能にする。
# AWS CLI の補完設定（complete -C）に必要。
autoload bashcompinit && bashcompinit

# エイリアスの先にある実コマンドの補完を有効化する。
# 例: alias aws="op plugin run -- aws" のように、コマンドをラップするエイリアスに対しても適切な補完を機能させるために必要。
setopt completealiases

# -------------------------------
# 1Password CLI（op）プラグインの読み込み
# -------------------------------
# op plugins が提供するエイリアス設定を読み込む。
# このファイル内で aws コマンドを op plugin 経由で実行するエイリアスが定義される。
source /Users/chiba.yukihiro/.config/op/plugins.sh

# -------------------------------
# AWS CLI の補完設定
# -------------------------------
# 「aws <TAB>」を実行した際に、aws_completer プログラムを使って
# AWS CLI のコマンド・オプションを補完するよう設定する。
complete -C '/usr/local/bin/aws_completer' aws

# このフラグは、1Password CLI（op）のプラグイン設定が
# 既に読み込まれたことを示すための環境変数。
# 複数回読み込まれた際にエイリアスが重複定義されるのを防ぐ役割を持つ。
export OP_PLUGIN_ALIASES_SOURCED=1

# AWS CLI を利用する際、コマンド実行を 1Password CLI (op) を経由するようにするエイリアス。
# これにより、1Password に保存された AWS 認証情報を自動で取得して実行できる。
alias aws="op plugin run -- aws"

重要なところは以下です。

• complete -C '/usr/local/bin/aws_completer' aws
  • 「aws コマンド向けにaws_completerで補完するよ」
• alias aws="op plugin run -- aws"
  • 「op plugin run -- awsのエイリアスとしてawsを設定するよ」

これらの関係性を簡単に説明するとこのようなイメージです。

元々の記述ではエイリアスであるawsにcompleteが適用されない、という状態でした。これが事象の原因です。

そしてsetopt completealiasesを設定することでエイリアスであるawsにも補完が効くようになり、これで事象が解決したというわけです。

setopt completealiasesとは？

setopt completealiasesの説明についてはこのあたりを見るのがよさそうです。

👉 zsh: 16 Options

• COMPLETE_ALIASES

  Prevents aliases on the command line from being internally substituted before completion is attempted. The effect is to make the alias a distinct command for completion purposes.

man zshoptionsでも同じ内容が確認できます。

なるべく直訳すると以下のようになるでしょうか。

コマンドライン上のエイリアスが、補完が試みられる前に内部的に置き換えられるのを防ぐ。

その結果として、補完の目的においてそのエイリアスを独立したコマンドとして扱うようになる。

この設定がないと、「aws コマンド向けにaws_completerで補完する」という試みが行われる前に「awsはop plugin run -- awsである」という変換が内部で行われ、結果としてawsを使用してのAWS CLI補完ができなくなります。

setopt completealiasesが指定されることで、エイリアスであるawsにも補完を行うよう挙動が変わるということのようでした。

終わりに

zshでawsコマンドをエイリアスに設定したらAWS CLIのタブ補完が効かなくなった！という場合の解消方法について紹介しました。

他にも解消方法はあるかもしれませんが、一番シンプルなのはsetopt completealiasesを指定することかと思います。

普段あまり気にすることがなかったzshのオプションの一端が垣間見れて楽しかったです。同様の事象に見舞われた方の参考になれば幸いです。

以上、チバユキ (@batchicchi)がお送りしました。