vercel-cli

Vercel CLI スキル

Vercel CLI（vercel または vc）を使うと、コマンドラインから Vercel プラットフォーム上のプロジェクトをデプロイ、管理、開発できます。各コマンドのフラグの詳細については、vercel <command> --help を使用してください。

あまり知られていないフラグや新たに追加されたフラグについては、インストール済みの CLI のヘルプを正としてください。ここにあるコマンド例だけでは不十分な場合は、推測せず、実行する前に vercel <command> --help を確認してください。

URL と JSON の解析対象は stdout のみにしてください。警告、進行状況、--help の出力は stderr に出力されます。ヘルプテキストを検索する場合に限り、ストリームを結合してください。一部のヘルプコマンドは使い方を表示したあとに終了コード 2 を返すため、使い方が表示されていればヘルプの読み取りは成功したものとして扱ってください。

エージェント／非対話モードでは、多くのコマンドがエラーや必須の確認を、status、reason、hint、next（実行可能な後続コマンド）を含む単一の JSON オブジェクトとして stdout に出力します。提案された next コマンドを使う前に、それがユーザーの意図したターゲットと認可を維持することを確認してください。リンク、認証、変更を伴う後続処理は自動で実行しないでください。list、logs、inspect、api などの読み取りコマンドは、通常の出力形式を維持します。

重要：プロジェクトのリンク

プロジェクトのコンテキストは、コマンドの作業ディレクトリによって決まります。重要な読み取りや変更を行う前に、対象のディレクトリから vercel project inspect --non-interactive を実行し、報告されたオーナーとプロジェクトを確認してください。このコマンドは非対話モードでは既存のコンテキストのみを解決します。link_required が返された場合やターゲットが一致しない場合は、自動でリンクせずに中止してください。

プロジェクトを認識する多くのコマンドでは、明示的な1回限りのターゲットとして、--scope <team> とともに --project <name-or-id> も指定できます。使用する前に、そのターゲットとスコープがユーザーの意図を維持していることを確認してください。

• <cwd>/.vercel/project.json：vercel link によって作成されます。この作業ディレクトリにあるリンクは、リポジトリのリンクより優先されます。CLI は通常、任意のサブディレクトリから実行した場合に、ルートの project.json を引き継ぎません。
• <repo-root>/.vercel/repo.json：vercel link --repo によって作成されます。CLI は、作業ディレクトリを含むプロジェクトディレクトリのうち、最も深い階層のものを選択します。
• リポジトリ内で一致するパスがない場合：作業ディレクトリを含むリポジトリのマッピングがない場合、対話的なリポジトリ解決では、設定済みプロジェクトから選択するよう求められます。現時点で非対話的なリポジトリ解決は、設定済みプロジェクトが1つだけならそれを選択し、複数ある場合は未解決のままにします。その後、プロジェクトを設定するコマンドがリンク処理を開始することがあるため、非対話モードは一般にフェイルクローズではありません。

アプリのディレクトリ内にいることは、意図したプロジェクトが選択された証拠にはなりません。特に、リポジトリのマッピングがそのディレクトリを対象としていない場合は、解決されたプロジェクトを明示的に確認してください。

vercel whoami --format json は、認証済みユーザーと有効なチームを識別します。TTY ではない環境で vercel whoami を実行した場合、ユーザー名のみが出力されます。どちらのコマンドも、リンクされたプロジェクトは確認しません。読み取り専用のプロジェクトコマンドでも、ログインやチームの SAML 再認証が必要になり、ブラウザー／デバイスの認証フローが開くことがあります。続行する前に、そのフローをユーザー自身が明示的に完了するよう依頼してください。

クイックスタート

npm i -g vercel
vercel login
vercel link              # single project
# OR
vercel link --repo       # monorepo
vercel pull
vercel dev        # local development
vercel deploy     # preview deployment
vercel --prod     # production deployment

決定木

適切なリファレンスファイルを選ぶには、以下を使用してください。

• デプロイ、再デプロイ、強制ビルド、キャッシュなしビルド、またはデプロイのソース／来歴 → references/deployment.md
• ローリングリリース、デプロイフック、cron ジョブ、キャッシュ、Git 接続、Edge Config、リダイレクト、カスタム環境 → references/project-infra.md
• ローカル開発 → references/local-development.md
• 環境変数 → references/environment-variables.md
• CI/CD 自動化 → references/ci-automation.md
• ドメインまたは DNS → references/domains-and-dns.md
• プロジェクトまたはチーム → references/projects-and-teams.md
• Vercel Toolbar のコメント（vercel comments） → references/comments.md
• ビルド失敗、デプロイエラー、ログ、メトリクス、Speed Insights、Core Web Vitals、アクティビティ、パフォーマンス、プレビューへのアクセス、または本番環境のデバッグ → references/monitoring-and-debugging.md
• アラート、使用状況、契約、請求に関する購入、トークン、テレメトリー、または CLI のアップグレード → references/platform-ops.md
• Blob ストレージ → references/storage.md
• Container Registry（vercel vcr：リポジトリ、イメージ、タグ、docker／podman／buildah のログイン、プッシュ／プル） → references/container-registry.md
• インテグレーション（データベース、ストレージなど） → references/integrations.md
• コネクター（vercel connect） → references/connectors.md
• ルーティングルール → references/routing.md
• ファイアウォール（WAF ルール、IP ブロック、レート制限） → references/firewall.md
• プレビュー環境のデプロイへのアクセス → vercel curl を使用してください（references/monitoring-and-debugging.md を参照）
• CLI コマンドが利用できない、または出力に必要なフィールドがない場合 → まず専用の CLI パスが利用できない、または不十分であることを確認してから vercel api を使用してください（references/advanced.md を参照）
• Node.js バックエンド（Express、Hono など） → references/node-backends.md
• モノレポ（Turborepo、Nx、ワークスペース） → references/monorepos.md
• Bun ランタイム → references/bun.md
• フィーチャーフラグ（vercel flags：作成、調査、設定、分割、ロールアウト、ルール、セグメント、sdk-keys） → references/flags.md
• マイクロフロントエンド → references/microfrontends.md
• サンドボックス → references/sandbox.md
• エージェント、MCP、スキルの検出、または AI Gateway → references/agent-and-ai.md
• キャプチャしたリクエストトレース（vercel traces。--open／--view を含む） → references/advanced.md
• 高度な機能（vercel api によるフォールバック、ウェブフック） → references/advanced.md
• グローバルフラグ → references/global-options.md
• 初回セットアップ → references/getting-started.md

反パターン

• 複数のプロジェクトがあるモノレポで、誤ったリンク方法を使う：vercel link は、1 つのプロジェクトのみを追跡する project.json を作成します。代わりに vercel link --repo を使ってください。問題が発生したら、まず .vercel/ を確認してください。
• モノレポでコマンドに自動リンクさせる：多くのコマンドは、.vercel/ が存在しない場合に暗黙的に vercel link を実行します。これにより project.json が作成されますが、誤った設定になる可能性があります。まず vercel link（または --repo）を明示的に実行してください。
• アプリのサブディレクトリでプロジェクトが決まると思い込む：vercel project inspect --non-interactive で確認してください。現状、対話なしモードでは、リポジトリのパスに一致するものがない場合、設定済みの唯一のプロジェクトが選ばれることがあります。
• リンク済みプロジェクトの確認に vercel whoami を使う：vercel whoami --format json が返すのは認証情報とチームのコンテキストであり、選択中のプロジェクトではありません。
• CI を直接実行する際に、対話なしのフラグを付け忘れる：検出されたエージェントにはデフォルトで --non-interactive が付与されますが、通常の CI には付与されません。CI では明示的に指定し、確認が必要なコマンドに限って --yes を追加してください。
• vercel build の後に --prebuilt を付けずに vercel deploy を使う：ビルド出力は無視されます。
• キャッシュなしでビルドし直すために vercel redeploy を使う：vercel redeploy にはキャッシュなしのフラグがありません。ビルドキャッシュを保持せずに新しいデプロイを行う必要がある場合は、--with-cache を付けずに vercel deploy --force を使ってください。
• フラグにトークンをハードコードする：--token の代わりに VERCEL_TOKEN 環境変数を使ってください。
• デプロイ保護を無効にする：プレビューデプロイにアクセスするには、代わりに vercel curl を使ってください。
• 早い段階で vercel api を使う：必要なデータの取得や変更に対応する専用の CLI コマンドがある場合は、そちらを優先してください。