# Commands
URL: /react/getting-started/cli/commands
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/react/getting-started/cli/commands.mdx

@seed-design/cli 명령어를 안내해요.

## 공통 동작

- CLI 실행에는 Node.js 20.19.0 이상이 필요해요.
- `add`, `add-all`은 `seed-design.json` 설정 파일을 사용해요.
- 설정 파일이 없거나 읽을 수 없으면 생성할지 먼저 물어봐요.
- 항목 추가 시 필요한 npm 패키지 의존성은 자동으로 설치돼요.
- `add`, `add-all` 실행 시 스니펫이 요구하는 seed-design 패키지 버전과 현재 프로젝트 버전이 다르면 경고를 보여줘요. (React: `@seed-design/react`, `@seed-design/css` / Lynx: `@seed-design/lynx-react`, `@seed-design/lynx-css`)
- 기존 파일과 내용이 다르면 기본적으로 `덮어쓰기 / 백업 후 교체 / 건너뛰기`를 선택할 수 있어요.
- `--on-diff` 옵션을 주면 충돌 처리 방식을 미리 고정할 수 있어요.
- 실패 원인을 자세히 확인하려면 `--verbose` 옵션을 사용할 수 있어요.

## init

`seed-design.json` 파일을 생성하는 명령어예요.

<Card icon="<IconFile />" title="Configuration" href="/react/getting-started/cli/configuration">
  `seed-design.json` 파일에 대해 알아봅니다.
</Card>

### init 명령어 입력하기

- npm: npx @seed-design/cli@latest init
- pnpm: pnpm dlx @seed-design/cli@latest init
- yarn: yarn dlx @seed-design/cli@latest init
- bun: bun x @seed-design/cli@latest init

### seed-design 설정

```sh
◇  TypeScript를 사용중이신가요?
│  Yes
│
◇  React Server Components를 사용중이신가요?
│  No
│
◇  어떤 프레임워크를 사용하시나요?
│  React
│
◇  seed-design 폴더 경로를 입력해주세요. (기본값은 프로젝트 루트에 생성됩니다.)
│  ./seed-design
│
◇  개선을 위해 익명 사용 데이터를 수집할까요?
│  Yes
```

### 옵션

| 옵션                | 설명                                 |
| ----------------- | ---------------------------------- |
| `-c, --cwd <cwd>` | 작업 디렉토리. 기본값은 현재 디렉토리              |
| `-y, --yes`       | 질문 없이 기본값으로 `seed-design.json` 생성  |
| `--default`       | Deprecated. `--yes`와 동일하게 기본값으로 생성 |
| `--verbose`       | 실패 시 stack trace 등 상세 오류 정보 출력     |
| `-h, --help`      | 도움말 출력                             |

- npm: npx @seed-design/cli@latest init --yes
- pnpm: pnpm dlx @seed-design/cli@latest init --yes
- yarn: yarn dlx @seed-design/cli@latest init --yes
- bun: bun x @seed-design/cli@latest init --yes

## add

스니펫을 다운로드하고 프로젝트에 추가하는 명령어예요.

<Card icon="<IconFile />" title="Snippet" href="/react/components/concepts/snippet">
  자주 쓰이는 UI 패턴의 재사용을 돕는 스니펫에 대해 알아봅니다.
</Card>

- npm: npx @seed-design/cli@latest add \[...item-ids]
- pnpm: pnpm dlx @seed-design/cli@latest add \[...item-ids]
- yarn: yarn dlx @seed-design/cli@latest add \[...item-ids]
- bun: bun x @seed-design/cli@latest add \[...item-ids]

`item-ids`를 생략하면, 다운로드 가능한 항목을 인터랙티브하게 선택할 수 있어요.

- npm: npx @seed-design/cli@latest add
- pnpm: pnpm dlx @seed-design/cli@latest add
- yarn: yarn dlx @seed-design/cli@latest add
- bun: bun x @seed-design/cli@latest add

```sh copy
◆  추가할 항목을 선택해주세요 (스페이스 바로 여러 개 선택 가능)
│  ◻ ui:action-button
│  ◻ ui:alert-dialog
│  ◻ ui:callout
│  ◻ ui:checkbox
│  ◻ ui:switch
│  ◻ ui:text-field
│  ◻ ui:tabs
│  ◻ (deprecated) ui:old-component
│  ◻ ...
└
```

여러 항목을 직접 지정할 수도 있어요.

- npm: npx @seed-design/cli@latest add ui:action-button ui:alert-dialog
- pnpm: pnpm dlx @seed-design/cli@latest add ui:action-button ui:alert-dialog
- yarn: yarn dlx @seed-design/cli@latest add ui:action-button ui:alert-dialog
- bun: bun x @seed-design/cli@latest add ui:action-button ui:alert-dialog

### 옵션

| 옵션                               | 설명                                                                     |
| -------------------------------- | ---------------------------------------------------------------------- |
| `-c, --cwd <cwd>`                | 작업 디렉토리. 기본값은 현재 디렉토리                                                  |
| `-u, --baseUrl <baseUrl>`        | 레지스트리 base URL                                                         |
| `--seed-react-version <version>` | 지정한 SEED React 버전의 레지스트리 사용 (예: `1.2`). `--baseUrl`/`--framework`보다 우선 |
| `-f, --framework <framework>`    | 대상 프레임워크 (`react` 또는 `lynx`). config의 `framework` 값을 덮어씀               |
| `--on-diff <mode>`               | 파일 충돌 처리 방식 지정 (`overwrite` 또는 `backup`)                               |
| `-a, --all`                      | **Deprecated**. 현재는 에러를 출력하고 `add-all` 사용을 안내                          |
| `--verbose`                      | 실패 시 stack trace 등 상세 오류 정보 출력                                         |
| `-h, --help`                     | 도움말 출력                                                                 |

### 버전에 맞는 스니펫 받기

프로젝트에 설치된 SEED 패키지 버전과 호환되는 스니펫이 필요하면 버전 옵션을 사용하세요. 해당 버전이 배포된 레지스트리 주소를 CLI가 자동으로 찾아줍니다.

- npm: npx @seed-design/cli@latest add --seed-react-version 1.2 ui:action-button
- pnpm: pnpm dlx @seed-design/cli@latest add --seed-react-version 1.2 ui:action-button
- yarn: yarn dlx @seed-design/cli@latest add --seed-react-version 1.2 ui:action-button
- bun: bun x @seed-design/cli@latest add --seed-react-version 1.2 ui:action-button

버전 옵션은 base URL과 프레임워크(react)를 함께 결정하므로 `--baseUrl` / `--framework`보다 우선해요.

#### baseUrl 직접 지정

레지스트리 주소를 직접 지정하려면 `--baseUrl`을 사용하세요. 기본값은 배포 환경 기준 [`https://seed-design.io`](https://seed-design.io)입니다.

- npm: npx @seed-design/cli@latest add --baseUrl https://v1-2.seed-design.io
- pnpm: pnpm dlx @seed-design/cli@latest add --baseUrl https://v1-2.seed-design.io
- yarn: yarn dlx @seed-design/cli@latest add --baseUrl https://v1-2.seed-design.io
- bun: bun x @seed-design/cli@latest add --baseUrl https://v1-2.seed-design.io

### 파일 충돌 처리

`--on-diff`를 지정하지 않으면, 기존 파일과 새 스니펫이 다를 때 아래 중 하나를 직접 고를 수 있어요.

- 덮어쓰기
- 기존 파일을 `legacy-<파일명>-<timestamp>`로 백업 후 교체
- 건너뛰기

## add-all

레지스트리 단위로 항목을 한 번에 추가하는 명령어예요.

- npm: npx @seed-design/cli@latest add-all \[...registry-ids]
- pnpm: pnpm dlx @seed-design/cli@latest add-all \[...registry-ids]
- yarn: yarn dlx @seed-design/cli@latest add-all \[...registry-ids]
- bun: bun x @seed-design/cli@latest add-all \[...registry-ids]

모든 레지스트리의 모든 항목을 추가하려면 `--all` 옵션을 사용하세요.

- npm: npx @seed-design/cli@latest add-all --all # 모든 레지스트리의 모든 항목 추가
- pnpm: pnpm dlx @seed-design/cli@latest add-all --all # 모든 레지스트리의 모든 항목 추가
- yarn: yarn dlx @seed-design/cli@latest add-all --all # 모든 레지스트리의 모든 항목 추가
- bun: bun x @seed-design/cli@latest add-all --all # 모든 레지스트리의 모든 항목 추가

특정 레지스트리의 모든 항목을 추가할 수도 있습니다.

- npm: npx @seed-design/cli@latest add-all breeze # breeze 레지스트리의 모든 항목 추가
- pnpm: pnpm dlx @seed-design/cli@latest add-all breeze # breeze 레지스트리의 모든 항목 추가
- yarn: yarn dlx @seed-design/cli@latest add-all breeze # breeze 레지스트리의 모든 항목 추가
- bun: bun x @seed-design/cli@latest add-all breeze # breeze 레지스트리의 모든 항목 추가

deprecated 항목을 포함하려면 `--include-deprecated` 옵션을 사용하세요.

- npm: npx @seed-design/cli@latest add-all ui --include-deprecated # ui 레지스트리의 모든 항목 추가 (deprecated 포함)
- pnpm: pnpm dlx @seed-design/cli@latest add-all ui --include-deprecated # ui 레지스트리의 모든 항목 추가 (deprecated 포함)
- yarn: yarn dlx @seed-design/cli@latest add-all ui --include-deprecated # ui 레지스트리의 모든 항목 추가 (deprecated 포함)
- bun: bun x @seed-design/cli@latest add-all ui --include-deprecated # ui 레지스트리의 모든 항목 추가 (deprecated 포함)

레지스트리 ID와 `--all`을 모두 생략하면, 추가할 레지스트리를 인터랙티브하게 선택할 수 있어요.

### 옵션

| 옵션                               | 설명                                                                     |
| -------------------------------- | ---------------------------------------------------------------------- |
| `-a, --all`                      | 모든 레지스트리의 모든 항목 추가                                                     |
| `--include-deprecated`           | deprecated 항목 포함                                                       |
| `-c, --cwd <cwd>`                | 작업 디렉토리. 기본값은 현재 디렉토리                                                  |
| `-u, --baseUrl <baseUrl>`        | 레지스트리 base URL                                                         |
| `--seed-react-version <version>` | 지정한 SEED React 버전의 레지스트리 사용 (예: `1.2`). `--baseUrl`/`--framework`보다 우선 |
| `-f, --framework <framework>`    | 대상 프레임워크 (`react` 또는 `lynx`). config의 `framework` 값을 덮어씀               |
| `--on-diff <mode>`               | 파일 충돌 처리 방식 지정 (`overwrite` 또는 `backup`)                               |
| `--verbose`                      | 실패 시 stack trace 등 상세 오류 정보 출력                                         |
| `-h, --help`                     | 도움말 출력                                                                 |

## compat

현재 프로젝트의 seed-design 패키지 버전과 스니펫 요구 버전이 호환되는지 검사해요. 플랫폼에 따라 검사 대상 패키지가 달라요. (React: `@seed-design/react`, `@seed-design/css` / Lynx: `@seed-design/lynx-react`, `@seed-design/lynx-css`)

- npm: npx @seed-design/cli@latest compat
- pnpm: pnpm dlx @seed-design/cli@latest compat
- yarn: yarn dlx @seed-design/cli@latest compat
- bun: bun x @seed-design/cli@latest compat

기본값은 `seed-design.json`의 `path` 아래에 이미 추가된 스니펫만 검사해요.

호환성 이슈가 있으면 종료 코드 `1`, 문제가 없으면 `0`으로 종료돼서 CI/에이전트 환경에서도 바로 사용할 수 있어요.

특정 항목만 검사할 수도 있어요.

- npm: npx @seed-design/cli@latest compat ui:action-button ui:alert-dialog
- pnpm: pnpm dlx @seed-design/cli@latest compat ui:action-button ui:alert-dialog
- yarn: yarn dlx @seed-design/cli@latest compat ui:action-button ui:alert-dialog
- bun: bun x @seed-design/cli@latest compat ui:action-button ui:alert-dialog

컴포넌트 shorthand를 쓸 때는 `-c` 옵션을 사용해요.

- npm: npx @seed-design/cli@latest compat -c action-button -c alert-dialog
- pnpm: pnpm dlx @seed-design/cli@latest compat -c action-button -c alert-dialog
- yarn: yarn dlx @seed-design/cli@latest compat -c action-button -c alert-dialog
- bun: bun x @seed-design/cli@latest compat -c action-button -c alert-dialog

모든 registry 항목을 검사하려면 `--all`을 사용하세요.

- npm: npx @seed-design/cli@latest compat --all
- pnpm: pnpm dlx @seed-design/cli@latest compat --all
- yarn: yarn dlx @seed-design/cli@latest compat --all
- bun: bun x @seed-design/cli@latest compat --all

### 옵션

| 옵션                            | 설명                                                       |
| ----------------------------- | -------------------------------------------------------- |
| `-c, --component <component>` | 검사할 컴포넌트 ID. 여러 번 또는 쉼표로 지정 가능                           |
| `-r, --registry <registryId>` | `--component`에 shorthand를 사용할 때 기본 registry 지정           |
| `-a, --all`                   | 모든 registry 항목 검사                                        |
| `--cwd <cwd>`                 | 작업 디렉토리. 기본값은 현재 디렉토리                                    |
| `-u, --baseUrl <baseUrl>`     | 레지스트리 base URL                                           |
| `-f, --framework <framework>` | 대상 프레임워크 (`react` 또는 `lynx`). config의 `framework` 값을 덮어씀 |
| `--verbose`                   | 실패 시 stack trace 등 상세 오류 정보 출력                           |
| `-h, --help`                  | 도움말 출력                                                   |

## docs

문서 링크, llms.txt 링크, 스니펫 링크를 조회하는 명령어예요.

- npm: npx @seed-design/cli@latest docs \[query]
- pnpm: pnpm dlx @seed-design/cli@latest docs \[query]
- yarn: yarn dlx @seed-design/cli@latest docs \[query]
- bun: bun x @seed-design/cli@latest docs \[query]

`query`를 생략하면, 카테고리 → 섹션 → 항목을 인터랙티브하게 선택할 수 있어요.

- npm: npx @seed-design/cli@latest docs
- pnpm: pnpm dlx @seed-design/cli@latest docs
- yarn: yarn dlx @seed-design/cli@latest docs
- bun: bun x @seed-design/cli@latest docs

```sh copy
◆  카테고리를 선택해주세요
│  React
│
◆  섹션을 선택해주세요
│  컴포넌트
│
◆  항목을 선택해주세요
│  Action Button
│
│  action-button
│  - docs: https://seed-design.io/react/components/action-button
│  - llms.txt: https://seed-design.io/llms/react/components/action-button.txt
│  - snippet: https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry/react/ui/action-button.tsx
│
```

### 직접 검색

항목 이름으로 직접 검색할 수 있어요.

- npm: npx @seed-design/cli@latest docs action-button
- pnpm: pnpm dlx @seed-design/cli@latest docs action-button
- yarn: yarn dlx @seed-design/cli@latest docs action-button
- bun: bun x @seed-design/cli@latest docs action-button

### 경로 기반 검색

`카테고리/섹션/항목` 형태로 직접 경로를 지정할 수 있어요.

- npm: npx @seed-design/cli@latest docs react/components/action-button
- pnpm: pnpm dlx @seed-design/cli@latest docs react/components/action-button
- yarn: yarn dlx @seed-design/cli@latest docs react/components/action-button
- bun: bun x @seed-design/cli@latest docs react/components/action-button

카테고리만 지정하면 해당 카테고리의 섹션/항목을 선택할 수 있어요.

- npm: npx @seed-design/cli@latest docs react
- pnpm: pnpm dlx @seed-design/cli@latest docs react
- yarn: yarn dlx @seed-design/cli@latest docs react
- bun: bun x @seed-design/cli@latest docs react

카테고리/섹션까지 지정하면 해당 섹션의 항목을 선택할 수 있어요.

- npm: npx @seed-design/cli@latest docs react/components
- pnpm: pnpm dlx @seed-design/cli@latest docs react/components
- yarn: yarn dlx @seed-design/cli@latest docs react/components
- bun: bun x @seed-design/cli@latest docs react/components

### 오타 제안

경로에 오타가 있으면 유사한 유효 경로를 제안해줘요.

```sh copy
react/component/action-buton: 문서를 찾을 수 없어요.

💡 이것을 의미했나요?
   - react/components/action-button
```

### Raw 모드

`--raw` 옵션을 사용하면 UI 없이 llms.txt 내용을 순수 마크다운으로 출력해요. LLM 파이프나 스크립트에서 활용할 수 있어요.

- npm: npx @seed-design/cli@latest docs react/components/action-button --raw
- pnpm: pnpm dlx @seed-design/cli@latest docs react/components/action-button --raw
- yarn: yarn dlx @seed-design/cli@latest docs react/components/action-button --raw
- bun: bun x @seed-design/cli@latest docs react/components/action-button --raw

패키지 changelog도 가져올 수 있어요.

- npm: npx @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw
- pnpm: pnpm dlx @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw
- yarn: yarn dlx @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw
- bun: bun x @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw

### 옵션

| 옵션                        | 설명                              |
| ------------------------- | ------------------------------- |
| `--raw`                   | UI 없이 llms.txt 내용을 순수 마크다운으로 출력 |
| `-u, --baseUrl <baseUrl>` | 레지스트리 base URL                  |
| `--verbose`               | 실패 시 stack trace 등 상세 오류 정보 출력  |
| `-h, --help`              | 도움말 출력                          |