datocms-cli

DatoCMS CLI スキル

CLI コマンド、マイグレーション、ローカルプロジェクトの設定に使用します。

純粋なStructured Textの変換やローカルDASTの作業には、CLIのブートストラップの前に datocms-structured-text を使用してください：document model、editing、または conversion。プロジェクト操作が必要な場合のCLIの実行と認証は、引き続きここで行います。兄弟スキルの参照資料が見つからない場合は、datocms/agent-skills からそのスキルをインストールするか、バンドル全体を更新してください。通常のCLIコマンドでは、いずれも必要ありません。

ステップ 1：コンテキストを検出する

確立済みのCLIコンテキストを再利用します。ライブ読み取りやコンテンツ操作では、まず datocms-cma のルート選択に従ってください。現在動作しているリモートMCP接続を置き換えるためだけに、CLIをインストールしないでください。ユーザーがライブ作業にDatoCMS MCPを選択した場合は、ユーザーが明示的に切り替えるまで、ここで止めてその接続を使い続けてください。

選択したCLI実行に限り、ブートストラップを行います。コマンドの説明に接続は必要ありません。CLI固有のマイグレーション、リンク、プロファイル、インポート、型生成はここで行います。

検出（which datocms に依存しないでください。CLIは npx 経由で実行されます）

1. package.json の devDependencies に datocms がある → CLIを使用できます。選択したCLI実行に必要なのに見つからない場合は、インストールします（npm install --save-dev datocms）。
2. アクティブなプロファイルに siteId が設定された datocms.config.json がある → リンク済みです。未リンクでもプロファイルのトークン環境変数（デフォルトは DATOCMS_API_TOKEN。.env／.env.local も対象）が設定されている → トークン認証が機能するため、ログイン／projects:list／リンクはスキップします（リンクすると設定が上書きされます）。それ以外の場合は、以下のブートストラップを進めます。
3. npx datocms whoami が成功する → OAuthセッションがアクティブです。
4. migrations/ ディレクトリがある → マイグレーションはすでにスキャフォールディングされています。
5. tsconfig.json または migrations.tsconfig がある → TypeScriptマイグレーションの規約が使用されています。

ブートストラップのフロー（CLIは使用可能だが未リンクの場合）

datocms login のみターミナルが必要です。それ以外は非TTYで実行されます。

npx datocms login  # user, one-time, interactive
npx datocms projects:list [hint] --json # agent discovers siteId
npx datocms link --site-id=<ID> [--organization-id=<ID>] # agent links

datocms link を実行する前に、必ず対象プロジェクトをユーザーに確認してください。projects:list が候補を1つだけ返す場合も同様です。候補（名前、ID、組織）を提示し、明示的な承認を待ってください。「候補が1つだけ」であることを同意と見なしてはいけません。ユーザーは、このリポジトリに紐付けるつもりのないプロジェクトにもアクセスできる可能性があり、誤ったプロジェクトへのリンクを後から修正するのは困難です。

--site-id を指定しない datocms link はターミナルが必要です。現在は非TTYの場合、--site-id の指定を促して正常に終了します。--site-id なしで再試行しないでください。認証情報がない場合も同様に、まず datocms login を実行するようユーザーに依頼してください。

CLI作業では、スキーマに依存するコードや変更を行う前に、選択したプロジェクト／環境で npx datocms schema:inspect を使用してください（モデルとフィールドの呼び出しを手動で結合しないでください）。必要に応じて、モデルのAPIキー、ID、名前で絞り込んでください。references/schema-inspect.md を参照してください。

認証ポリシー

• 対話型CLI実行：login と link によるOAuthを使用します。このケースでは、ユーザーにトークンの貼り付けや、.env への DATOCMS_CMA_TOKEN=... の追加を求めないでください。
• 無人実行（CI、cron、サーバーサイドアプリ、OAuthセッションのない共有スクリプト）：環境変数でCMA対応トークンを使用します。読み取り専用のCDAトークン（DATOCMS_PUBLISHED_CONTENT_CDA_TOKEN、DATOCMS_DRAFT_CONTENT_CDA_TOKEN、NEXT_PUBLIC_DATOCMS_API_TOKEN）は機能しません。別途CMA対応トークンが必要であることを伝えてください。

ステップ 2：ワークフローを特定する

カテゴリが明らかだからといって、質問を省略しないでください。該当カテゴリに必要な重要な情報が依頼にすでに含まれている場合、またはリポジトリの調査で安全に確認できる場合に限り、追加の質問を省略してください。

実際のワークフローの判断を損なわないために必要な、最小限の的を絞った質問をしてください。

カテゴリ固有の入力情報は参照ファイルにあります

ステップ3で読み込む各カテゴリの参照資料には、冒頭に 「コマンド実行前に確認する入力情報」 のセクションがあります。これは、このステップにおけるカテゴリ別の確認事項に相当します。タスクのカテゴリに対応する参照資料の読み込みを省略しないでください。ここには、このステップが保護するワークフロー上の判断が含まれています。読み込みを省略すると、確認項目も省略することになります。

スキーマ変更 — ユーザーと方針を決める

依頼から行が明らかでない場合は、ユーザーに確認してください。どのツールで変更するかよりも、元に戻せるかどうかとワークフローの好みが重要です。

タスク	方針
破壊的なスキーマ変更：フィールド／モデルの削除、レコードの bulk_destroy、データを失う field_type の変更（例：string → json。保存済みの値を破棄する変更すべて）	まずフォークしたサンドボックスに対してマイグレーション（migrations:new）を実施します。ユーザーから明示的かつ繰り返し確認を得ない限り、プライマリには絶対に適用しないでください。
可逆的なスキーマ変更：フィールド／モデル／ブロックの追加、フィールド名の変更、required の切り替え、バリデーションの追加／強化、フィールドセットの並べ替え	「レビュー可能なマイグレーションにしますか、それともサンドボックスに直接変更を加えますか？」 と確認してください。どちらを担当するかは、最初に読み込まれたスキルではなく、回答によって決まります。リポジトリでマイグレーションを使用している場合や、ユーザーがセカンダリブランチにいる場合はマイグレーションを優先します。サンドボックスで手早く反復する場合は直接変更でも問題ありません。ユーザーに希望がなく、リポジトリにマイグレーションの慣習（migrations/ ディレクトリ、過去のマイグレーションコミット）が見られる場合に限り、マイグレーションをデフォルトにします。
明示的な単発の変更またはオプトアウト（「これだけ直して」「マイグレーションのワークフローなしで」「マイグレーションを作成しないで」）	直接変更を行います。変更が破壊的であると判明した場合を除き、マイグレーションを再提案しないでください。
コンテンツ操作：公開／非公開、個別レコードの削除、スラッグの修正、フィールド値の一括更新、アップロードの再タグ付け	マイグレーションは不要です。
コミットして環境間で再実行するコード	datocms-cma ではなく、マイグレーションを使用します。

破壊的変更＋マイグレーションの分岐では、ここで creating-migrations.md と running-migrations.md を読み込みます。単発の変更、コンテンツ操作、直接変更の分岐では datocms-cma を使用します。API 関連の作業は datocms-cma が担当し、実行方法（CLI の cma:call／cma:script、または MCP）を選びます。参照資料は自分で読み込んでください。ユーザーにたらい回しをしないでください。コマンドの仕組みはここで扱います。cma:call／cma:script／cma:docs のフラグ、標準入力とファイルモード、アンビエントグローバル、環境の指定（direct-cma-calls.md、cma-script.md）。チェックイン済みの buildClient() スクリプトと、無人実行のランタイムコード（CI、アプリサーバー、Webhook、長期稼働する自動化）には datocms-cma を使用します。

破壊的な変更と本番環境に影響する操作の確認

破壊的なスキーマ変更では、必ず次の確認を行ってください。以下の一覧には、スキーマ以外の破壊的なコマンドも含まれます。

コンテキストが不足している場合は、次のコマンドの最終的な実行コマンドを提案する前に、明示的な確認を求めてください。

• environments:destroy
• environments:promote
• 明らかに破棄可能ではないターゲットへのインポート
• プライマリに相当する環境での migrations:run --in-place（プライマリでの --in-place --allow-primary）
• maintenance:on --force
• environments:fork --fast --force
• destroy、bulk_destroy、または promote メソッドを指定した cma:call
• フォークしたサンドボックスでのマイグレーションではなく、プライマリに相当する環境を対象とする直接のスキーマ変更（cma:call または cma:script を使用）
• plugins:reset（ユーザーがインストールまたはリンクした CLI プラグインをすべて削除します）

ステップ 3：リファレンスを読み込む

タスクの分類に基づいて、このスキルファイルと同じディレクトリにある references/ から適切なリファレンスファイルを読み込みます。関連するものだけを読み込んでください。

セットアップまたは設定が必要な場合にのみ読み込みます：

• references/cli-setup.md — インストール、設定、プロファイル、グローバルフラグ、トークンの解決

カテゴリごとに読み込みます：

タスクカテゴリ	リファレンスファイル
マイグレーションの作成	references/creating-migrations.md
マイグレーションの実行	references/running-migrations.md
スキーマの生成	references/schema-generate.md
スキーマの調査	references/schema-inspect.md
CMA の直接呼び出しの仕組み	cma:call の場合は references/direct-cma-calls.md、cma:script の場合は references/cma-script.md、または両方
環境管理	references/environment-commands.md
デプロイのワークフロー	references/deployment-workflow.md
複数プロジェクトの同期	references/blueprint-sync.md
コンテンツのインポート	references/importing-content.md
CLI プラグインの管理	references/cli-plugin-management.md

リポジトリにコピーする同梱ヘルパー：scripts/（リリースおよび複数プロジェクト同期のラッパー）と assets/（それらの GitHub Actions ワークフロー）。コントラクトについては、deployment-workflow.md の「リリースヘルパー」と blueprint-sync.md の「自動化のガイダンス」を参照してください。

必要に応じて横断的なリファレンスも読み込みます：

• マイグレーションの作成と実行を組み合わせる場合は、creating-migrations.md と running-migrations.md の両方を読み込みます
• スキーマ生成の後に型付き CMA コードを変更する場合は、生成された型を利用するための datocms-cma のガイダンスも読み込みます
• CMA の直接呼び出しが単発のコマンドを超える規模になった場合は、再利用可能なコード向けに datocms-cma に切り替えます
• デプロイに環境コマンドが含まれる場合は、environment-commands.md も読み込みます
• 複数プロジェクトの同期でロールアウトを実行する場合は、running-migrations.md も読み込みます
• CLI プラグインを WordPress／Contentful のインポート専用にインストールする場合は、importing-content.md も読み込みます

ステップ 4：実装して検証する

選択したリファレンスを使って、コマンド構文、必要な入力、テンプレート、検証方法を確認します。リポジトリで使われているパッケージマネージャーのランナーを使用し、それがない場合は npx datocms を使用してください。

• migrations:new でマイグレーションをひな形から作成し、手作業でファイル名を付けないでください。リファレンスに記載された正確な関数シグネチャを使用し、関数本体で API を呼び出す場合は datocms-cma を読み込みます。
• マイグレーションでは --source を指定し、まずドライランを実行して、プライマリ環境への --in-place よりもフォークして実行する方法を優先してください。--force は明示的なオーバーライドとして扱います。
• 直接呼び出しでは、位置引数、標準入力、ファイルモードのいずれかを選ぶ前に direct-cma-calls.md または cma-script.md を読み込みます。ステップ 2 のスキーマ方式と環境認証の方針を維持してください。
• 実行前に、選択した認証方法、プロファイル、環境、出力先を確認します。既存の OAuth 認証または非対話型トークン認証を再利用し、両方を必須にしないでください。
• 要求された結果を検証し、実行した内容、確認した内容、未解決の入力を報告します。コマンド例では、不足している前提条件を、接続を行わずに明記してください。

スキル間のルーティング

このスキルでは、CLI コマンド、フラグ、設定、ワークフロー、マイグレーションファイルのひな形作成を扱います。次のいずれかに該当する場合は、対応するスキルを有効にしてください。

条件	振り分け先
スクリプトまたはマイグレーション内の DAST	datocms-structured-text。レコードの永続化には datocms-cma
マイグレーションスクリプトの本文内での CMA API 呼び出し（レコード、スキーマ、アップロード）	datocms-cma
コード内での client.environments.* によるプログラムからの環境管理	datocms-cma
アプリケーションコードまたは再利用可能なスクリプト内での、生成されたスキーマ型の使用	datocms-cma
フロントエンド表示向けの GraphQL によるコンテンツのクエリ	datocms-cda
フレームワーク連携、ドラフトモード、リアルタイム更新のセットアップ	datocms-frontend-integrations
DatoCMS プラグインの構築	datocms-plugin
セットアップの計画や手順の案内を希望している（マイグレーションとリリース、複数プロジェクト間の同期、プロジェクトへのインポート）	datocms-setup