editorconfig

A small CLI to manage a consistent .editorconfig across your projects.

• ✅ Generate a sane default .editorconfig in seconds
• ✅ Check if your existing file matches the target setup
• ✅ Confirm before overwriting an existing .editorconfig (or pass --overwrite to skip the prompt)
• ✅ Override the built-in template with a team-shared file via --template (local path or https:// URL)

Why?

Keeping .editorconfig aligned across multiple repositories is boring and error-prone:

• Some repos have no .editorconfig
• Some have outdated or partial settings
• People copy–paste from “somewhere” and drift over time

This CLI aims to provide a single source of truth for your preferred .editorconfig, and a few helpers to keep it in sync.

Installation

You can use it without installing, via npx:

npx @sheplu/editorconfig --mode=write

Or install it globally:

npm install -g @sheplu/editorconfig
editorconfig

Or as a dev dependency:

npm install -D @sheplu/editorconfig

Quick Start

From the root of your project:

npx @sheplu/editorconfig --mode=write

This will:

• Create a .editorconfig file if it doesn’t exist
• Write the default template
• Ask before overwriting an existing file (or fail in non-interactive contexts unless --overwrite is passed)

Current Features

write

npx @sheplu/editorconfig --mode=write

Creates a base .editorconfig file in the current directory.

If a .editorconfig already exists at the target path, the CLI will:

• Prompt for confirmation in an interactive terminal (y / yes to overwrite, anything else keeps the file).
• Exit non-zero in non-interactive contexts (CI, redirected stdin) so a script never silently destroys an existing config.

Pass --overwrite (or -o) to bypass the prompt and force a rewrite:

npx @sheplu/editorconfig --mode=write --overwrite

You can also point at a custom path:

npx @sheplu/editorconfig --mode=write --path=path/to/.editorconfig

Typical content (example):

root = true

[*]
indent_style = tab
indent_size = 4
tab_width = 4
end_of_line = lf
charset = utf-8
spelling_language = en
trim_trailing_whitespace = true
insert_final_newline = true
quote_type = single
spaces_around_operators = true

check

npx @sheplu/editorconfig --mode=check

Validates your existing .editorconfig and reports any drift from the target configuration.

This command will:

• Read your existing .editorconfig
• Compare it against the tool’s canonical template
• Exit with:
  • 0 if everything matches
  • 1 if differences are found

--template (custom team template)

Both write and check accept a --template (or -t) flag pointing at a custom .editorconfig-syntax file. Sections in that file override the built-in defaults; languages it doesn't redefine still come from the built-ins. This lets a team host a single source of truth and reference it from every repo.

The flag accepts either a local path or an https:// URL:

# local file
npx @sheplu/editorconfig --mode=write --template=./team.editorconfig

# remote URL
npx @sheplu/editorconfig --mode=check --template=https://raw.githubusercontent.com/example/team-config/main/.editorconfig

The custom template must follow the same semantics as the built-ins:

• Use only known section headers ([*], [*.md], [*.{js,jsx,...}], etc.). Unknown headers (like [*.proto]) are rejected.
• Include root = true in the preamble whenever the template redefines [*].
• Each header may appear at most once.

URL fetching is constrained for safety: https:// only (http:// is rejected before any network call), redirects must stay on https (max 5 hops), 10-second timeout, 1 MB response cap. Templates are fetched on every invocation — there is no local cache.

--help

npx @sheplu/editorconfig --help

Prints the full usage, the available commands, and every supported option.

Planned / Upcoming Features

1. Interactive update / replace

npx @sheplu/editorconfig --mode=fix

2. Compare with target setup

npx @sheplu/editorconfig --mode=diff

Roadmap

• [ ] Add diff logic and diff command
• [ ] Add interactive fix / update command
• [ ] Expose presets or configuration options

Additional properties can be found on the editorconfig wiki.

Tests

Tests live under test/ and are split by scope:

• test/unit/ — fast, in-process tests of exported functions (no spawning, no I/O beyond a tmp dir).
• test/integration/ — full CLI runs. The interactive prompt path is exercised in a real pseudoterminal via node-pty; the rest go through child_process.spawnSync with a closed stdin.

Run them with:

npm test                  # everything
npm run test:unit         # unit only — runs in ~50ms
npm run test:integration  # integration only — spawns the CLI
npm run test:coverage.    # coverage with 95% threshold
npm run lint              # oxlint

CI runs lint, audit, and the full suite on every PR across Node 24 / 26.

Documentation

Editorconfig documentation