Skip to content
xtarter
Blog

CLI Overview

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

Global Options

Section titled “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

Section titled “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
xtarterize query Search tasks by natural language query

Exit Codes

Section titled “Exit Codes”

The CLI follows the Unix convention: exit code 0 means success, 1 means the command found something that needs attention. This makes xtarterize usable as a CI gate.

Command Exit 0 Exit 1
check Fully conformant, no failing diagnostics Pending changes or failing diagnostics
diff No pending changes, all dry runs succeed At least one pending change, or a task failed to dry-run
doctor All diagnostics pass At least one diagnostic fails
add All requested tasks applied Task not found, or at least one task failed to apply
init / sync All updates applied At least one task failed to apply
init / sync with --dry-run No pending changes, all dry runs succeed At least one pending change (same contract as diff), or a task failed to dry-run
undo All files restored Nothing to undo, or at least one file failed to restore
restore File restored No backup found, or restore failed
Terminal window
# Fail CI when the project is not conformant
npx xtarterize check --quiet || exit 1

In GitHub Actions, check also emits native workflow command annotations — one ::error per non-conformant task (linked to the config file it would modify) and one per failing diagnostic — so failures appear inline on the PR. Annotations are written to stderr, so --json and --badge - output stays machine-readable:

CI annotations
npx xtarterize@latest check --annotations

doctor

Section titled “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

Section titled “Options”
Option Description
--verbose Show system information (OS, architecture, CPU count, RAM)
--quiet Suppress detailed output, show summary only
--json Output machine-readable JSON diagnostics
Terminal window
npx xtarterize@latest doctor
Verbose
npx xtarterize@latest 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

Section titled “init”

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

Options

Section titled “Options”
Option Description
--dry-run Preview all changes without applying
--yes Skip all confirmations, apply all changes automatically
--compose <query> Rank tasks by relevance to a natural language query
--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@latest init
Dry run
npx xtarterize@latest init --dry-run
Auto-apply
npx xtarterize@latest init --yes
Skip tasks
npx xtarterize@latest init --skip lint/oxlint
Only specific
npx xtarterize@latest init --only lint/biome,ts/incremental

sync

Section titled “sync”

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

Options

Section titled “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
Terminal window
npx xtarterize@latest sync
Dry run
npx xtarterize@latest sync --dry-run
Auto-apply
npx xtarterize@latest sync --yes

diff

Section titled “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

Section titled “Options”
Option Description
--quiet Suppress verbose output
--format <format> Output format (terminal or json)
Terminal window
npx xtarterize@latest diff

check

Section titled “check”

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

Options

Section titled “Options”
Option Description
--verbose Show tool installation and conflict checks
--quiet Suppress verbose output
--badge <path> Generate a conformance badge SVG (use - for stdout)
--annotations Emit GitHub Actions workflow command annotations (auto-enabled in CI)
Terminal window
npx xtarterize@latest check
Verbose
npx xtarterize@latest check --verbose
Badge
npx xtarterize@latest 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

Section titled “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

Section titled “Options”
Option Description
--quiet Suppress interactive prompts
--format <format> Output format (terminal or json)
--timing Show detailed per-task timing breakdown
--all Apply all applicable new and patch tasks without interaction
Specific task
npx xtarterize@latest add lint/biome
Interactive
npx xtarterize@latest add

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

All tasks
npx xtarterize@latest add --all

Apply all applicable new and patch tasks in one pass with no interaction.

undo

Section titled “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

Section titled “Options”
Option Description
--quiet Skip confirmation prompt
Terminal window
npx xtarterize@latest undo

restore

Section titled “restore”

Restore a file from a previous backup. If multiple backups exist, you’ll be prompted to select one. Use --yes to automatically restore the latest backup without prompting.

Arguments

Section titled “Arguments”
Argument Required Description
filepath Yes Path to the file to restore

Options

Section titled “Options”
Option Description
--yes Skip confirmation, restore latest backup when multiple exist
--quiet Suppress verbose output
Terminal window
npx xtarterize@latest restore tsconfig.json
Auto-restore
npx xtarterize@latest restore biome.json --yes
Quiet
npx xtarterize@latest restore tsconfig.json --quiet

list

Section titled “list”

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

Options

Section titled “Options”
Option Description
--quiet Suppress verbose output
Terminal window
npx xtarterize@latest list

query

Section titled “query”

Search tasks by natural language query. No need to remember exact task IDs - just describe what you’re looking for.

Options

Section titled “Options”
Option Description Default
--limit <n> Maximum number of results to show 20
--threshold <n> Minimum relevance score (0-1) 0.1
--json Output machine-readable JSON false
Terminal window
npx xtarterize@latest query "strict typescript"
JSON output
npx xtarterize@latest query "ci pipeline" --json
Limit results
npx xtarterize@latest query "linting and formatting tool" --limit 5

Task Status Values

Section titled “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

Section titled “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. The .xtarterize/ directory is automatically added to your project’s .gitignore, keeping internal artifacts out of version control.

Command Relationships

Section titled “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

Section titled “References”
Explore conformance tasks →