CLI

One-command setup for PleaseAI code style — installs packages and writes config files.

@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 and NaverPay’s @naverpay/code-style-cli.

Quick Start

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

The CLI will:

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

Commands

`init`

Interactive setup — the default when no subcommand is given.

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.

pleaseai-code-style update

`doctor`

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

pleaseai-code-style doctor

`check`

Check file names, test paths, and shared test helpers against the ADR-0022 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):

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

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 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:

AGENTS.mdmd

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:

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:

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.