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
--timing	Show detailed per-task timing breakdown
--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 task, or pick interactively
xtarterize undo	Undo the last run by restoring backed-up files
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
--format <format>	Output format (terminal or json)
--timing	Show detailed per-task timing breakdown

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
--format <format>	Output format (terminal or json)
--timing	Show detailed per-task timing breakdown

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
--format <format>	Output format (terminal or json)

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
--badge <path>	Generate a conformance badge SVG (use - for stdout)

npx xtarterize check
npx xtarterize check --verbose
npx xtarterize check --badge conformance.svg

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, or pick interactively from a grouped menu.

When called with a task ID, applies that specific task after showing a diff preview and confirmation. When called without a task ID, shows a grouped multi-select menu of all applicable tasks with their current status.

Options

Option	Description
--quiet	Suppress interactive prompts
--format <format>	Output format (terminal or json)
--timing	Show detailed per-task timing breakdown

Specific task

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

Interactive

npx xtarterize add

Browse tasks by category, select multiple, and apply with per-task confirmation.

undo

Undo the last init, sync, or add run by restoring all files that were backed up. Reads the run manifest (.xtarterize/backups/last-run.json) written during apply to identify which files to restore.

Options

Option	Description
--quiet	Skip confirmation prompt

npx xtarterize undo

Tip

The undo command restores all files from the most recent run in one step. For single-file restores, use xtarterize restore <file> instead.

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/. A run manifest (last-run.json) is also written so undo can restore all files from a run in one step.

Tip

Backups are stored with timestamps in .xtarterize/backups/ and indexed in .xtarterize/backups/.index.json. Use xtarterize undo to revert an entire run, or xtarterize restore <file> to revert a single file.

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 last| H[undo]
    H -->|single file| F[restore]
    B -->|view all| G[list]
    B -->|badge| I[badge SVG]

    style A fill:#6366f1,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#22c55e,color:#fff
    style H fill:#ef4444,color:#fff

References

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

Explore conformance tasks →