---
title: "CLI"
description: "PleaseAI 코드 스타일을 한 번의 명령으로 설정 — 패키지 설치와 설정 파일 작성까지."
---

> Documentation Index
> Fetch the complete documentation index at: https://code-style.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

`@pleaseai/code-style`는 PleaseAI의 공유 코드 스타일을 어떤 프로젝트에도 적용해 주는 제로 설정 CLI입니다. ESLint / Prettier / EditorConfig 패키지를 설치하고, AI 코딩 어시스턴트가 처음부터 린트를 통과하는 코드를 작성할 수 있도록 `AGENTS.md` 규칙 블록을 관리합니다.

[ultracite](https://github.com/haydenbleasel/ultracite)와 네이버페이의 [`@naverpay/code-style-cli`](https://github.com/NaverPayDev/code-style)에서 영감을 받았습니다.

## 빠른 시작

`package.json`이 있는 프로젝트 루트에서 실행하세요:

```bash
bunx @pleaseai/code-style
```

```bash
pnpm dlx @pleaseai/code-style
```

```bash
npx @pleaseai/code-style
```

CLI는 다음을 수행합니다:

1. lockfile에서 패키지 매니저를 감지합니다 (bun → pnpm → yarn → npm, 기본값은 bun)
2. 사용 가능한 도구를 체크박스 UI로 표시합니다. 이미 설치된 항목은 `(installed)`로 표시됩니다
3. 선택한 패키지를 dev dependency로 설치합니다
4. 해당 설정 파일을 작성하거나 업데이트합니다

## 명령어

### `init`

대화형 설정 — 서브커맨드를 지정하지 않으면 기본 동작입니다.

```bash
pleaseai-code-style init
pleaseai-code-style init --yes   # 비대화형, 기본값 수락
```

### `update`

패키지나 다른 설정 파일을 건드리지 않고 `AGENTS.md` 규칙 블록 **만** 새로 고칩니다. `@pleaseai/code-style`을 업그레이드한 뒤 최신 규칙을 적용할 때 사용하세요.

```bash
pleaseai-code-style update
```

### `doctor`

현재 프로젝트의 설정 상태를 보고합니다 — 어떤 패키지가 설치되어 있고, 어떤 설정 파일이 존재하는지 확인할 수 있습니다.

```bash
pleaseai-code-style doctor
```

### `check`

파일 이름, 테스트 경로, 공유 테스트 헬퍼를 [ADR-0022](https://github.com/chatbot-pf/engineering-standards/blob/main/docs/adr/0022-agent-navigable-code-organization-standard.md) code-organization 표준(3층)에 맞춰 검사합니다. 구조 규칙(2층)은 **ast-grep** 도구가 `sgconfig.yml`에 연결해 주는 `@pleaseai/ast-grep-config` 규칙으로 `ast-grep scan`을 따로 실행합니다.

`check`는 CLI에 번들된 `@pleaseai/ast-grep-config`의 추출 규칙을 `@ast-grep/cli`의 `ast-grep` 바이너리로 실행합니다. 바이너리는 검사하는 프로젝트에서 먼저 찾고, 프로젝트에 있는 추출 규칙 사본은 마지막 대안으로만 씁니다. 둘 다 dev dependency로 설치하세요 — 바이너리는 `check`용, 패키지는 `ast-grep scan` 규칙용입니다(`init`의 **ast-grep** 도구가 설치해 줍니다):

```bash
bun add -D @pleaseai/ast-grep-config @ast-grep/cli
```

```bash
please-style check              # 현재 디렉터리 검사
please-style check packages/    # 하위 디렉터리 검사
please-style check --json       # 기계가 읽는 출력
please-style check --strict     # 발견 사항이 있으면 exit 1 (위반을 없앤 뒤 CI용)
```

| 플래그 | 설명 |
| --- | --- |
| `[path]` | 검사할 디렉터리 (기본값: 현재 디렉터리) |
| `--json` | 결과를 JSON(`root`, `findings`, `notices`)으로 출력 |
| `--strict` | 발견 사항이 하나라도 있으면 exit 1 (기본: 경고만) |
| `--config <file>` | 설정 파일 (기본값: 둘러싼 프로젝트 루트의 `code-organization.json`, 위쪽에 프로젝트 표지 파일이 없으면 `<path>`의 것) |

종료 코드: `0` 발견 사항 없음 또는 경고만, `1` `--strict`에서 발견 사항 있음, `2` 사용법 오류, 설정 오류, 또는 추출이 필요한 파일이 있는데 `@ast-grep/cli`를 찾지 못함.

선택 설정 파일 `code-organization.json`은 이름을 **추가**만 할 수 있습니다 — TypeScript `sourceRoots`와 테스트 `envSegments`를 더할 수 있고, 테스트를 소스 옆에 두거나 검사를 끄는 옵션은 없습니다. 전체 검사 내용은 [CLI README](https://github.com/pleaseai/code-style/tree/main/packages/cli/README.ko.md#please-style-check)를 참고하세요.

## 지원 도구

| 도구 | npm 패키지 | 설정 파일 |
| --- | --- | --- |
| eslint-config | `@pleaseai/eslint-config`, `eslint` | `eslint.config.mjs` |
| prettier-config | `@pleaseai/prettier-config`, `prettier` | `package.json#prettier` |
| editorconfig | `@pleaseai/editorconfig` | `.editorconfig` |
| agents-md | — | `AGENTS.md` (마커로 관리되는 블록) |
| ast-grep | `@pleaseai/ast-grep-config`, `@ast-grep/cli` | `sgconfig.yml` |

## `AGENTS.md` 규칙 블록

CLI는 `AGENTS.md`에 마커로 구분된 블록을 작성하므로, 주변에 직접 작성한 내용을 섞어 두어도 다음 실행 시 사라지지 않습니다:

```md title="AGENTS.md"
내 프로젝트 노트는 여기에 있습니다.

<!-- pleaseai-code-style:start -->
# PleaseAI Code Style

이 규칙은 `@pleaseai/code-style`에서 관리합니다.
`pleaseai-code-style update`를 실행하면 이 블록이 새로고침됩니다.

- 포매터: `@pleaseai/eslint-config` (`@antfu/eslint-config`를 감쌈)
- 세미콜론 없음, 홑따옴표, 공백 2칸 들여쓰기, trailing comma, LF 개행
- ESM만 사용 — `require`/`module.exports` 사용 금지
- ...
<!-- pleaseai-code-style:end -->

내 콘텐츠는 그대로 유지됩니다.
```

CLI는 두 마커 주석 사이의 내용 **만** 관리하며 — `AGENTS.md`의 나머지 내용은 그대로 보존됩니다. `update`를 연속으로 두 번 실행해도 no-op이며, 블록이 중복되지 않습니다.

전체 원본 규칙 목록은 AI 어시스턴트가 긴 버전을 읽기 원할 때 참고할 수 있도록 `node_modules/@pleaseai/code-style/rules.md`로 함께 배포됩니다.

## 옵션

| 플래그 | 설명 |
| --- | --- |
| `--yes`, `-y` | 기본값을 수락하고 기존 파일을 확인 없이 덮어씀 |
| `--lang <ko\|en>` | CLI 언어 강제 지정 (기본값은 `$LC_ALL` / `$LANG`) |
| `--help`, `-h` | 도움말 출력 |
| `--version`, `-v` | CLI 버전 출력 |

## 현지화

CLI는 `LC_ALL`, `LANG`, `LC_MESSAGES`에서 locale을 자동 감지하며, 현재 한국어와 영어 메시지를 제공합니다. `--lang ko` 또는 `--lang en`으로 강제 지정할 수 있습니다:

```bash
pleaseai-code-style --lang ko init
```

## CI에서의 사용

`--yes`와 언어 옵션을 조합하면 CI나 프로젝트 템플릿에 적합한 완전 비대화형 실행을 만들 수 있습니다:

```bash
pleaseai-code-style --yes --lang en init
```

모든 도구의 기본값을 수락하고, 기존 설정 파일을 덮어쓰며, 영어로 출력합니다.

## 바이너리

패키지는 두 개의 bin 엔트리를 노출합니다 — 원하는 것을 사용하세요:

- `pleaseai-code-style`
- `please-style` (짧은 별칭)

둘 다 동일한 실행 파일을 가리킵니다.

Source: https://code-style.pages.dev/ko/cli/index.mdx