CLI Overview

The xtarterize CLI provides commands to detect, apply, and maintain conformance configuration for JavaScript/TypeScript projects.

Global Options

Option	Description
--cwd <path>	Target directory (default: current working directory)
--json	Output machine-readable JSON
--help	Show help for a command
--version	Show version number

Available Commands

Command	Description
xtarterize init	Full conformance setup — detect, plan, apply
xtarterize sync	Update existing configs to latest templates
xtarterize diff	Show pending changes without applying
xtarterize check	Audit current conformance status
xtarterize doctor	Run environment, tools, and project diagnostics
xtarterize add <task-id>	Apply a single conformance task
xtarterize restore <file>	Restore a file from backup
xtarterize list	List all available tasks with status

doctor

Run comprehensive project diagnostics. Checks are grouped into four categories:

Group	Checks
Environment	Node.js version against engines.node, Git installation
Tools	Required tools from package.json are installed (with version info)
Project	Lockfile, tsconfig.json, README.md, .gitignore
Configuration	Conflicting tool detection (e.g., Biome + ESLint/Prettier)

Options

Option	Description
--verbose	Show system information (OS, architecture, CPU count, RAM)
--quiet	Suppress detailed output, show summary only

npx xtarterize doctor
npx xtarterize doctor --verbose

With --verbose, a System group is added displaying platform, OS release, architecture, CPU count, and RAM:

  System
    ✅ Platform | Linux 6.8.0 | x64 | 16 CPUs | 32 GB RAM

  Environment
    ✅ Node.js 22.14.0 satisfies engines.node ^22.0.0
    ✅ Git 2.43.0 is installed

  Tools
    ✅ TypeScript 5.7.3 is installed
    ✅ Biome 1.9.4 is installed

  Project
    ✅ pnpm-lock.yaml exists
    ✅ tsconfig.json exists
    ⚠ README.md is missing

  Configuration
    ✅ No conflicting tools detected

All diagnostics also support --json for machine-readable output.

init

Full conformance setup. Detects your project stack, shows a plan, and applies changes.

Options

Option	Description
--dry-run	Preview all changes without applying
--yes	Skip all confirmations, apply all changes automatically
--skip <task-id>	Exclude a specific task (comma-separated)
--only <task-id>	Apply only a specific task (comma-separated)
--quiet	Suppress interactive prompts and verbose output

Basic

npx xtarterize init

Dry run

npx xtarterize init --dry-run

Auto-apply

npx xtarterize init --yes

Skip tasks

npx xtarterize init --skip lint/oxlint

Only specific

npx xtarterize init --only lint/biome,ts/incremental

sync

Update existing project configs to match the latest conformance templates. Only shows tasks with patch or conflict status.

Options

Option	Description
--dry-run	Preview changes without applying
--yes	Skip all confirmations, apply all updates automatically
--skip <task-id>	Exclude a specific task (comma-separated)
--only <task-id>	Apply only a specific task (comma-separated)
--quiet	Suppress interactive prompts and verbose output

npx xtarterize sync
npx xtarterize sync --dry-run
npx xtarterize sync --yes

Note

Unlike init, sync only targets tasks with patch or conflict status. It won’t re-apply already conformant configs.

diff

Show pending changes for all tasks with new, patch, or conflict status, without applying anything. Read-only. Uses unified diffs for patch comparisons.

Options

Option	Description
--quiet	Suppress verbose output

npx xtarterize diff

Tip

The diff command shows full file contents for new tasks (files that don’t exist yet) and unified diffs for patch tasks (existing files that need updates).

Note

When multiple tasks modify the same JSON file (e.g., tsconfig.json), diff merges their changes into a single unified diff so you see the complete intended state rather than overlapping individual patches.

check

Audit which tasks are conformant and which need attention. Also runs diagnostics for conflicting tools and missing installations.

Options

Option	Description
--verbose	Show tool installation and conflict checks
--quiet	Suppress verbose output

npx xtarterize check
npx xtarterize check --verbose

Output shows:

Icon	Status	Meaning
✔	skip	Conformant — no action needed
~	patch	Needs update — will be patched
✗	new	Missing entirely — will be created
⚠	conflict	Incompatible config — needs manual resolution

In verbose mode, check also displays diagnostics for:

• Conflicting tools — Biome + ESLint/Prettier detected together
• Legacy configs — ESLint flat config migration recommendations
• Tool installations — Tools in package.json but not installed locally

add

Apply a single conformance task.

Options

Option	Description
--quiet	Suppress interactive prompts

npx xtarterize add lint/biome
npx xtarterize add ci/release
npx xtarterize add codegen/plop

restore

Restore a file from a previous backup. If multiple backups exist, you’ll be prompted to select one.

npx xtarterize restore tsconfig.json
npx xtarterize restore biome.json

list

List all registered tasks grouped by category, with current status.

Options

Option	Description
--quiet	Suppress verbose output

npx xtarterize list

Task Status Values

Each task reports one of four statuses:

Status	Meaning
new	File/config doesn’t exist yet
patch	File exists but needs additions/updates
skip	Already conformant, nothing to do
conflict	Existing config is incompatible; requires decision

Backup System

Before any file is modified, xtarterize creates a timestamped backup in .xtarterize/backups/. You can restore any file using the restore command.

Tip

Backups are stored with timestamps in .xtarterize/backups/ and indexed in .xtarterize/backups/.index.json. Use xtarterize restore <file> to revert any change.

Command Relationships

flowchart TD
    A[init] -->|first run| B[check]
    A -->|preview| C[diff]
    B -->|find patches| D[sync]
    D -->|preview| C
    A -->|add one| E[add]
    A -->|undo| F[restore]
    B -->|view all| G[list]
    
    style A fill:#6366f1,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#22c55e,color:#fff

References

• GNU Diff Unified Format — How unified diffs work
• GitHub Actions Documentation — CI/CD workflow reference

Explore conformance tasks →