fastly-cli

トリガーと対象範囲

重要：多くのサブコマンドは、直感に反するパスを使用します（例：fastly domain create は 403 で失敗し、正しくは fastly service domain create です。ロギングは fastly service logging、アラートは fastly service alert、レート制限は fastly service rate-limit です）。

対象：サービス、バックエンド、ドメイン、VCL スニペット、キャッシュのパージ、Compute/WASM のデプロイ、ログストリーミング（S3/Datadog/Splunk/Kafka/25 以上のプロバイダー）、NGWAF/WAF、TLS/mTLS、KV/構成/シークレットストア、統計、アラート、レート制限、ACL、認証トークン。

Fastly CLI の概要

前提条件

fastly CLI が必要です。API 操作には Fastly へのネットワークアクセスも必要です。 インストール方法については、https://www.fastly.com/documentation/reference/cli/ を参照してください。 JSON の例では jq も必要です。オリジンの確認には curl と openssl を使用します。 Compute のビルドには、プロジェクトの言語ツールチェーンと依存関係が必要です。

ユーザーのローカル CLI または環境にすでに設定されている認証情報を使用してください。 認証情報が設定されていない場合は、ユーザー自身がローカルで fastly auth login --sso を完了するか、チャット外で FASTLY_API_TOKEN を設定するよう案内してください。 チャットで API キーを尋ねたり、トークンを表示したり、認証済みコマンドでシェルのトレースを有効にしたりしないでください。

参考資料

トピック	ファイル	使用する場面
認証	auth.md	ログイン、保存されたトークン、サービス認証、CI/CD 認証の設定
Compute	compute.md	エッジアプリケーションのビルド／デプロイ、ローカル開発サーバー
サービス	services.md	サービスの CRUD、バックエンド、ドメイン、ACL、ディクショナリ、VCL、パージ、レート制限
ロギング	logging.md	S3、GCS、Datadog、Splunk、Kafka、25 以上のプロバイダーへのログストリーミング
NGWAF	ngwaf.md	Next-Gen WAF のワークスペース、IP／国のリスト、ルール、シグナル、しきい値、アラート
通知	notifications.md	Slack/PagerDuty/webhook の統合、監査ログのイベントマッピング
統計	stats.md	各 fastly stats サブコマンドが使用するフラグ、および 2 つのフラグセットの相違点
ストア	stores.md	KV ストア、Config ストア、Secret ストア、リソースリンク
TLS	tls.md	プラットフォーム TLS、Let's Encrypt サブスクリプション、カスタム証明書、相互 TLS

エンドポイントの選択、単位と期間の規約、クエリ例については、fastly-stats スキルを使用してください。

コマンド構造

fastly <command> <subcommand> [flags]

トップレベルコマンド

カテゴリ	コマンド
コンピューティング	compute - エッジアプリケーションをビルドしてデプロイします
サービス	service - CDN サービス、ロギング、バックエンド、VCL、ACL、パージを管理します
セキュリティ	ngwaf - Web アプリケーションファイアウォール
TLS	tls-subscription、tls-custom、tls-platform、tls-config - 証明書を管理します
ストレージ	kv-store、config-store、secret-store - エッジデータストア
認証	auth - ログイン、保存済みトークン、アクティブなトークンの出力、失効；auth-token（非推奨）
情報	stats、ip-list、pops、whoami - 情報を照会します
通知	integration - 通知先；audit-log event-mapping - イベントトリガー
その他	dashboard、domain、dns、apisecurity、products、object-storage、tools

グローバルフラグ

ほとんどのコマンドで使用できます。

# Service targeting
--service-id SERVICE_ID    # Target service by ID
--service-name NAME        # Target service by name
-s SERVICE_ID              # Short form

# Version targeting (version-scoped commands like `fastly service domain/backend/...`)
# NOTE: `fastly domain create` does NOT accept --version (it uses a different API)
--version VERSION          # Specific version number
--version active           # Currently active version
--version latest           # Most recent version
--version staged           # Currently staged version

# Authentication
--token TOKEN              # API token or stored token name (use 'default' for default)

# Output (--json is per-command, not global)
--verbose                  # Detailed output
--quiet                    # Minimal output

# Automation
--accept-defaults          # Accept default values
--auto-yes                 # Skip confirmations
--non-interactive          # No prompts

主なパターン

• ID（-s SERVICE_ID）または名前（--service-name NAME）で対象を指定します
• バージョンの指定：--version active、--version latest、--version staged、または--version N
• ロックされたバージョンを自動で複製するには、--autocloneを使用します
• スクリプトで扱う出力には--jsonを、CI/CD では--non-interactive --accept-defaultsを使用します
• JSON のフィールド名はコマンドによって異なります。jqのセレクターを記述する前に出力を確認してください。
• ActiveVersionの形式はさまざまです。--version activeを優先するか、jq -r '.ActiveVersion.Number // .ActiveVersion'で解析してください
• CLI のバージョンを確認するコマンドはfastly versionです（fastly --versionではありません）
• POP／シールドの検索にはfastly popsを使用します。listサブコマンドと--jsonはありません。--shieldには、POP のCODEではなくSHIELD列の値を使用してください
• 認証：ログインにはfastly auth login --ssoを使用するか、FASTLY_API_TOKEN環境変数を設定します
• アクティブな API トークンを必要とするコマンドでは、$(fastly auth token)を使用します。特定の保存済みトークンを選択するには、$(fastly auth token --token TOKEN_NAME)を使用します
• auth tokenはターミナルへの出力を拒否しますが、エージェントが取得する標準出力は非ターミナルの場合があります。単独で実行したり、その結果をエコーしたりしないでください
• ロギングはservice loggingの配下にあります（例：fastly service logging s3 create）
• 設定：プラットフォーム固有の CLI 設定ファイルを確認するにはfastly config --locationを使用します。fastly.tomlはプロジェクトマニフェストです

よく使うフラグの例

特に混乱しやすいフラグです。以下のパターンをそのままコピーして使用してください。

自動複製（既存サービスのバージョン）

# --autoclone automatically clones a locked version before making changes.
# Without it, you get "version is locked" errors and waste time cloning manually.
fastly service backend create --service-id $SID --version active --autoclone \
  --name my-origin --address origin.example.com --port 443 --use-ssl

fastly service domain create --service-id $SID --version active --autoclone \
  --name cdn.example.com

既存サービスのバージョンに対して、バックエンド、ドメイン、スニペット、VCL、条件、ヘッダー、その他のバージョン単位のリソースを作成、更新、削除する場合は、--autocloneを指定します。 新しいサービスの場合は、以下の新規サービスのワークフローに示すように、ロック解除済みの--version 1を--autocloneなしで設定し、その後、検証して一度だけ有効化します。

ブール値フラグ（--use-ssl。--use-ssl trueではありません）

# CORRECT - boolean flags are bare, no value
fastly service backend create --name origin --address example.com --port 443 --use-ssl

# WRONG - do not pass a value to boolean flags
fastly service backend create --name origin --address example.com --port 443 --use-ssl true

同様に機能するその他のブール値フラグ：--auto-yes、--non-interactive、--verbose、--quiet、--autoclone。

ドメインの作成（--nameフラグが必要）

# CORRECT
fastly service domain create --service-id $SID --version active --autoclone --name cdn.example.com

# WRONG - domain is not a positional argument
fastly service domain create --service-id $SID --version active cdn.example.com

# WRONG - there is no -d flag
fastly service domain create --service-id $SID --version active -d cdn.example.com

統計（過去およびリアルタイム）

# Historical stats by day for a date range (JSON output)
fastly stats historical --service-id $SID --by day \
  --from "2026-02-01" --to "2026-03-01" --json

# Real-time stats (last second)
fastly stats realtime --service-id $SID --json

--byフラグで指定できる値：day、hour、minute。--fromフラグと--toフラグには、引用符で囲んだ日付文字列を指定します。統計コマンドで JSON を出力するには、--jsonを使用します。

反映の遅延

変更が Fastly のネットワーク全体に反映されるまで、数秒から数分かかります（バージョンの有効化では最大 10 分、TLS では最大 5 分）。キャッシュのパージは 1～2 秒で完了します。変更を確認するときは、バックオフを入れて再試行してください。

新しいサービスの有効化手順：まったく新しいサービスを有効化した後は、ドメインがエッジ POP に反映されるまでの 10～60 秒間、500「Domain Not Found」が返ることがあります。これは正常な動作です。設定を変更せず、待ってから再試行してください。バージョンを更新した後（バックエンド設定の修正など）は、新しいバージョンが反映されるまで 15～30 秒お待ちください。

KV Store の注意点

• 使用前にリンクする：Compute コードから KV ストアにアクセスするには、サービスのバージョンにリンクする必要があります。fastly kv-store create を実行し、その後 fastly service resource-link create --resource-id STORE_ID --service-id $SID --version active --autoclone を実行してください。
• 結果整合性：読み取り後の書き込みは結果整合性です。書き込んだばかりのキーは、数秒間読み取れない場合があります。スクリプトで直後の読み取り結果に依存せず、短い待機時間を設けるか、再試行ループを追加してください。
• エントリーサイズの上限：個々の KV ストアエントリーの上限は 25 MB です。大きな値を扱う場合は、これを考慮してください。
• ストアの一覧表示：fastly kv-store list は、サービスごとではなく、アカウント上のすべてのストアを一覧表示します。特定のサービスにリンクされているストアを確認するには、fastly service resource-link list を使用してください。

Host ヘッダーのオーバーライドパターン

オリジンのホスト名と送信したい Host ヘッダーが異なる場合（例：オリジンが example.com で、Host: download.example.com を送信したい場合）、バックエンドで --override-host を使用してください：

fastly service backend create --service-id $SID --version 1 \
  --name my-origin --address example.com --port 443 --use-ssl \
  --override-host download.example.com \
  --ssl-cert-hostname example.com --ssl-sni-hostname example.com

--override-host の値は、オリジンに送信される Host ヘッダーです。--ssl-cert-hostname と --ssl-sni-hostname は、オリジンの TLS 証明書に一致させる必要があります（通常は --address の値です）。これらの設定を逆にすると、503 エラーが発生します。

サービス一覧の完全性

サービスを列挙する場合（帯域幅統計の取得など）は、fastly service list --json を使用してください。 このコマンドは API のページネーションを内部で処理し、後の --page から明示的に開始しない限り、すべてのページを返します。 トラフィックがゼロのサービスも一覧に表示されるため、トラフィックゼロのサービスが省略される統計 API に頼らず、返されたすべてのサービス ID をループ処理してください。

新しい VCL サービスのセットアップワークフロー

新しい VCL キャッシュサービスを最初から最後まで立ち上げるには、次の手順を使用してください。各手順には検証ポイントがあります。

1. 事前確認 — オリジンが応答することを確認し、TLS 証明書の SAN を調べます：

   curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
   echo | openssl s_client -connect ORIGIN_ADDRESS:443 -servername ORIGIN_ADDRESS 2>/dev/null | \
     openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
   

   確認ポイント：オリジンが 200 を返し、バックエンドの ssl-cert-hostname が提示された証明書と一致していること。HTTPS の SNI／証明書の組み合わせで検証に成功せず、その Host を指定した HTTP では動作する場合は、--port 80 を使用するか、オリジンの証明書を修正してください。検証を無効にしてはいけません。

2. サービスを作成 — 出力に表示されるサービス ID を控えてください：

   fastly service create --name "my-service" --non-interactive
   

3. バージョン 1 にドメインとバックエンドを追加（新しいサービスでは --autoclone や --version latest を使用しないでください）：

   fastly service domain create --service-id $SID --version 1 \
     --name my-service.global.ssl.fastly.net
   
   fastly service backend create --service-id $SID --version 1 \
     --name origin --address ORIGIN_ADDRESS --port 443 --use-ssl \
     --override-host ORIGIN_ADDRESS \
     --ssl-cert-hostname ORIGIN_ADDRESS --ssl-sni-hostname ORIGIN_ADDRESS
   

4. 有効化前にバージョンを検証：

   fastly service version validate --service-id $SID --version 1
   

   確認ポイント：検証が成功し、ドメインまたはバックエンドの不足に関するエラーがないこと。

5. 有効化：

   fastly service version activate --service-id $SID --version 1
   

6. 反映を確認 — 15～30 秒待ってから、HEAD ではなく GET でテストします：

   curl -sS -D - -o /dev/null https://my-service.global.ssl.fastly.net/ | head -1
   

   確認ポイント：200 OK。500「Domain Not Found」が返る場合は、待ってから再試行してください（10～60 秒間は正常です）。503 が返る場合は、バックエンドの SSL 設定を確認してください。

高度なワークフロー（カスタムドメインでの TLS、Host ヘッダーのオーバーライド、稼働中のサービスの更新）については、services.md を参照してください。

トラブルシューティング

一覧については、troubleshooting.md を参照してください。主な注意点は上記で説明しています：SSL ホスト名のフラグ（Host ヘッダーのオーバーライドパターンを参照）、ブール型フラグとドメインの --name（一般的なフラグの使用例を参照）、--autoclone（主なパターンを参照）、トークンの安全な取り扱い（主なパターンを参照）。