HN 日本語サマリー

← 一覧へ戻る
プログラミング

OpenAI CLI

OpenAI CLI (github.com)

203 pointsby armcat95 コメント

要約

OpenAI CLIは、OpenAI REST APIを操作するための公式コマンドラインインターフェースです。HomebrewやGoを使ったインストール方法、APIキーによる認証、リソースベースのコマンド構造、ファイル操作、画像生成などの機能について解説しています。また、環境変数、グローバルフラグ、相互TLS認証、エラーハンドリングなどの詳細な設定や利用方法も説明しています。

全文翻訳

OpenAI CLI

OpenAI REST API の公式CLI。

インストール

Homebrew を使用したインストール
brew install openai/tools/openai
Go を使用したインストール

CLIをローカルでテストまたはインストールするには、Go バージョン1.26以降が必要です。

go install 'github.com/openai/openai-cli/cmd/openai@latest'

go install を実行すると、バイナリはGoのbinディレクトリに配置されます。

  • デフォルトの場所: $HOME/go/bin (GOPATHが設定されている場合は $GOPATH/bin)
  • パスの確認: go env GOPATH を実行してベースディレクトリを確認してください。

インストール後にコマンドが見つからない場合は、GoのbinディレクトリをPATHに追加してください。

# シェルプロファイル（.zshrc, .bashrcなど）に追加
export PATH="$PATH:$(go env GOPATH)/bin"

最初に資格のあるインタラクティブな openai を実行すると、Bash、zsh、fishセッション用に画像ピッカーのTabショートカットがサイレントに保存されます。それらを使用するには、新しいターミナルを開いてください。要件とオプトアウトについては、ショートカットのセットアップと削除を参照してください。PowerShellは通常のTab補完を維持します。openai images generate の後にEnterキーを押すとピッカーが開きます。

アップデート通知

標準の openai は、標準入力、標準出力、標準エラー出力がターミナルである場合に、新しい安定版リリースをチェックします。これは、ヘルプの下に、最大で7日に1回、プレーンテキストの通知として追加されます。明示的なヘルプ、コマンド、補完、CI、リダイレクトされたストリームは、チェックを完全にスキップします。

通知には、CLIがインストール方法を検証できる場合にアップデートコマンドが含まれます。検証済みのHomebrewインストールは brew upgrade --cask openai/tools/openai を使用します。Goコマンドは、検証済みのバイナリ、利用可能なGoコマンド、および明示的な一致する GOBIN を必要とします。カスタム GOOS または GOARCH 設定は、インストールガイドを選択します。Goのメジャーバージョン2以降へのアップグレードもインストールガイドを選択します。不明なインストールには、代わりにインストールガイドへのリンクが表示されます。CLIは自動的にアップデートをインストールしません。

チェックは、API認証情報なしで公開GitHubリリースメタデータを使用し、1日に最大1回実行されます。チェックは HTTPS_PROXY および NO_PROXY（小文字の形式を含む）を尊重します。アップデートの検出は最大200ミリ秒待ちます。チェックが失敗しても何も表示されません。パッケージマネージャーの利用可能性は、新しいGitHubリリースから遅れる場合があります。チェックと通知を無効にするには OPENAI_CLI_NO_UPDATE_CHECK=1 を設定してください。

ローカルでの実行

このプロジェクトのgitリポジトリをクローンした後、scripts/run スクリプトを使用してツールをローカルで実行できます。

./scripts/run args...

使用方法

CLIはリソースベースのコマンド構造に従います。

openai <リソース> [サブリソース...] <コマンド> [フラグ...]

標準APIエンドポイントには、APIキーが必要です。

export OPENAI_API_KEY="sk-..."

openai responses create \
  --input "Say this is a test" \
  --model gpt-5.5

管理者エンドポイントには、管理者APIキーが必要です。

export OPENAI_ADMIN_KEY="sk-admin-..."

openai admin organization usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

openai admin --help や openai admin organization --help のように、各グループを --help で参照してください。既存のコロンコマンド（例: openai admin:organization:usage completions）も引き続き機能します。

openai を実行すると、タスクごとのコマンドグループを参照でき、各グループの説明が表示されます。グループヘルプは、アクションとネストされたコマンドグループを分離し、すべての直接的なコマンドをリストします。ヘルプはAPIキーやネットワーク接続なしで機能します。

openai help setup                  # APIキーを安全に入力する
openai images generate --help      # 例とすべての画像オプション
openai help images generate        # 同じ完全な画像ヘルプ
openai --help                      # コマンドグループとグローバルオプション

コマンドに --help（または -h）を追加すると、完全なヘルプページが表示されます。openai help COMMAND も同じページを表示します。コマンドページにはグローバルオプションがリストされます。それらの完全な説明については、openai --help を使用してください。コマンドオプションの後に --help を配置できます。古い help --all というスペルは、移行ガイドと完全なページを表示します。コマンドの動作、デフォルト、出力形式は変更されません。Tab補完は同じグループ順序に従い、ヘルプトピックとファイル入力パスをサポートします。アップグレード後、新しいファイルパスの動作を有効にするには、シェル補完をリロードしてください。以前にロードされた補完スクリプトは、更新されるまで以前の動作を維持します。

コマンド挿入を有効にすると、例、セットアップガイダンス、リカバリコマンドからコマンドラインを埋めることができます。Ctrl+X、次にTabで、実行せずに候補を検索します。ダブルTabは、Bash、zsh、fishのオプションのバインディングです。

JSONレスポンスが成功した場合、デフォルトで読みやすいテキストが出力されます。これはパイプの場合も同様です。APIデータを解析するスクリプトでは、--format json または --format jsonl を使用してください。抽出、バイナリ出力、および読みやすい表示の範囲については、コマンド結果の読み方を参照してください。

ローカルファイルを明示的な目的とともにアップロードし、そのメタデータを検査してから、コンテンツをダウンロードします。

openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt

file-example を返されたファイルIDに置き換えてください。アップロードは、@ を追加せずにプレーンなパスを取ります。create、retrieve、content、およびそれらの既存のフラグは引き続き利用可能です。リテラルファイル名、出力形式、スクリプト例については、ファイルの操作を参照してください。

openai images generate --prompt "A tiny orange robot" は、画像を ~/Downloads/gpt-images/ に保存し、そのパス（パイプの場合も含む）を出力します。CLIは、明示的なモデルまたはレガシーレスポンス形式なしで保存する場合、gpt-image-2.5-sunburst を使用します。別の正確なIDには --model、ファイル名には --name、既存のディレクトリには --output-dir を使用してください。既存のファイルは保持されます。--format json は、CLIプリセットを保存または適用せずにAPIデータを返します。images edit もソースファイルを保持しながら新しい結果を保存します。images create-variation は廃止され、利用できなくなりました。バリエーションを作成するには、GPT Imageモデルとプロンプトを使用して images edit を使用してください。コマンドとデフォルトについては、画像生成と保存を参照してください。

openai images preview "path/to/image.png" は、APIリクエストなしで保存された画像を再表示します。将来保存された画像が自動的に表示されるかどうかを記憶するには、openai images inline on または off を使用してください。コマンドごとの --inline auto、on、または off はその設定を上書きします。on はローカルApple Terminalで画像フォントも許可します。

エラーはデフォルトでアクション可能なサマリーを標準エラー出力に出力します。元のAPIエラー詳細（不明なフィールドやSDK報告のストリームエラーイベントを含む）を取得するには、--format-error json を使用してください。これらのイベントの場合、抽出パスは error エンベロープを含みます（例: --transform-error error.code）。明示的な --format 値 json、jsonl、raw、yaml は、--format-error で上書きされない限りエラーにも適用されます。明示的な --format-error auto または text はサマリーを復元します。--transform-error は成功した出力とは独立してエラーデータを抽出します。フォーマットされていない、または空のエラーボディには安全な診断が表示されます。SDKが保持している場合にのみHTTPステータスが含まれます。サマリーは拒否された値とリクエストURLを省略します。明示的なAPIエラー詳細は、サーバー提供の機密データを含む場合があります。

環境変数
環境変数必須デフォルト値
OPENAI_API_KEYいいえnull
OPENAI_ADMIN_KEYいいえnull
OPENAI_ORG_IDいいえnull
OPENAI_PROJECT_IDいいえnull
OPENAI_WEBHOOK_SECRETいいえnull
OPENAI_CUSTOM_HEADERSいいえnull
OPENAI_MTLS_CLIENT_CERT_FILEいいえnull
OPENAI_MTLS_CLIENT_KEY_FILEいいえnull
OPENAI_UNTRUSTED_STDINいいえfalse
グローバルフラグ
  • --api-key (OPENAI_API_KEY 環境変数でも設定可能)
  • --admin-api-key (OPENAI_ADMIN_KEY 環境変数でも設定可能)
  • --organization (OPENAI_ORG_ID 環境変数でも設定可能)
  • --project (OPENAI_PROJECT_ID 環境変数でも設定可能)
  • --webhook-secret (OPENAI_WEBHOOK_SECRET 環境変数でも設定可能)
  • --mtls-client-cert-file (OPENAI_MTLS_CLIENT_CERT_FILE 環境変数でも設定可能)
  • --mtls-client-key-file (OPENAI_MTLS_CLIENT_KEY_FILE 環境変数でも設定可能)
  • --help - コマンドラインの使用法を表示
  • --debug - デバッグログを有効にする。これにはHTTPリクエスト/レスポンスの詳細とボディが含まれます。機密性の高いペイロードが含まれる可能性がある場合、デバッグログを共有しないでください。
  • --version, -v - CLIバージョンを表示
  • --base-url - カスタムAPIバックエンドURLを使用します。localhost または 127.0.0.1 および ::1 のようなリテラルループバックIPアドレスを除くHTTPSが必要です。これは OPENAI_BASE_URL にも適用されます。リモートHTTPバックエンドはHTTPSを有効にする必要があります。
  • --header, -H - リテラルのリクエストヘッダーを Name: Value として追加します。複数ヘッダーの場合は繰り返します。
  • --format - 出力形式を変更します (auto, text, explore, json, jsonl, pretty, raw, yaml)。auto はデータを抽出しない限り読みやすいテキストを選択します。
  • --format-error - 標準エラー出力のエラー形式を変更します (auto, text, explore, json, jsonl, pretty, raw, yaml)。auto はエラーデータを抽出しない限り読みやすいサマリーを選択します。
  • --transform - GJSON構文を使用してデータ出力を変換します。
  • --transform-error - GJSON構文を使用してエラー出力を変換します。
リクエストヘッダー

リソースコマンドの前または後に --header または -H を使用します。

openai --header 'X-Trace-ID: example-123' models list \
  -H 'X-Client-Label: local,manual'

値はリテラルです。カンマとコロンは保持され、@ プレフィックスはファイルを読み込みません。値の前後のスペースとタブはトリムされます。-H 'X-Example:' は空の値を送信します。名前が繰り返された場合、大文字小文字を区別せずに最後の値が優先され、デフォルトおよびエンドポイント固有のヘッダーを上書きします。Host や Content-Length のようなHTTPトランスポートによって管理されるヘッダーは、トランスポートの動作を維持します。指定されたヘッダー値はヘルプで非表示になり、デバッグログで赤裸々になります。

認証情報を含むヘッダーの場合、シークレットマネージャーまたは信頼できるランチャーにCLIの環境に直接 OPENAI_CUSTOM_HEADERS を設定させます。これにより、認証情報がコマンド引数から除外され、リテラルのシークレットをシェル履歴に入力するのを回避できます。この変数は、1行あたり1つの Name: Value エントリを受け入れます。例（非機密値の場合）:

export OPENAI_CUSTOM_HEADERS='X-Trace-ID: example-123
X-Client-Label: local,manual'
openai models list

--header およびエンドポイント固有のヘッダーフラグは、一致する環境エントリを上書きします。環境ヘッダー値もデバッグログで赤裸々になります。標準APIおよび管理者認証には OPENAI_API_KEY および OPENAI_ADMIN_KEY を使用してください。

相互TLS (mTLS)

相互TLSは現在ベータ版です。オプトインして組織またはプロジェクトのCA証明書をアクティブ化するには、OpenAI Mutual TLS Beta Program の手順に従ってください。

APIキーリクエストを相互TLSクライアント証明書で認証するには、クライアント証明書と秘密鍵を個別のPEMファイルとして提供します。証明書チェーンサポートが組織で有効になっている場合、証明書ファイルにはリーフ証明書を最初に、その後に中間証明書を含める必要があります。それ以外の場合は、アクティブ化されたCA証明書によって直接署名されたクライアント証明書を使用してください。

export OPENAI_MTLS_CLIENT_CERT_FILE=/run/secrets/openai/client-chain.pem
export OPENAI_MTLS_CLIENT_KEY_FILE=/run/secrets/openai/client.key
export OPENAI_BASE_URL=https://mtls.api.openai.com/v1

openai files list

両方のmTLSファイルは一緒に設定する必要があります。秘密鍵は権限が制限されたファイルに保管してください。秘密鍵の内容をコマンド引数や環境変数に直接含めないでください。CLIは自動的にmTLSエンドポイントを選択しないため、OPENAI_BASE_URL または --base-url を明示的に設定してください。HTTPおよびSOCKSプロキシは引き続きサポートされますが、プロキシ自体のTLSハンドシェイク中にクライアント証明書が提示されるのを防ぐために、HTTPSプロキシは拒否されます。

ファイルを引数として渡す

JSON入力値の場合、@myfile.ext はローカルファイルの内容を読み込みます。

バイナリアップロードフラグはプレーンなパスを使用します。例えば、files upload --file "upload space.txt" --purpose user_data を使用します。ここで、--file "@upload space.txt" は @ で始まる実際のファイル名を指定しており、別のファイル参照を展開しません。ファイル操作については、ファイルの操作を参照してください。

openai <command> --arg @abe.jpg

ファイルはJSONまたはYAMLブロブ内にも渡すことができます。

openai <command> --arg '{image: "@abe.jpg"}'
# 同等:
openai <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

信頼できないソースからJSONまたはYAMLをパイプする場合、信頼できないstdinモードを有効にしてください。

untrusted-producer | OPENAI_UNTRUSTED_STDIN=1 openai <command> --file ./upload.txt

このモードでは、標準入力から提供された値はリテラルデータとして扱われます。リクエストボディ、ヘッダー、クエリパラメータの @、@file://、@data:// 参照はローカルファイルを読み込みません。ファイルアップロードパラメータは、コマンドラインフラグとして明示的に提供する必要があります。明示的なフラグは通常のファイル動作を維持し、標準入力から提供された値よりも優先されます。信頼できるヒアドキュメントや、意図的にローカルファイルを参照するその他の信頼できるパイプ入力を使用する場合は、OPENAI_UNTRUSTED_STDIN を未設定のままにしてください。

@ 記号で始まるリテラル文字列を渡す必要がある場合は、@ 記号をエスケープして、誤ってファイルを渡さないようにすることができます。

openai <command> --username '\@abe'
明示的なエンコーディング

JSONエンドポイントの場合、CLIツールはファイルタイプのスニッフィングを行い、ファイルの内容を文字列リテラル（プレーンテキストファイルの場合）またはBase64エンコードされた文字列リテラル（バイナリファイルの場合）として送信するかどうかを判断します。ファイルを明示的にプレーンテキストまたはBase64エンコードされたデータのいずれかとして送信する必要がある場合は、@file://myfile.txt（文字列エンコーディングの場合）または@data://myfile.dat（Base64エンコーディングの場合）を使用できます。絶対パスは @file:// または @data:// で始まり、その後に3番目の / が続きます（例: @file:///tmp/file.txt）。

openai <command> --arg @data://file.txt

異なるGo SDKバージョンのリンク

./scripts/link スクリプトを使用して、開発目的でCLIをOpenAI Go SDKの異なるバージョンにリンクできます。

特定のバージョンをリポジトリからリンクするには（バージョンはブランチ、gitタグ、またはコミットハッシュにできます）。

./scripts/link github.com/org/repo@version

ローカルコピーのSDKにリンクするには。

./scripts/link ../path/to/openai-go

リンクスクリプトを引数なしで実行すると、デフォルトで ../openai-go になります。

貢献

バグレポートや機能リクエストは、GitHub issues を通じて共有してください。プルリクエストはリポジトリの共同作業者に限定されており、非共同作業者からのプルリクエストは受け付けていません。貢献ポリシーと開発ガイドについては、CONTRIBUTING.md を参照してください。セキュリティ脆弱性については、SECURITY.md に従ってください。

ライセンス

Copyright 2026 OpenAI

このプロジェクトはApache License 2.0の下でライセンスされています。