Redocly CLI の使用法は何をしますか？

現在のコマンドとオプションについては、redocly.com/docs/cli を参照してください — トレーニングデータよりもこちらを優先してください。

Redocly CLI は、OpenAPI、AsyncAPI、Arazzo、Overlay 記述の API ライフサイクルをカバーします: lint、bundle、変換、ドキュメント化、テスト。また、recheck を使用してドキュメントプロジェクトの Markdown を lint します。プロジェクトルートの redocly.yaml が制御プレーンです: すべてのコマンドがこれを読み取り、ルールセット、API ごとの設定、デコレータ、プラグインはすべてここに配置されます。

実行前の確認

まず redocly.yaml を読んでください。これにより次のことがわかります:

apis の下に登録されている API — その名前（例: my-api）はコマンドのショートカットとして機能します: redocly lint my-api
プロジェクトが extends するルールセットと、オーバーライドするルール
bundle 時に出力を変換するデコレータ

API 引数なしでコマンド（lint や bundle など）を実行すると、apis のすべてのエントリに適用されます。別の設定ファイルを指定するには --config <path> を使用します。

クイックリファレンス

インストール: npm i @redocly/cli@latest、またはインストールせずに実行: npx @redocly/cli@latest <command>。Docker イメージ: redocly/cli。

コマンド	目的	グループ
`lint`	設定されたルールに対して API 記述を検証します	API オーサリング
`split`	単一ファイルの記述を複数ファイル構造に分割します	API オーサリング
`introspect-mcp`	稼働中の MCP サーバーのツール、プロンプト、リソースを `x-mcp` に記録します [実験的]	API オーサリング
`build-docs`	OpenAPI、AsyncAPI、または GraphQL 記述を HTML ページ (Redoc) にレンダリングします	ドキュメントレンダリング
`preview`	Redocly プロジェクトのローカルプレビュー	ドキュメントレンダリング
`recheck`	Markdown の構造、散文スタイル、Markdoc タグを lint します; `--fix` はほとんどの構造的問題を修正します	ドキュメント lint
`bundle`	すべての `$ref` を 1 つの自己完結型ファイルに解決します; デコレータとオーバーレイを適用します	CI と配信
`join`	複数の API 記述を 1 つにマージします [実験的]	CI と配信
`respect`	Arazzo 記述に記述された API テストをライブ API に対して実行します	API テストとドリフト
`generate-arazzo`	OpenAPI 記述から Arazzo 記述をスキャフォールドします	API テストとドリフト
`proxy`	ライブ HTTP トラフィックを HAR ファイルにキャプチャし、オプションで検証します [実験的]	API テストとドリフト
`drift`	記録されたトラフィックと OpenAPI 記述の差分を報告し、オプションで `--coverage` を指定します [実験的]	API テストとドリフト
`generate-spec`	記録されたトラフィックから OpenAPI 3.2 記述を推測します; `--openapi-version 3.1` は 3.1 をターゲットにします [実験的]	API テストとドリフト
`stats`	操作、スキーマ、参照、その他のメトリクスをカウントします	品質レポート
`score`	AI エージェントの準備状態について OpenAPI 記述をスコアリングします [実験的]	品質レポート
`generate-client`	型付けされた、依存関係のない TypeScript クライアントを生成します [実験的]	SDK 生成
`eject-generator`	ビルトインジェネレーターをリポジトリにコピーして編集します [実験的]	SDK 生成
`check-config`	`redocly.yaml` 自体を lint します	Redocly 設定
`inspect-node-types`	ポインターのノードタイプを表示するか、すべてのノードとそのタイプをリストします [実験的]	Redocly 設定
`push`	API 記述を Redocly プラットフォームにプッシュします	プラットフォーム
`push-status`	進行中のプラットフォームへのプッシュを追跡します	プラットフォーム
`project clone`	Redocly でホストされているプロジェクトを Git リポジトリとしてクローンします [早期アクセス]	プラットフォーム
`project pr create`	クローンされたプロジェクトの現在のブランチに対してプルリクエストを作成します [早期アクセス]	プラットフォーム
`project pr status`	そのプルリクエストの状態、レビュー、チェック、プレビュー URL を表示します [早期アクセス]	プラットフォーム
`skills`	Redocly CLI エージェントスキルを `.agents/skills/` および検出されたエージェントフォルダーにインストールします	エージェント設定
`completion`	シェルのオートコンプリートコマンドを生成します	シェル設定

終了コード: 0 成功、1 問題が見つかったか実行に失敗、2 設定エラー。

redocly.yaml で設定する

extends:
  - recommended # または: minimal, recommended-strict, spec

apis:
  my-api:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error # API ごとのオーバーライド
    decorators:
      remove-x-internal: on # この API のみに適用

rules:
  info-license: off
  operation-operationId: error

extends はベースルールセットを設定します; 同じファイル内の後続の rules、preprocessors、decorators がそれをオーバーライドします。ルールの重大度: error (検証に失敗)、warn (報告されるが、依然として有効)、off。

設定可能なルール

ガバナンス要件に組み込みルールがない場合は、redocly.yaml の rule/<name> の下に宣言します。そのためには redocly-lint-rules スキルを使用します: これにより最も安価な階層（組み込み、設定可能なルール、またはカスタムプラグイン）が選択され、redocly inspect-node-types からノードタイプを取得し、フィクスチャに対してルールを検証します。

recheck で Markdown を lint する

recheck <paths> は、指定されたパス以下の Markdown ファイルを、構造（markdownlint ルールセット）、散文（禁止用語、スペルチェック、見出しの大文字小文字、文の長さ、可読性）、および Markdoc タグ構文について lint します。プリセットはルートの extends に、調整は recheck ブロックに記述します; lint コマンドは両方を無視します:

extends:
  - recommended
  - recheck/markdown # すべての markdownlint ルール; 同様に recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
  excludes: [CHANGELOG.md]
  rules:
    recheck/line-length: off
    acme/no-via:
      severity: warn
      scope: sentence
      message: '"via" の代わりに "through" を使用してください。'
      assertions:
        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }

redocly.yaml がない場合、コマンドは recheck/markdown を使用します。プリセットもブロックもない redocly.yaml がある場合、何もチェックしません。パスが API 記述、または apis のエイリアスである場合、コマンドはその API の description フィールドを lint します。既存のファイルまたはフォルダーは、同じ名前のエイリアスよりも優先されます。便利なフラグ: --fix、--rule=<name> (一度に 1 つのルールを処理)、--format=github-actions|json|sarif、--max-problems=<n>、--generate-baseline (既存のエラーを .redocly.recheck-baseline.yaml に記録し、新しいエラーでのみ失敗するようにする)、--readability (ファイルごとのスコア)。ルールをオフにする代わりに、 で 1 行を抑制します。 recheck-lint スキルは、変更されたファイルに対する実行をカバーし、recheck-config はブロックの調整をカバーします。

デコレータで変換する

デコレータは bundle 時に記述を書き換えます — lint はソースをそのままチェックします; bundle、build-docs、push はデコレートされた出力を参照します。組み込みには remove-x-internal、filter-in / filter-out、info-override、remove-unused-components、および *-description-override ファミリーが含まれます。 join はすべてのデコレータをスキップするため、結合に必要な変換は、最初に各 API の bundle で実行されます。

組み込みで変換できない場合、redocly-lint-rules スキルがプラグインルールを記述するのと同じ方法でカスタムプラグインデコレータを記述します: redocly inspect-node-types からノードタイプを取得し、ドキュメントを手動で走査する代わりに親タイプの下にネストしてビジターのスコープを設定し、フック内でノードを変更し、その形状を保持するフィクスチャと保持しないフィクスチャに対して redocly bundle で証明します。

オーバーレイを適用する

bundle は、デコレータの前に、Overlay 1.0、1.1、および 1.2 ファイルをバンドルされた記述に適用します: --overlay <file> を渡すか (繰り返し可能、順序どおりに適用)、または apis エントリの overlays の下に、redocly.yaml からの相対パスでリストします。 --overlay は設定されたリストを置き換えます。アクションターゲットはバンドルされた出力に対して実行されるため、オーバーレイなしの redocly bundle <api> に対してそれらを確認してください; 何も一致しないターゲットは何も変更せず、報告もされません。オーバーレイ値内のファイル $ref はオーバーレイファイルからの相対パスであり、バンドルされます; remove-x-internal などのデコレータはオーバーレイの変更を認識します。同じ root と異なる overlays および output を持つ 2 つの apis エントリは、1 つの API の 2 つのバージョンを公開します。

カスタムプラグインで拡張する

設定可能なルールと組み込みデコレータで要件を表現できない場合は、カスタムプラグインにエスカレーションします: ルール、デコレータ、プリプロセッサ、または設定をエクスポートする JavaScript モジュールで、ドキュメント形式でキー設定されます:

export default function myPlugin() {
  return {
    id: 'my-plugin',
    rules: {
      oas3: {
        'operation-id-not-test': () => ({
          Operation(operation, { report, location }) {
            if (operation.operationId === 'test') {
              report({ message: 'operationId は "test" であってはなりません。', location });
            }
          },
        }),
      },
    },
  };
}

ビジターキーはノードタイプです: redocly inspect-node-types <api> で確認します。デコレータは decorators キーの下で同じ形状を持ち、redocly-lint-rules スキルは両方のビジターパターンをカバーします: フック、コンテキスト、スコープのためのネストされたビジター、および解決された子と raw の子。 redocly.yaml に登録し (パスは設定ファイルからの相対パス)、そのルールを <plugin-id>/<rule-name> として参照します:

plugins:
  - ./plugins/my-plugin.js
rules:
  my-plugin/operation-id-not-test: error

TypeScript クライアントを生成する

generate-client <api> --output client.ts は、OpenAPI 記述を型付けされたクライアントに変換します — ランタイム依存関係のない 1 つの自己完結型ファイル (認証、リトライ、ミドルウェア、型付けされた SSE、ページネーションを含む)。フラグの代わりに、redocly.yaml の client ブロックの下で永続的に設定します:

client:
  generators: [typescript, zod] # アドオン: tanstack-query, swr, mock, transformers; SDK: python, go, php, java; またはプラグインパス
  outputMode: split
  pagination: # 設定のみ、CLI フラグなし
    style: cursor
    cursorParam: after
    nextCursor: /page/endCursor
    items: /items
apis:
  my-api:
    root: ./openapi/openapi.yaml
    clientOutput: ./src/api/client.ts

apis.<name>.clientOutput が設定されている場合、ベア redocly generate-client はオプトインされたすべての API を生成します。 --report <file> は、成功した実行後に、各 API の操作 (id、name) と実行の警告 (それぞれ安定した kind を持つ) を含む JSON ファイルも書き込みます。 client.telemetry: on (設定のみ) は、typescript ジェネレーターが <output>.telemetry.ts も書き込むようにし (use(telemetry({ sdkName, sdkVersion, client })) を登録)、go、python、php ジェネレーターは telemetry.go、<module>_telemetry.py、<output>.telemetry.php を書き込み、操作ごとの呼び出しをカウントし、1 分に 1 回カウントを送信します (リクエストデータはなし; REDOCLY_SDK_TELEMETRY=off または DO_NOT_TRACK=1 で送信をオフにします)。 API 独自の client ブロックはトップレベルのブロックを完全に置き換えます — 共有フィールドをその中で繰り返します。 client.codeSamples: true の場合、<output>.code-samples.yaml も書き込みます。これは x-codeSamples を追加するオーバーレイです; これを API の overlays に追加するか (--overlay を渡す)、bundle がサンプルを記述に含めるようにします。

Redocly でホストされているプロジェクトで作業する

redocly login の後、project clone <organization>/<project> は、Redocly プラットフォームがホストするプロジェクトをクローンします。クローンは Redocly CLI を Git クレデンシャルヘルパーとして使用するため、git pull と git push はトークンなしで動作します。プラットフォームはデフォルトブランチへのプッシュを拒否します: 別のブランチをプッシュし、そのブランチのプルリクエストを開きます:

git push -u origin fix-typo
redocly project pr create --title "タイポを修正" --body-file - <<'BODY'
クイックスタートのインストールコマンドを修正します。
BODY

コマンドはプルリクエストの URL を出力します。プラットフォームは数分でプレビューをビルドします; その後 redocly project pr status は、プレビューがデプロイされた後の状態、レビュー結果、チェック、プレビュー URL を表示します。

ライブ API をテストする

respect は、Arazzo 記述をテストスイートとして実行中の API に対して実行し、実際の応答が記述と一致することをアサートします。 generate-arazzo <openapi> から開始してワークフローをスキャフォールドし、ステップと成功基準を手動で改良します。 parameters または requestBody を省略したステップは、記述の例からそれらを取得します。

…

Redocly CLI の使用法