Skip to main content

CLI Commands

setup / init​

Launches the interactive wizard. init is an alias for setup.

npx @rtorcato/repo-tooling setup # current directory
npx @rtorcato/repo-tooling setup -d ./my-app # specific directory
npx @rtorcato/repo-tooling setup --skip-install # skip npm/pnpm install

Add --preset <name> to skip the wizard: minimal, library, web-app, node-api, nextjs-app, react-app, swift-library, vite-plus, or vite-plus-app. minimal is tsconfig + Biome + Vitest and nothing else. The Swift preset scaffolds a SwiftPM package rather than an npm one — see the Swift guide. The two Vite+ presets are opt-in and replace Biome, tsup and a separate Vitest — see the Vite+ guide.

In a terminal, --preset prints the file list it resolved and lets you uncheck the extras (git hooks, commitlint, releases, Dependabot/CodeQL, badges, AI agent rules) before anything is written. Pass --yes to write it all in one shot. When stdin or stdout is piped or redirected — CI — the review is skipped automatically.

copy <name>​

Copies a standalone config file into the current directory without running the full wizard.

npx @rtorcato/repo-tooling copy biome # → biome.json
npx @rtorcato/repo-tooling copy tsconfig # → tsconfig.json

Available presets: biome, tsconfig, bun, nx, changesets, release-please, oxlint, claude-skill, claude-sync-agents, mcp-example.

claude-sync-agents copies scripts/sync-agents.mjs, which regenerates AGENTS.md from skills/<package>/SKILL.md so the two can't drift. It is zero-config — the skill directory comes from the root package.json name with the npm scope stripped (@rtorcato/js-common → skills/js-common/). Wire node scripts/sync-agents.mjs --check into CI to fail on a stale AGENTS.md.

copy is for configs you must own rather than extend — Biome doesn't support configuration extension, and TypeScript configs resolve more reliably when local. Most other configs (ESLint, Prettier, Vitest, etc.) can be imported or extended directly — see the Configuration Reference for usage.

Copied assets don't drift silently​

A copy used to be a one-shot: nothing looked at the file again, so a repo could sit on an ancient copy of scripts/sync-changelog.mjs for a year without a signal. copy now records the asset's hash at copy time in .repo-tooling.json, and doctor's Copied assets check reads it back:

StateMeansdoctor
staleUntouched since the copy, but the package ships a newer versiondrift — fix copied-assets re-copies it, and can't lose anything, because nothing local is in it
modifiedThe file differs from what was copied — someone forked it deliberatelyreported, never overwritten; a human decision
untrackedNo recorded hash: the copy predates this, or the repo has no .repo-tooling.jsonreported, never drift — a missing record isn't evidence of drift

copy never creates a lockfile just to have somewhere to write. Run fix lockfile first if you want a repo's copies tracked.

list / ls​

Prints all available tooling configurations.

npx @rtorcato/repo-tooling list

doctor​

Audits an existing project against the presets and reports drift.

npx @rtorcato/repo-tooling doctor # current dir
npx @rtorcato/repo-tooling doctor -d ./app # specific dir
npx @rtorcato/repo-tooling doctor --json # machine-readable output
npx @rtorcato/repo-tooling doctor --offline # skip checks that read live GitHub state
npx @rtorcato/repo-tooling doctor --snapshot # write the live GitHub settings into rules.github

Each row reports one of:

StatusMeaning
okConfig matches the preset (or required file present)
driftConfig exists but has diverged from the preset
missingConfig required but not found
not configuredOptional tool not present in the project
skippedNot run — --offline skips checks that read live GitHub state

--offline for CI gates​

Some checks read live GitHub state over gh: branch protection, merge and security settings, the release environment, repository secrets, and milestones. Their result depends on timing (a milestone at 100% before it is closed) and on who runs them (a token without admin access can't read security settings). Pass --offline whenever doctor gates CI. Those checks then report skipped and never fail the run. Plain doctor still runs them. The composite action (uses: rtorcato/repo-tooling@vX.Y.Z) passes --offline for you.

What gets checked​

GroupChecks
EnvironmentNode (vs. minimum + LTS patch level), engines.node, Node version pin (.nvmrc / .node-version), Node version consistency (the pin, engines.node and workflow Node versions agree on one major)
Repo baselinepackage.json, EditorConfig, VS Code extensions (.vscode/extensions.json), Git identity (user.email is a real address), Git author history, Community health (CONTRIBUTING.md, SECURITY.md), Declared exceptions (rules.exceptions in .repo-tooling.json)
Tooling presetsTypeScript, Biome, ESLint, Prettier, Oxlint, Vitest, Commitlint
AutomationGit hooks, Pre-push hook, lint-staged, verify script, semantic-release, knip
CI / supply chainGitHub Actions, Release token (semantic-release needs RELEASE_TOKEN, with GITHUB_TOKEN as fallback), npm OIDC publish, npm trusted publisher, Dependabot, CodeQL, GitLab CI
Build / docsTypeDoc, size-limit, Tree-shake check
EcosystemBun runtime, Turborepo / Nx, Tailwind / PostCSS
GitHub (live, over gh)Branch protection, Merge settings, Workflow permissions, Code-scanning gate, Security updates, Release gate, Release environment, Release secrets, Repository secrets, Milestones

Release gate​

The Release gate check looks for the workflow job that publishes (semantic-release, changesets/action, changeset publish, or npm/pnpm/yarn publish) and reports drift when nothing holds it before the registry:

  • the job declares no environment: and the repo has no release environment
  • the job names an environment the repo doesn't have (Actions creates it unprotected on first run)
  • the job names an environment with no required reviewers

Release environment reports a release environment that no job references, and Release secrets reports publish secrets kept as repository secrets rather than on the environment. fix release-environment creates the environment with you as the required reviewer and adds environment: release to the job. It only runs when named.

A repo that publishes nothing is ok, reported as not applicable. A root package.json with private: true counts as publishing nothing, unless it is a monorepo root with a workspace package that isn't private. The workspace packages come from pnpm-workspace.yaml or the workspaces field. A pnpm or Changesets monorepo always has a private root while packages/* publish, so the check still runs there.

The npm OIDC publish and npm trusted publisher checks use the same publish matcher and the same private-root rule. In a monorepo, the trusted-publisher check reports one row per public workspace package, each prefixed with its directory. Running doctor -d packages/x on a single package reads the workflows and GitHub settings from the git root, since that's where they live.

After the per-row results, doctor prints a Next steps: footer listing the exact fix command to run for each non-ok item:

Next steps:
- Run `npx @rtorcato/repo-tooling fix engines` to align engines.node
- Run `npx @rtorcato/repo-tooling fix editorconfig` to scaffold EditorConfig
- Run `npx @rtorcato/repo-tooling fix dependabot` to scaffold Dependabot
- Run `npx @rtorcato/repo-tooling fix` to walk all findings interactively

Exits non-zero on drift or missing — useful as a CI gate.

fix [target]​

Applies scaffolders for items doctor flagged. Without a target it walks every non-ok result, prompting per item; with a target it applies just that one.

fix aligns an existing project; it doesn't create one. In an empty directory (nothing but dotfiles such as .git) the walk refuses and exits 1 with a pointer to setup --preset <name>, and doctor's next steps say the same.

npx @rtorcato/repo-tooling fix # walk all findings interactively
npx @rtorcato/repo-tooling fix dependabot # scaffold dependabot.yml + auto-merge workflow
npx @rtorcato/repo-tooling fix --yes # apply every recommended fix without prompts
npx @rtorcato/repo-tooling fix biome --dry-run # print what would change, write nothing
npx @rtorcato/repo-tooling fix biome --diff # show the exact diff before confirming

Flags​

FlagBehaviour
-d, --directory <path>Target directory (defaults to cwd)
--yesAssume yes to every prompt, including drift overwrites
--dry-runPrint the files each fixer would write, without writing
--diffPrint a unified diff of each change before the confirm prompt

Drift policy​

When a file exists but doesn't extend the preset, fix defaults the confirm prompt to No — your customisations are preserved unless you explicitly say yes (or pass --yes). The prompt always tells you which file is about to be overwritten.

Diff preview (--diff)​

When you want to see exactly what would change before saying yes, pass --diff. For each output the fixer would touch, you'll see:

  • a create <path> header if the file is new (no diff body to show), or
  • a modify <path> header followed by a unified diff comparing the current file to what the fixer would write.
$ npx @rtorcato/repo-tooling fix biome --diff
🔧 biome — Biome is drift

modify biome.json
--- biome.json
+++ biome.json
@@ -1,3 +1,12 @@
-{
- "rules": { "noConsole": "error" }
-}
+{
+ "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+ "extends": ["@rtorcato/repo-tooling/biome"],
+ …
+}
? ⚠️ Scaffold biome.json … — overwrite existing file? user customizations will be lost (y/N)

The diff:

  • is suppressed in --json mode (the structured output stream stays clean),
  • is suppressed for safe-add fixers (those never overwrite existing files),
  • honours NO_COLOR and the standard terminal-colour detection chalk uses,
  • works in both targeted (fix biome --diff) and walk-all (fix --diff) modes.

Implementation note: the preview is computed by shadow-running the fixer in a temp copy of your project directory — your real files are never touched until you confirm.

Available targets​

doctor and list --json are the source of truth — run them for the exact set in the version you have; new targets are added regularly. The current set:

Core config

TargetScaffolds
package-jsonadds @rtorcato/repo-tooling to devDependencies
enginesengines.node in package.json (never overwrites)
tsconfigtsconfig.json
biomebiome.json
eslinteslint.config.mjs
oxlint.oxlintrc.json (additive to Biome/ESLint; the Oxlint check)
prettierprettier.config.mjs
editorconfig.editorconfig
vscode-extensions.vscode/extensions.json (merge-friendly)
nvmrc.nvmrc pinned to Node 22
node-versionpoints CI at node-version-file: .nvmrc (one Node source of truth); an extra node-version: step in a job that already reads node-version-file is test coverage and is left alone

Testing & verify

TargetScaffolds
vitestvitest.config.ts (preserves existing vitest.setup.ts)
cypresscypress.config.ts + cypress/support + tests/e2e boilerplate
commitlintcommitlint.config.mjs
husky.husky/pre-commit, .husky/pre-push, package.json lint-staged (deep-merges)
verifyunified verify script (typecheck && lint && tests) in package.json
knipknip.json

Release

TargetScaffolds
semantic-releaserelease.config.mjs + plugins (skipped on private packages)
changesets.changeset/config.json (alternative to semantic-release)
release-pleaserelease-please-config.json + manifest + workflow (alternative)
release-environmentthe release environment on GitHub with you as required reviewer, plus environment: release on the publishing job (see Release gate). Runs only when named, never under bare fix or --yes
npm-trusted-publisherregisters release.yml as the package's OIDC trusted publisher on npm via npm trust github. Refuses when the package isn't on npm yet, local npm is older than 11.15.0, or you aren't logged in. Runs only when named. In a monorepo, run it once per package with -d packages/x
changesets-migratemoves a public package from semantic-release to Changesets. Runs only when named
attw@arethetypeswrong/cli + an attw script, wired into verify
publintpublint + a publint --strict script, wired into verify
badgesstatus-badge row (CI, npm, license) in README.md

CI & supply chain

TargetScaffolds
github-actions.github/workflows/ci.yml (+ release.yml for a semantic-release library; Vitest jobs run pnpm coverage). A ci.yml that still has a release job gets just that job moved out into release.yml (its environment: carried over, needs: references and the workflow_dispatch/milestone triggers only it used dropped) — every other job, trigger and comment in ci.yml stays byte-for-byte. Otherwise a ci.yml that no longer matches the preset is left as-is unless the finding being fixed is the GitHub Actions drift itself — your edits are never silently reverted
gitlab-ci.gitlab-ci.yml (lint/typecheck/test/build mirrored from GitHub Actions)
dependabot.github/dependabot.yml (monthly, grouped: production-minor/dev-minor/major-updates) + the dependabot-automerge.yml workflow — see Dependabot strategy
renovaterenovate.json (alternative to Dependabot)
codeql.github/workflows/codeql.yml (security scanning)
github-settingsbranch protection + auto-merge + workflow permissions + Dependabot vulnerability alerts, automated security fixes and private vulnerability reporting (the Security updates check) + a code-scanning branch ruleset (when CodeQL is on, the Code-scanning gate check) via gh api (mutates the remote repo). Applies rules.github when the repo declares it
milestonescloses 100%-complete open milestones, then opens a rolling next one if none is left, via gh api (mutates the remote repo). Never deletes one. Explicit-only, and refuses to close anything when a workflow, in the working tree or on the default branch, runs on milestone close, since that publishes — see milestone hygiene
codeowners.github/CODEOWNERS with commented examples
community-healthCONTRIBUTING.md, SECURITY.md, PR + issue templates
lockfilerecords current tool choices in the repo-tooling lockfile

Build, bundling & monorepo

TargetScaffolds
bunbunfig.toml + a Bun-typed tsconfig.json for Bun runtime/test users
rolluprollup.config.mjs re-exporting the shared library preset
rolldownrolldown.config.mjs re-exporting the shared library preset
size-limita size-limit budget (.size-limit.cjs/.json), plus the size script and the size-limit + @size-limit/preset-small-lib devDependencies that run it
treeshake-checkapps/treeshake-check — esbuild + metafile bundle assertion
pnpm-workspacemerges the shared pnpm settings into pnpm-workspace.yaml (verifyDepsBeforeRun, minimumReleaseAgeExclude, esbuild's build approval) — never rewrites the file
turborepoturbo.json task pipeline (pnpm-workspace monorepos)
nxnx.json task orchestrator (alternative to Turborepo)
tailwindTailwind CSS v4 (postcss.config.mjs + src/styles/globals.css)
postcsspostcss.config.mjs with autoprefixer (non-Tailwind pipelines)

Docs

TargetScaffolds
typedoctypedoc.json + .github/workflows/docs.yml (GitHub Pages)

AI agents (opt-in)

TargetScaffolds
aiall AI agent files at once (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill, MCP example)
claude-skillthe Claude Code skill at .claude/skills/repo-tooling/SKILL.md
cursor-rulesthe rules for Cursor at .cursor/rules/repo-tooling.mdc
copilot-instructionsthe rules block in .github/copilot-instructions.md
agents-mdthe rules block in AGENTS.md (universal)

Typical workflow​

npx @rtorcato/repo-tooling doctor # see what's missing
npx @rtorcato/repo-tooling fix # walk the list, accept defaults
npx @rtorcato/repo-tooling doctor # confirm everything is now ok