---
title: "CLI"
description: "One-command setup for PleaseAI code style — installs packages and writes config files."
---

> 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` is a zero-config CLI that wires PleaseAI's shared code style into any project. It installs the ESLint / Prettier / EditorConfig packages and manages an `AGENTS.md` rules block so AI coding assistants know how to write code that passes lint on the first try.

Inspired by [ultracite](https://github.com/haydenbleasel/ultracite) and NaverPay's [`@naverpay/code-style-cli`](https://github.com/NaverPayDev/code-style).

## Quick Start

Run from the root of any project that has a `package.json`:

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

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

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

The CLI will:

1. Detect your package manager from the lockfile (bun → pnpm → yarn → npm, falling back to bun)
2. Show a checkbox UI listing the available tools; already-installed ones are labelled `(installed)`
3. Install the packages you select as dev dependencies
4. Write or update the matching config files

## Commands

### `init`

Interactive setup — the default when no subcommand is given.

```bash
pleaseai-code-style init
pleaseai-code-style init --yes   # non-interactive, accept defaults
```

### `update`

Refresh **only** the `AGENTS.md` rules block without touching packages or other config files. Use this after bumping `@pleaseai/code-style` to pull in the latest rules.

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

### `doctor`

Report the current project configuration status — which packages are installed, which config files exist.

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

### `check`

Check file names, test paths, and shared test helpers against the [ADR-0022](https://github.com/chatbot-pf/engineering-standards/blob/main/docs/adr/0022-agent-navigable-code-organization-standard.md) code-organization standard (layer 3). The structural rules (layer 2) run separately with `ast-grep scan` and the `@pleaseai/ast-grep-config` rules that the **ast-grep** tool wires into `sgconfig.yml`.

`check` runs the extraction rules from the CLI's bundled `@pleaseai/ast-grep-config` with the `ast-grep` binary from `@ast-grep/cli`; the binary resolves from the checked project first (the project's copy of the extraction rules is only a last-resort fallback). Install both as dev dependencies — the binary for `check`, the package for the `ast-grep scan` rules (the **ast-grep** tool in `init` does this):

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

```bash
please-style check              # check the current directory
please-style check packages/    # check a subdirectory
please-style check --json       # machine-readable output
please-style check --strict     # exit 1 on any finding (for CI once clean)
```

| Flag | Description |
| --- | --- |
| `[path]` | Directory to check (default: the current directory) |
| `--json` | Print the result as JSON (`root`, `findings`, `notices`) |
| `--strict` | Exit 1 when there is any finding (default: warn only) |
| `--config <file>` | Config file (default: `code-organization.json` in the enclosing project root, or in `<path>` when no project marker is found above it) |

Exit codes: `0` no findings or warnings only, `1` findings with `--strict`, `2` usage or config error, or `@ast-grep/cli` cannot be resolved while a file needs extraction.

An optional `code-organization.json` can only **add** names — extra TypeScript `sourceRoots` and extra test `envSegments`. There is no option to move tests next to sources or to turn a check off. See the [CLI README](https://github.com/pleaseai/code-style/tree/main/packages/cli#please-style-check) for every check.

## Supported Tools

| Tool | npm package(s) | Config file |
| --- | --- | --- |
| 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` (marker-managed block) |
| ast-grep | `@pleaseai/ast-grep-config`, `@ast-grep/cli` | `sgconfig.yml` |

## The `AGENTS.md` Rules Block

The CLI writes a marker-delimited block into `AGENTS.md` so you can mix your own content around it without losing edits on the next run:

```md title="AGENTS.md"
My project notes live here.

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

These rules are managed by `@pleaseai/code-style`. Run
`pleaseai-code-style update` to refresh this block.

- Formatter: `@pleaseai/eslint-config` (wraps `@antfu/eslint-config`)
- No semicolons, single quotes, 2-space indent, trailing commas, LF line endings
- ESM only — never emit `require`/`module.exports`
- ...
<!-- pleaseai-code-style:end -->

My own content stays here untouched.
```

The CLI **only** owns the content between the two marker comments — everything else in `AGENTS.md` is preserved verbatim. Running `update` twice in a row is a no-op; the block never duplicates.

The full canonical rules are shipped per language for AI assistants that prefer to read the long version: start with `node_modules/@pleaseai/code-style/rules/general.md` (every language), then the language guide listed in `node_modules/@pleaseai/code-style/rules.md` (for example, `node_modules/@pleaseai/code-style/rules/typescript.md` for TypeScript and JavaScript).

## Options

| Flag | Description |
| --- | --- |
| `--yes`, `-y` | Accept defaults and overwrite existing files without prompting |
| `--lang <list>` | Languages for the AGENTS.md rules block, comma-separated (`init`/`doctor`: detected; `update`: the languages already in the block; see below) |
| `--locale <ko\|en>` | Force the CLI locale (defaults to `$LC_ALL` / `$LANG`) |
| `--help`, `-h` | Print help |
| `--version`, `-v` | Print the CLI version |

## Languages

`--lang <list>` selects the programming languages the AGENTS.md rules block links to, for example `--lang typescript,dart`. Accepted values: `typescript`, `dart`, `rust`, `java`, `go`, `python`, `ruby`, `csharp`, `html-css`. Without it, `init` detects languages from marker files in the project root: `package.json` or `tsconfig.json` (typescript), `pubspec.yaml` (dart), `Cargo.toml` (rust), `build.gradle`, `build.gradle.kts` or `pom.xml` (java), `go.mod` (go), `pyproject.toml` (python). Interactive `init` lets you adjust the detected set. `update` keeps the languages the existing block links unless `--lang` is given. An unknown `--lang` value exits with an error (exit code 1) listing the accepted languages. `doctor` reports the detected languages.

## Localisation

The CLI auto-detects your locale from `LC_ALL`, `LANG`, or `LC_MESSAGES` and currently ships Korean and English messages. Override with `--locale ko` or `--locale en`:

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

`--lang ko` and `--lang en` are the deprecated locale alias: they still set the locale for now, with a deprecation warning, and select no languages. When both `--lang ko|en` and `--locale` are given, `--locale` wins. A `--locale` value other than `ko` or `en` also exits with an error (exit code 1).

## CI Usage

Combine `--yes` with a locale override for a fully non-interactive invocation suitable for CI or project templates:

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

This accepts defaults for every tool, overwrites any existing config files, and uses English output.

## Binaries

The package exposes two bin entries — use whichever you prefer:

- `pleaseai-code-style`
- `please-style` (short alias)

Both point to the same executable.

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