dd-account-setup

Datadog アカウントを作成／接続する

このスキルでは、ユーザーを正常な状態に導きます。**有効な API キーとアプリケーションキーがあり、適切なリージョンが設定され、Datadog API による検証が済んでいる状態です。**セットアップ／インストルメンテーションスキルが前提とする「ステップ 0」です。最初に実行してから、次のスキルに引き継いでください。

これは、単独で完結するガイド付きフローです。すでに存在するものを検出し、利用できるものが見つからない場合は、OAuth（ブラウザー、PKCE と state）でサインインするか、新しいアカウントを作成します（ターミナル内で、生成したパスワードを .env に保存）。その後、そのセッションを API キーに変換します。すべての処理は、小さな インラインの bash + curl コマンドで実行します（OAuth では openssl も使用します）。同梱スクリプトや node は不要です。クロスプラットフォームに対応しています（macOS、Linux、WSL／Git Bash 経由の Windows）。

この SKILL.md が全体の骨格です。短い手順をインラインで説明し、各手順の詳しい処理は references/ に案内します。参照ファイルは、そのファイル名が示されている手順に到達したときだけ読んでください。

フローの概要

headless requested?  ──yes──▶  Step H: env keys only (OAuth needs a browser), validate, done
   │no (default — interactive)
   ▼
Step 1  Detect existing credentials (env)
   │
   ▼
Step 2  Determine region / site  (DD_SITE → validate; else ask → user picks, default US1)
   │
   ▼
Step 3  Authenticate  — ask first (even if env keys were detected)   → references/authenticate.md
   │        └─ ASK: how to connect? ↴
   │            ├─ A. Use the detected env key (only if one exists) → validate → Step 5
   │            ├─ B. Sign in (I have an account) → OAuth (browser, PKCE + state) ──▶ Bearer token
   │            └─ C. Create a new account → Path C: auto in-terminal signup, generated password ──▶ then OAuth
   ▼
Step 4  Turn the OAuth session into an API key   → references/get-api-key.md
   │        (identity + region via /current_user; OAuth→retrieve most-recent key, app-key→create → write straight to .env; else guide to UI key page)
   ▼
Step 5  Load creds from .env, validate, hand off

**絶対に守るルール：API キー、アプリキー、トークン、サイトを推測したり、捏造したりしないでください。**環境内に設定されている値を読み取り、検証してください。設定されていない場合は認証を行い、憶測で処理を進めないでください。

表示と表現の規約 — ステップ 1 の前に一度読む

すべてのステップで、ユーザーへの説明と進捗表示には同じルールを適用します。ステータス行をすっきりと表示するための規約、ホストネイティブのセレクターを使って尋ねること（文字入力で選択させない）、マーカーの規律に従ったライブ進捗チェックリストです。これらは references/conventions.md に記載されています。ステップ 1 の前に読み、以降のすべてのステップで適用してください。以下の各ステップの末尾には、切り替える項目を示す ↳ Checklist: の案内があります。

---

ステップ 0 — 事前確認（準備状況ボード）

ユーザーが処理開始前に全体の流れを把握できるよう、最初に一度だけ実行してください。利用可能なツール、すでに検出されているもの、フローで行うこと（ブラウザーを一度開くことを含む）を表示します。何も書き込まず、秘密情報も表示しません。実行するたびにステップ 1 からフロー全体を実行します。途中から再開したり、先のステップに進んだりすることはできません。前回の実行結果も再利用されません。

DDLOG="${TMPDIR:-/tmp}/dd-onboard-$(id -u).log"; : >"$DDLOG"   # fresh log for this run
mark(){ command -v "$1" >/dev/null 2>&1 && echo "✓" || echo "$2"; }
# python3 gates the auto browser-callback; fall back to python only if it's a real py3.
have_py3(){ command -v python3 >/dev/null 2>&1 && return 0; command -v python >/dev/null 2>&1 && python -c 'import sys;exit(0 if sys.version_info[0]==3 else 1)' 2>/dev/null; }
py3msg(){ have_py3 && echo '✓ (auto browser-callback)' || echo '⊘ (will paste the redirect URL)'; }
echo   "Datadog account setup — preflight"
echo   "  deps (required):  bash ✓   curl $(mark curl ✗)   openssl $(mark openssl ✗)"
echo   "  deps (optional):  python3 $(py3msg)   browser-open $( { command -v open >/dev/null 2>&1 || command -v xdg-open >/dev/null 2>&1; } && echo ✓ || echo '⊘ (open URL manually)')"
# Canonical DD_* loader — this same block is repeated verbatim in later steps because each ```bash runs a fresh shell (not drift).
# Load DD_* with precedence: shell env > .env.local > .env. A real env var is never overwritten; surrounding quotes are stripped. *_SRC records where each came from (unset ⇒ from the shell env).
for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && { export "$k=$v"; eval "${k}_SRC=$f"; }; done; done
echo   "  detected creds:   DD_SITE=${DD_SITE:-<unset>}${DD_SITE_SRC:+ [$DD_SITE_SRC]}   DD_API_KEY=$([ -n "$DD_API_KEY" ] && echo "set …${DD_API_KEY: -4}${DD_API_KEY_SRC:+ [$DD_API_KEY_SRC]}" || echo '<unset>')   DD_APP_KEY=$([ -n "$DD_APP_KEY" ] && echo "set${DD_APP_KEY_SRC:+ [$DD_APP_KEY_SRC]}" || echo '<unset>')"
echo   "  what happens:     confirm region → authenticate (opens your browser once) → get an API key → write it to .env → validate. ~2 min, one browser approval."
[ "$(mark curl ✗)" = ✗ ] || [ "$(mark openssl ✗)" = ✗ ] && echo "  ✗ missing a required dep above — install it before continuing."

ボードは、すでに整った表示になっているため、そのままユーザーに読み上げてください。必須の依存関係が不足している場合は停止し、その旨を伝えてください。その後、チェックリストのステップ 1 にチェックを付けて次へ進みます。必ずステップ 1 に進み、後のステップに飛ばないでください。

↳ Checklist: ボードを表示してからチェックリストを表示し、1. 認証情報を検出 ◔ とします。

---

ステップ H — ヘッドレス／非対話型（ブラウザーなし、プロンプトなし）

人間がいないとブラウザーを使うフローもサインアップのフローも実行できないため、まずこれを判断します。環境ではなく、スキルの呼び出し方からヘッドレスかどうかを推定してください。判定条件はユーザーの依頼そのものです。たとえば「Datadog を非対話形式でセットアップして」「CI で実行するので、ブラウザーは使えない」のように、ブラウザーを使わないことや対話型プロンプトを使わないことを明示している場合です。

TTY がないという理由だけで、ヘッドレスだと推定しないでください。通常のターミナル実行では、必ず対話型フローを使います。明示的な依頼があった場合に限り、対話型フローを無効にします。

ヘッドレスでの実行を求められていると判断した場合は、以下のブロックを実行してください。それ以外の場合は実行しないでください。OAuth ではブラウザーが必要で、サインアップのプロンプトには人が応答する必要があります。そのため、有効な状態にする方法は、すでにキーが提供されている場合に限られます。DD_API_KEY、DD_APP_KEY、DD_SITE がすべて設定されていることを必須とし、それ以外の場合は速やかに失敗させてください。

# Run this block ONLY when you inferred a non-interactive request. It enforces the one thing
# headless needs — keys already present — and fails fast when any are missing.
# Load DD_* (env > .env.local > .env), same precedence as Step 1 — CI keys often live in .env, not exported.
for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
missing=""
[ -z "$DD_API_KEY" ] && missing="$missing DD_API_KEY"
[ -z "$DD_APP_KEY" ] && missing="$missing DD_APP_KEY"
[ -z "$DD_SITE" ]    && missing="$missing DD_SITE"
[ -n "$missing" ] && { echo "Non-interactive mode requires:$missing — set them and re-run. Sign-in and trial signup need a browser."; exit 1; }

3 つすべてが設定されている場合は、ステップ 5 に進みます。ここで /api/v1/validate を使ってキーを検証します（DD-API-KEY ヘッダーで動作します）。注意：/api/v1/validate が確認するのは DD_API_KEY のみです。DD_APP_KEY は必須ですが、ここでは個別に検証されません。誤った、または期限切れのアプリキーは、後でアプリキーを必要とする最初の呼び出し時に判明します。ヘッドレスの場合、OAuth やサインアップへのフォールバックはありません。どちらもブラウザーが必要です。そのため、上記のメッセージを表示して失敗させ、ログから問題を特定できるようにしてください。

↳ Checklist (headless): 項目は 2 つだけです。検証に通ったら両方にチェックを付け、ステップ 5 に進んでください。

---

Step 1 — 既存の認証情報を検出する

環境変数と、プロジェクトの .env／.env.local ファイルを読み取ります。値をそのままユーザーに表示せず、マスクしてください。

# Load DD_* with precedence: shell env > .env.local > .env (real env var wins; quotes stripped). *_SRC = file it came from (unset ⇒ shell env).
for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && { export "$k=$v"; eval "${k}_SRC=$f"; }; done; done
echo "DD_SITE   = ${DD_SITE:-<unset>}${DD_SITE_SRC:+ (from $DD_SITE_SRC)}"
echo "DD_API_KEY= $( [ -n "$DD_API_KEY" ] && echo "set (…${DD_API_KEY: -4})${DD_API_KEY_SRC:+ (from $DD_API_KEY_SRC)}" || echo "<unset>" )"
echo "DD_APP_KEY= $( [ -n "$DD_APP_KEY" ] && echo "set (…${DD_APP_KEY: -4})${DD_APP_KEY_SRC:+ (from $DD_APP_KEY_SRC)}" || echo "<unset>" )"

• DD_API_KEY が存在する（環境変数または .env／.env.local）場合 → Step 2（サイトを固定する）に進み、その後 Step 3 に進んで確認します（選択肢 A＝検出されたキーを使用する、または認証する／別のアカウントを作成する B／C）。検出されたキーは、Step 3 でユーザーが確認して選べる選択肢であり、黙ってデフォルトで使用するものではありません。別の組織やアカウントを希望する場合があります。
• DD_API_KEY がどこにも存在しない場合 → ユーザーはまだ使用できるキーを持っていません。それでも Step 2 を実行し（登録時に正しいリージョンが表示されるようにするため）、その後 Step 3 に進み、接続方法を尋ねます。

API キーがなくアプリケーションキーだけでは不十分です。「キーなし」として扱ってください。シェルはブロック間で状態を保持しないため、後続のブロックで $DD_API_KEY を使用する場合は、先頭でこのローダーを再実行します。そのため、Path A、Step 4、Step 5 で再度表示されます。

↳ チェックリスト： 今すぐリストを投稿し、1. 認証情報を検出にチェックを入れ、2. リージョンを確認に ◔ を付けます。

---

Step 2 — リージョン／サイトを決定する

サイトによって、後続のすべての URL（登録、API ホスト、キーのページ）が決まるため、検証の前に固定します。 リージョンの表は references/regions.md にあります。

1. DD_SITE が設定されている場合（環境変数または .env）：references/regions.md の許可されたサイトの一覧と照合して検証します。一覧にない場合は停止し、わかりやすいエラーを表示します。

   DD_SITE="<value>" は認識されている Datadog サイトではありません。references/regions.md にあるリージョンから選び、それに応じて DD_SITE を設定してください。

2. DD_SITE が設定されていない場合： references/regions.md の表からリージョンを選ぶようユーザーに尋ねます。黙って決めないでください。ユーザーの所在地を検出しようとしないでください（IP ジオロケーションの検索や、その他のサードパーティへの呼び出しは禁止です）。適切なリージョンはユーザーのいる場所ではなく、インフラストラクチャが稼働している場所だからです。希望がない場合は US1（datadoghq.com）をデフォルトにします。たとえば、次のようにユーザーに伝えます。

   このアカウントをどの Datadog リージョンに配置しますか？インフラストラクチャ（たとえば、クラウドリージョン）が稼働している場所に最も近いリージョンを選んでください。遠くのリージョンにデータを送信すると、レイテンシとエグレスコストが増加し、アカウント作成後にリージョンを変更することはできません。デフォルト：US1（バージニア州）、datadoghq.com。

   ホストのネイティブセレクターを使い、最初に **US1（デフォルト）**を提示します。選択肢の数に上限がある場合は、上限まで次の順序で表示します — US1、EU1、AP1、UK1 — 残りはセレクターの自由入力欄「Other」で選べるようにします。

   続行する前にユーザーの返信を待ちます。「ok」「default」「sure」など、単に了承する返答は US1 を意味します。

API ホストは一律 https://api.${DD_SITE} です。

↳ チェックリスト： ユーザーがリージョンを確認したら、2. リージョンを確認にチェックを入れ、3. 認証に ◔ を付けます。

---

Step 3 — 認証

まず接続方法を尋ねてください。Step 1 で環境変数の認証情報が検出されている場合も同様です。その後、ユーザーが選んだ方法を実行します。認証情報に触れる前に「選択肢」を提示してください。環境変数の DD_API_KEY は、ユーザーが意図する組織やアカウントとは異なるものに属している場合があり、リージョンからはそれを判別できないため、推測せずにユーザー自身に選んでもらいます。（ヘッドレスのStep Hは例外です。質問に使える TTY がないため、環境変数のキーのみを使用します。）

詳細な手順、「選択肢」のネイティブセレクターでの文言、および3つのすべての方法は references/authenticate.md にあります。

ユーザーの選択	方法	内容
既存の認証情報を使用する (Step 1 でキーが検出された場合のみ提示)	A	検出されたキーを検証します（誤ったリージョンのキーも検出し、Step 2 に戻ります）。
サインイン — すでにアカウントを持っています	B	ブラウザーで OAuth（PKCE + state）を行い、Bearer トークンを 0600 のファイルに保存します。
新しいアカウントを作成する (デフォルト)	C	生成したパスワードを使ってターミナル内で自動的にサインアップし、その後、方法 B を実行します。

references/authenticate.md を読み、ホストのネイティブセレクターで選択肢を提示して、対応する方法を実行します。方法が行き詰まった場合は、選択肢を再提示してください（OAuth でアカウントが見つからない場合は C。誤ったリージョンのキーが原因で Step 2 に戻った場合は、その後に再提示します）。

↳ チェックリスト： トークンまたはキーを実際に取得するまで 3. Authenticate は ◔ のままにします（各方法の目安は references/authenticate.md を参照）。

---

Step 4 — OAuth セッションを API キーに変換する

OAuth トークンでユーザーを認証できますが、後続の計装には DD_API_KEY が必要です。Bearer トークンで本人確認を行ってからキーを取得します。OAuth セッションでは組織の最新のキーを取得します（OAuth トークンではキーを作成できません）。アプリキーで認証する場合はキーを作成します。いずれもできない場合は、UI のキーのページを案内します。

詳細な分岐（本人確認、取得と作成の使い分け、HTTP コード付きのブロック、および EMPTY_ORG／LIST_DENIED／SECRET_DENIED／CREATE_DENIED／TRANSPORT_ERROR の結果テーブル）は references/get-api-key.md にあります。これに従ってください。シークレットは .env に直接書き込み、画面には出力しません。

↳ チェックリスト： 検証済みのキーを取得したら、4. Get & validate an API key にチェックを付け、5 を ◔ にします。

---

Step 5 — 確認して引き継ぐ

キーはすでに .env にあります。読み込んで検証します（呼び出しごとに新しいシェルを使用し、毎回まず .env を解析して読み込みます。source は使用しません。細工された .env が実行されるのを防ぐためです。また、キーの値を直接コマンドに埋め込んではいけません）。

DDLOG="${TMPDIR:-/tmp}/dd-onboard-$(id -u).log"; tf="${TMPDIR:-/tmp}/dd-oauth-$(id -u).token"
# Load DD_* (env > .env.local > .env) — parse, don't source, so a crafted .env can't execute. Covers a Path-A key that lives only in the shell env or .env.local.
for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
vcode=$(curl -sg -o "$DDLOG" -w '%{http_code}' -H "DD-API-KEY: $DD_API_KEY" "https://api.${DD_SITE}/api/v1/validate")
# re-derive org/email for the card (fresh shell — Step 4 vars don't persist); only if a token is still around
who=""; [ -s "$tf" ] && who=$(curl -sg -H "Authorization: Bearer $(cat "$tf")" "https://api.${DD_SITE}/api/v2/current_user" 2>>"$DDLOG" | grep -oE '"email"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | cut -d'"' -f4)
cmk="${TMPDIR:-/tmp}/dd-signup-$(id -u).created"; spw=""   # marker exists only if THIS run created the account (Path C, C3) — no stale password from an earlier run
[ -f "$cmk" ] && spw=$(grep -E '^DD_SIGNUP_PASSWORD=' .env 2>/dev/null | tail -1 | cut -d= -f2-)   # newest .env entry = the password this run generated (C2 appends to .env)
# consistent 🔑 credential card — the one place credential state is summarized; secret shown only as last4
echo "🔑 Datadog credential"
[ -n "$who" ] && echo "   org:     $who"
echo "   region:  ${DD_SITE}"
echo "   api key: …${DD_API_KEY: -4}  (in .env — never printed in full)"
[ -n "$spw" ] && echo "   password: in .env as DD_SIGNUP_PASSWORD (ends …${spw: -4}) — you need it to sign in to Datadog"
echo "   status:  $([ "$vcode" = 200 ] && echo '✓ validated (HTTP 200)' || echo "✗ validate HTTP $vcode — see: tail -n 30 \"$DDLOG\"")"

• 上記のカードが正式な概要です。検証レスポンスの生データも出力しないでください。200 以外の場合は tail -n 30 "$DDLOG" を提示し、結果テーブルに従って処理します（ここでの 403 は通常、リージョンの誤りを示すため Step 2 に戻ります）。
• 本人確認の呼び出しで確認した認証済みの組織／メールアドレスを報告します。
• 認証情報はすべて .env（DD_SITE、DD_API_KEY、および Path C でアカウントを作成した場合は DD_SIGNUP_PASSWORD）に保存されます。ここへ直接書き込み、画面には出力しません。サインアップ用の一時ファイルと OAuth の state ファイルおよび callback ファイルを削除します：rm -f "${TMPDIR:-/tmp}"/dd-signup-$(id -u).* "${TMPDIR:-/tmp}"/dd-oauth-$(id -u).state "${TMPDIR:-/tmp}"/dd-oauth-$(id -u).cb。
• 後続処理への引き継ぎ — OAuth トークンは保持してください。 ${TMPDIR:-/tmp}/dd-oauth-$(id -u).token（0600）はそのまま残します。後続の計装ではこの Bearer トークンを再利用して、通常の API キーでは作成できないリソース（特に RUM アプリケーション）をプロビジョニングします。有効期間とスコープは限定されています。セットアップが完了したら、オンボーディングを呼び出した側（例：オーケストレーター）が削除します（rm -f "${TMPDIR:-/tmp}"/dd-oauth-$(id -u).token）。計装を単独で実行する場合は、完了後に自分で削除してください。
• 次のように伝えます：「アカウントの準備ができました。これでセットアップ／計装のステップを実行できます。」（例：studio-setup、browser-rum-setup、llm-observability-setup、またはその他の *-setup スキル）。

↳ チェックリスト： 5. Ready — hand off にチェックを付け、完了した項目をすべて表示して、フローが完了したことがユーザーに分かるようにします。

---

トラブルシューティングとリファレンス

手順が失敗した場合は、references/troubleshooting.md を参照してください。症状と対処法の表（リージョンの誤り、OAuth の状態の不一致、ヘッドレスでの終了、Path-C の登録エラーなど）に加え、設計上の決定事項と一時状態に関する注意事項が記載されています。