Redocly CLI 사용법
최신 명령어와 옵션은 redocly.com/docs/cli를 참고하세요. (트레이닝 데이터보다 공식 문서를 우선시하십시오.)
Redocly CLI는 OpenAPI, AsyncAPI, Arazzo 및 Overlay 설명의 API 수명 주기(린트, 번들, 변환, 문서화, 테스트)를 다룹니다.
또한 recheck로 문서 프로젝트의 Markdown을 린트합니다.
프로젝트 루트의 redocly.yaml은 제어판 역할을 합니다: 모든 명령어가 이를 읽으며, 규칙 집합, API별 설정, 데코레이터 및 플러그인이 모두 여기에 있습니다.
실행하기 전에
먼저 redocly.yaml을 읽으십시오. 다음을 알려줍니다:
apis아래에 등록된 API와 그 이름(예:my-api)은 명령어 단축키로 사용됩니다:redocly lint my-api- 프로젝트가
extends하는 규칙 집합과 재정의하는 규칙 - 번들 시 출력을 변환하는 데코레이터
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 태그를 린트합니다. --fix는 대부분의 구조적 문제를 수정합니다. | 문서 린팅 |
bundle | 모든 $ref를 하나의 독립적인 파일로 해결합니다. 데코레이터와 오버레이를 적용합니다. | CI 및 전달 |
join | 여러 API 설명을 하나로 병합합니다 [실험적]. | 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 자체를 린트합니다. | 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 린트하기
recheck <paths>는 주어진 경로의 Markdown 파일을 구조(markdownlint 규칙 집합), 산문(금지 용어, 맞춤법, 제목 대소문자, 문장 길이, 가독성), Markdoc 태그 구문에 대해 린트합니다.
프리셋은 루트 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 필드를 린트합니다.
기존 파일이나 폴더가 동일한 이름의 별칭보다 우선합니다.
유용한 플래그: --fix, --rule=<name>(한 번에 하나의 규칙 작업), --format=github-actions|json|sarif, --max-problems=<n>, --generate-baseline(기존 오류를 .redocly.recheck-baseline.yaml에 기록하고 새 오류에서만 실패), --readability(파일별 점수).
규칙을 끄는 대신 <!-- recheck-disable-next-line <rule> -->로 한 줄을 무음 처리합니다.
recheck-lint 스킬은 변경된 파일에 대해 실행하는 것을 다루고, recheck-config는 블록 조정을 다룹니다.
데코레이터로 변환하기
데코레이터는 번들 시 설명을 다시 작성합니다. lint는 작성된 대로 소스를 확인하고, bundle, build-docs, push는 데코레이트된 출력을 봅니다.
내장 데코레이터에는 remove-x-internal, filter-in / filter-out, info-override, remove-unused-components, *-description-override 계열이 포함됩니다.
join은 모든 데코레이터를 건너뛰므로, 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을 가진 두 개의 apis 항목은 하나의 API에 대해 두 가지 버전을 게시합니다.
사용자 정의 플러그인으로 확장하기
설정 가능한 규칙과 내장 데코레이터로 요구 사항을 표현할 수 없을 때는 사용자 정의 플러그인으로 에스컬레이션하십시오: 규칙, 데코레이터, 전처리기 또는 구성을 내보내는 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 스킬은 둘 다에 대한 방문자 패턴(훅, 컨텍스트, 범위를 위한 중첩 방문자, 해결된 자식과 원시 자식)을 다룹니다.
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 설명을 타입이 지정된 클라이언트로 변환합니다. 하나의 독립적인 파일에 제로 런타임 종속성(인증, 재시도, 미들웨어, 타입이 지정된 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 인수 없음)는 옵트인된 모든 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분에 한 번씩 카운트를 보냅니다(요청 데이터 없음; 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 credential helper로 사용하므로 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를 생략한 단계는 설명의 예제에서 가져옵니다.
API 설명 점수 매기기
score는 OpenAPI 설명을 검사하고 AI 에이전트가 API를 올바르게 사용할 가능성을 높이는 요소에 대해 0-100 점수를 반환합니다.
AI 에이전트가 API 설명을 소비할 때, 검색 가능한 작업 ID, 명확한 매개변수 설명, 예제, 및 오류 응답이 있는 설명은 더 나은 자동화를 가능하게 합니다.
score는 설명, 작업, 매개변수, 응답, 예제 및 보안 정의를 평가하여 에이전트가 설명과 상호 작용하는 방식을 모델링합니다.
npx @redocly/cli@latest score path/to/openapi.yaml
공개 점수 등급: 90-100 'A', 80-89 'B', 55-79 'C', <55 'D'.
플랫폼에 푸시하기
redocly login 후 push <api> [<domain>]은 API 설명을 Redocly 플랫폼에 업로드합니다.
apis에 <domain>/<name>으로 등록된 API 또는 루트 domain 아래의 API 이름을 사용합니다.
선택적 두 번째 인수로 도메인을 재정의할 수 있습니다.
푸시는 번들링, 데코레이트, 그리고 플랫폼으로 전송합니다.
조직 및 프로젝트가 대상입니다: push my-api@v2 또는 push my-api --destination my-org/my-project를 확인하십시오.
redocly.yaml의 push 블록 아래에서 도메인, 조직, 배치 파일 등을 설정할 수 있습니다.
명령어 완성 및 설치
completion은 셸(현재 bash, zsh, fish)에 대한 자동 완성 스크립트를 생성합니다:
redocly completion >> ~/.zshrc
sdk 하위 명령어(sdk install, sdk update, sdk version)는 Redocly SDK를 간접적으로 관리합니다(주로 플랫폼 사용자용).
skills는 스킬 파일을 .agents/skills/ 및 사용 중인 AI 에이전트에 설치합니다.