CLI リファレンス

vantage の全コマンド。dev・build・preview・check・routes・add・docs・search・doctor・upgrade。

vantage はアプリ作者が使う唯一の CLI です。特記がなければプロジェクトルートで実行します。

コマンド一覧

コマンド	役割
`vantage dev`	開発サーバー（HMR + オプションの API）。既定 `:5173`
`vantage build`	クライアント + オプションのサーバーをビルド → `dist/`
`vantage preview`	本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー）
`vantage check`	静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1
`vantage routes`	ページ + API の URL マップを表示（`--pages` / `--apis` で片側だけ、`--detail` で仕様つき）
`vantage add <kind> <name>`	`page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定）
`vantage docs [name]`	同梱のガイド + コンポーネントリファレンスを表示
`vantage search <query>`	同じリファレンスを全文検索（自然言語 or `--regex`）
`vantage doctor`	環境・インストールの健全性を診断
`vantage upgrade`	生成成果物を再生成し、配置済みの `AGENTS.md` を正本から同期

クイックモード（パスを直接渡す）

cd してからコマンドを打つ代わりに、プロジェクトのパスを直接渡して起動できます。第 1 引数が既知コマンドではなくファイルシステム上のパスを指す場合、そのパスを root として dev を起動します（ターミナルに quick dev → <path> と表示されます）。

vantage ./demo                 # ディレクトリ → その中で dev を起動
vantage ./demo/index.tsx       # ページファイル → その `package.json` があるディレクトリで dev
vantage ./demo/src/index.tsx   # src/ レイアウトでも同じ（root は ./demo）

パスの解決ルール:

渡したパス	root になるもの
ディレクトリ	そのディレクトリ自身
`.tsx` / `.jsx` のページファイル	そこから上に辿って最初に `package.json` があるディレクトリ（無ければ親ディレクトリ）
存在しないパス・その他	該当なし（`Unknown command` エラー）

add・docs・search を除く root スコープの各コマンドも、末尾に path positional を取れます。dev を明示してもよいですし、build / check / routes などにも同じパスを渡せます。

vantage dev ./demo             # 明示的なクイック dev
vantage build ./demo           # ./demo をビルド
vantage check ./demo/index.tsx # ファイル指定でも親ディレクトリを検査

`vantage routes` — URL マップと仕様

引数なしで、ページ・レイアウト・API の URL マップを出します。フラグで片側だけに絞ったり、各ルートの静的な仕様を足したりできます。

フラグ	意味
`--pages`	ページ（+ layout / 404 / error）だけを表示
`--apis`	API ルートだけを表示
`--detail`	各ルートの仕様を併記（ページはパスパラメータと `definePage` のメタ、API はメソッド・リクエスト・レスポンス）
`--json`	機械可読出力（`--detail` を付けると各要素に `spec` が付く）

--pages と --apis は排他ではありません。両方付けても、どちらも付けなくても全部出ます。

vantage routes --pages           # ページだけ
vantage routes --apis --detail   # API を仕様つきで
vantage routes --detail --json   # 仕様つきの機械可読出力

Pages
  /sales/:customerId           sales/[customerId].tsx
      title    Customer detail
      params   :customerId

API
  /api/customers/:id           server/api/customers/[id].ts
      GET
        path     :id
        response 200 application/json
        error    404 "Customer ${params.id} not found"

--detail が拾うのは次の書き方です。

行	何を読むか
`title` / `nav` / `desc`	`definePage({ ... })` の文字列リテラル
`params`	ファイル名の `[id]` / `[...rest]`
メソッド	`export function GET` などの HTTP メソッド export
`query`	`searchParams.get/getAll/has("x")`
`body`	`request.json()` / `formData()` / `text()`（`const { a, b } = await request.json()` ならキーも）
`response`	`Response.json(…)` / `json(…)` / `new Response(…)` の status・content-type・オブジェクトリテラルのキー
`error`	`new HttpError(status, "message")`

`vantage docs` — ドキュメントを CLI で読む

このサイトの内容はパッケージに同梱されていて、vantage docs でそのまま読めます。ネット接続もブラウザも不要なので、コーディングエージェントが props を確かめるのに向いています。

vantage docs                    # 全ページの一覧（ガイド + コンポーネント）
vantage docs button             # 1 ページ表示（短縮名 → ui/button に解決）
vantage docs parts/data-table   # 完全な slug でも引ける
vantage docs --all              # 全ページを連結して出力

フラグ	意味
`--list`	ページ名を表示するだけ（本文を出さない）
`--all`	全ページを連結して出力
`--json`	機械可読出力（`{ slug, title, description, section, content }`）
`--lang <ja\|en>`	言語（既定 `ja`）

引数なしの vantage docs は、セクションごとに slug と説明を並べます（左の列がそのまま引数になります）。

$ vantage docs

ガイド
  index                       設定ファイル不要（config-free）な React ダッシュボードフレームワーク。書くのは index.tsx だけ。
  getting-started             インストールから最初の Vantage アプリを起動するまで。
  routing                     ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
  …

@squadbase/vantage/ui
  ui/accordion                開閉する見出しの縦積み。既定では 1 つだけ開く。
  ui/alert                    ページ内に置く通知。中身は表示したまま注意を促す。
  ui/badge                    小さなラベル。件数・状態・タグに。
  …

vantage docs <name>   show one page      --json   machine-readable
vantage docs --all    show every page    --lang   ja | en

名前を渡すと、そのページを Markdown のまま出力します（TTY では見出しと引用が色付けされ、パイプすると素の Markdown になります）。props の表は Markdown の表として読めます。

$ vantage docs button

# Button

> 6 つの variant と 8 つの size を持つボタン。

いちばんよく使うコンポーネントです。`variant` で意味づけを、`size` で大きさを決めます。

```tsx
import { Button, buttonVariants } from "@squadbase/vantage/ui";
```

| Prop | Type | Default | 説明 |
| --- | --- | --- | --- |
| `variant` | `"default" \| "secondary" \| …` | `"default"` | 見た目と意味づけ。 |
| `size` | `"default" \| "xs" \| "sm" \| …` | `"default"` | 高さと余白。`icon` 系は正方形になる。 |
| `render` | `ReactElement` |  | 別の要素として描画する（Radix の `asChild` に相当）。 |
…

名前は短縮形で引けます。vantage docs button は ui/button に、vantage docs data-table は parts/data-table に解決されます。曖昧なとき・見つからないときは候補が出て、終了コードは 1 になります。

$ vantage docs sele
✗ No page named "sele". Did you mean: ui/select, parts/multi-select, parts/searchable-select?

--json は 1 ページを機械可読にしたものです。content にページ全体の Markdown が入ります。

{
  "slug": "ui/badge",
  "lang": "ja",
  "title": "Badge",
  "description": "小さなラベル。件数・状態・タグに。",
  "section": "components/ui",
  "sectionTitle": "@squadbase/vantage/ui",
  "content": "# Badge\n\n> 小さなラベル。件数・状態・タグに。\n\nテキストの横に添える…"
}

本文中のリンクは slug なので、[DataTable](parts/data-table) は vantage docs parts/data-table で開けます。

`vantage search` — 名前を知らなくても辿り着く

vantage docs <name> は名前を知っている前提の参照です。「日付範囲を選ぶ UI が欲しい」のように やりたいことから辿るときは vantage search を使います。対象は vantage docs と同じ同梱ドキュメント（ガイド + ui / parts / markdown のコンポーネント）で、結果はそのまま vantage docs <name> に渡せます。

vantage search 期間を選ぶ UI が欲しい   # 自然言語（クエリは引用符なしでもよい）
vantage search "pagination"            # 英語のドキュメントを引くなら --lang en
vantage search "enable[A-Z]\w+" --regex  # 正規表現で props を横断検索
vantage search チャート --limit 3 --json # 機械可読

フラグ	意味
`--regex`	クエリを正規表現として扱う（大文字小文字は区別しない）
`--limit <n>`	表示件数（既定 `10`）
`--json`	機械可読出力
`--lang <ja\|en>`	言語（既定 `ja`）

既定は BM25 による全文検索です。ページ名・タイトル・説明文を本文より重く見て並べ、ヒットしたページごとに一致した箇所のスニペットを表示します。日本語は字種の切れ目（漢字・カタカナ・ひらがな）で区切って索引を作るので、「テーブルにページングを付けたい」のような文のままのクエリでも引けます。

$ vantage search 期間を選ぶ UI が欲しい --limit 3

  parts/date-range-picker  DateRangePicker · @squadbase/vantage/components
                           > プリセット付きの期間選択。
  ui/calendar              Calendar · @squadbase/vantage/ui
                           単日・複数日・期間を選べるカレンダーです。ダッシュボードで期間を選ばせたい場合は、これを直接
  ui/accordion             Accordion · @squadbase/vantage/ui
                           常に開いている単独の折りたたみが欲しいだけなら

左の列がそのまま vantage docs <name> に渡せる slug、右がタイトルと import 元、その下が一致箇所のスニペットです。実際にはこの前後に 55 results for "…" ja · bm25 の見出しと、--limit で隠れた件数・フラグのヒントが付きます（上の例では省略）。件数は索引に 1 語でも一致したページの数なので、下位はほとんど関係ありません。上から数件だけを見て、足りなければ --limit を上げてください。

--json は同じ結果を機械可読にしたものです。score は BM25 のスコア、command はそのまま実行できる形です（以下は vantage search 期間選択 --limit 1 --json の出力）。

{
  "query": "期間選択",
  "mode": "bm25",
  "lang": "ja",
  "count": 14,
  "results": [
    {
      "slug": "parts/date-range-picker",
      "title": "DateRangePicker",
      "description": "プリセット付きの期間選択。",
      "section": "components/parts",
      "sectionTitle": "@squadbase/vantage/components",
      "command": "vantage docs parts/date-range-picker",
      "score": 18.033,
      "snippet": "> プリセット付きの期間選択。"
    }
  ]
}

--regex は名前・タイトル・説明・本文を正規表現で走査し、行番号付きで一致行を出します。props の綴りを横断で確かめたいときに向いています。

$ vantage search "enable(Sorting|Filtering)" --regex

  parts/data-table  DataTable  4 matches
      30  | `enableSorting` | `boolean` | ヘッダークリックで並べ替える。 |
      31  | `enableFiltering` | `boolean` | ツールバーに検索欄を出す。 |
      49  <DataTable columns={columns} data={data} enableSorting enableFiltering>

1 ページにつき最初の 3 行までを表示しますが、4 matches の件数は正確です。名前・タイトル・説明だけが一致したページは name match と表示され、本文の行は出ません。ヒットが 0 件でもエラーにはならず（終了コード 0、--json なら "count": 0）、不正な正規表現のときだけ終了コード 1 になります。

`--json`

check / routes / doctor / build / upgrade / docs / search は --json を受け付けます。CI やエージェントの自動処理に使えます。

vantage check --json

{
  "code": "ROUTE_CONFLICT",
  "severity": "error",
  "message": "2 files resolve to /sales",
  "files": ["sales.tsx", "sales/index.tsx"],
  "fix": "Rename or remove one route file so each route is unique."
}

`build --api-base-url`

vantage build は、クライアントが /api を呼ぶベースURLを指定する --api-base-url を受け付けます。フロントとサーバーを別オリジンにデプロイするときに使います。

vantage build --api-base-url https://api.example.com

このフラグは .env の PUBLIC_API_BASE_URL より優先されます。未指定なら空(同一オリジンの相対パス)。詳細はビルドとデプロイを参照してください。

`--port` — dev / preview のポート

vantage dev(既定 :5173)と vantage preview(既定 :4173)は --port を受け付けます。

vantage dev --port 3000
vantage preview --port 8080

--port を明示したときは、そのポートが取れなければ起動せずエラーで終了します(exit 1)。 --port 3000 と書くのは、リバースプロキシ・コンテナのポートマッピング・OAuth のリダイレクト URI などプロセスの外側との約束があるからで、黙って 3001 で上がるのは復旧ではなく静かな失敗だからです (「3000 で誰かが listen しているか」だけを見る監視は、誰も到達できないサーバーを “起動成功” と報告してしまいます)。

--port を省いたときは既定ポートが埋まっていれば次の空きポートへ自動でずれます。複数のプロジェクトを同時に立ち上げるのに手間はかかりません。この既定は 2 つのフラグで上書きできます。

フラグ	意味
`--strict-port`	`--port` を省いたときも、既定ポートが取れなければエラーで終了する
`--no-strict-port`	`--port` を明示したときも、埋まっていれば次の空きポートへずらす

vantage dev --port 3000 --no-strict-port   # 3000 が埋まっていれば 3001 で上がる
vantage dev --strict-port                  # 5173 が取れなければ起動しない

dev のブラウザ出力 — 転送とオーバーレイ

vantage dev は、ブラウザ側で起きたことを開発ターミナルへ転送します。既定で転送するのは console.warn / console.error と、未捕捉のエラー / Promise リジェクションです。

1:46:34 PM [vite] (client) [console.warn] rows is empty
1:46:34 PM [vite] (client) [Unhandled error] TypeError: rows.map is not a function
 > src/sales/index.tsx:12:18
    11 |    const rows = data?.rows
    12 |    return <ul>{rows.map((r) => <li key={r.id}>{r.name}</li>)}</ul>
       |                     ^

未捕捉のエラーはソースマップを解決したうえで、該当行のコードフレーム付きで出ます。ブラウザの DevTools を開かなくても、多くの不具合はターミナルだけで追えます（設定は不要で、無効化するオプションもありません）。

console.log / console.info は転送しません。描画のたびに走るログでサーバー自身の出力が埋もれてしまうためです。ターミナルに出したい情報は console.warn で出してください。

エラーが起きたときにブラウザへ出る全画面のオーバーレイは --no-overlay で消せます。

vantage dev --no-overlay

スクリーンショットやデモのようにオーバーレイが画面の邪魔になるとき、あるいはエラーの内容がすでにターミナルへ転送されていて画面側は素の状態を見たいときに使います。既定はオン（--overlay で明示することもできます）。

`VANTAGE_PROFILE` — 遅いときに測る

どのコマンドでも VANTAGE_PROFILE=1 を付けると、フェーズごとの所要時間が出ます。

VANTAGE_PROFILE=1 vantage dev

[vantage:profile] scan                          1.6ms  @0.146s
[vantage:profile] diagnostics                   2.1ms  @0.148s
[vantage:profile] generate                      1.5ms  @0.159s
[vantage:profile] vite:createServer            16.2ms  @0.165s
[vantage:profile] vite:listen                  41.3ms  @0.206s

左が所要時間、右の @ はプロセス開始からの経過です。scan(ルートの走査)・ diagnostics(静的診断)・generate(.vantage/ の生成)・vite:*・build:client / build:server が出ます。

静的診断（`check`）

vantage check が検出する診断は次の 8 種類です（エラー 6・警告 2）。

コード	深刻度	意味
`FORBIDDEN_FILE`	エラー	禁止された設定ファイルがルートに存在する
`SRC_DIR_SPLIT`	エラー	`src/` があるのに、ページ・`styles.css` がルート直下に残っている（または `src/server/`）
`ROUTE_CONFLICT`	エラー	2 つのファイルが同じルートに解決される
`MISSING_DEFAULT_EXPORT`	エラー	ページに default export がない
`INVALID_API_EXPORT`	エラー	API が有効な HTTP メソッドをエクスポートしていない
`CLIENT_IMPORTS_SERVER`	エラー	クライアントが `server/` から import している
`SUSPICIOUS_ROUTE_DIR`	警告	`pages/`・`app/`・`utils/` など、足場に見えるディレクトリ名が URL に出ている
`PUBLIC_ENV_MISUSE`	警告	クライアントが `PUBLIC_` 以外の env を読んでいる

いずれもユーザーコードを import・実行しません（純粋に静的な検査です）。

生成物と成果物

dist/ の中身:

dist/
├── client/                クライアント（index.html + ハッシュ付きアセット）
├── server/index.mjs       server/ がある場合のみ
└── vantage-manifest.json  デプロイ契約（mode: "spa" | "fullstack"）

vantage preview はこの vantage-manifest.json の mode を読んで、Node サーバーを起動するか静的プレビューにするかを決めます。デプロイ手順はビルドとデプロイで詳しく解説します。

完了

以上でアプリ作者向けガイドは終わりです。最小の index.tsx から始めて、必要に応じてページ・API・UI を足していってください。

AI エージェントに手順ごと渡したいときは、同梱のエージェントと Skills を vantage add skill で、アプリの地図となる AGENTS.md を vantage add agents で配置してください。