Skip to content
xtarter
Blog

CLI Overview

xtarterize detects, applies, and maintains conformance configuration for JavaScript and TypeScript projects.

Global options

Section titled “Global options”

Flags follow the command name: xtarterize check --json works, xtarterize --json check is rejected.

Option Commands Description
--cwd <path> all Target directory (default: current directory)
--json all Output machine-readable JSON
--quiet all except query Suppress prompts and verbose output; restore still prompts for a backup unless --yes
--help all Show help for a command
--version entry Show the version number

Commands

Section titled “Commands”
Command Description
init Full conformance setup: detect, plan, apply
sync Update existing configs to the latest templates
diff Show pending changes without applying
check Audit current conformance status
doctor Run environment, tool, and project diagnostics
add [task-id] Apply one task, or pick interactively
undo Undo the last run by restoring backed-up files
restore <file> Restore one file from backup
list List available tasks with their status
query Search tasks by natural language query

Exit codes

Section titled “Exit codes”

0 means success; 1 means the command found something that needs attention. check, diff, and doctor work as CI gates.

Command Exits 1 when
check A task is non-conformant or a diagnostic fails
diff, init --dry-run, sync --dry-run A change is pending or a dry run fails
doctor A diagnostic fails
init, sync A task fails to apply (unknown --only or --skip IDs do not fail the run; unknown IDs in the selection config warn)
add The task ID is unknown or the task fails to apply
undo, restore Nothing to restore, or a restore fails

Unknown commands and options exit 1 before anything runs and suggest a correction when one is close.

In GitHub Actions, check also writes one ::error annotation per non-conformant task and per failing diagnostic, forced with --annotations or enabled automatically in CI. Annotations go to stderr, so --json and --badge - output stays machine-readable.

doctor

Section titled “doctor”

Run diagnostics for the environment, declared tools, project files (tsconfig.json, README.md, .gitignore), and conflicting configurations such as Biome with ESLint or Prettier. Options: --verbose (adds system information), --quiet (summary only), --json.

Terminal window
npx xtarterize@latest doctor

init

Section titled “init”

Detect the project stack, show a plan, and apply changes.

Option Description
--dry-run Preview changes without applying
--yes Skip confirmations
--compose <query> Rank tasks by relevance to a query
--threshold <n> Minimum score for --compose (0-1, default 0.1)
--skip <task-id> Exclude tasks (comma-separated)
--only <task-id> Apply only these tasks (comma-separated)
--include-conflicts Apply conflicting tasks too
--format <format> Output format: terminal or json
--timing Show per-task timing
Terminal window
npx xtarterize@latest init

sync

Section titled “sync”

Update existing configs to match the latest templates. Unlike init, only tasks in patch or conflict status are offered, and --compose and --threshold are not supported. All other init options apply.

Terminal window
npx xtarterize@latest sync

diff

Section titled “diff”

Preview changes for new, patch, and conflict tasks without writing any conformance files; the project .gitignore may still be created or updated. New files are shown in full; patched files use unified diffs. Changes to the same JSON file are merged into one diff.

Options: --format <terminal|json>.

Terminal window
npx xtarterize@latest diff

check

Section titled “check”

Audit which tasks are conformant and report conflicting tools, legacy ESLint configs, and missing tool installations.

Option Description
--badge <path> Write a conformance badge SVG (- for stdout)
--annotations Emit GitHub Actions annotations (auto-enabled in CI)
Terminal window
npx xtarterize@latest check

add

Section titled “add”

Apply one task, or show a grouped multi-select menu when no task ID is given.

Option Description
--all Apply all new and patch tasks without prompting
--include-conflicts Apply conflicting tasks too
--format <format> Output format: terminal or json
--timing Show per-task timing
Specific task
npx xtarterize@latest add lint/biome

undo

Section titled “undo”

Undo the last init, sync, or add run. Backed-up files are restored, and files the run created are deleted.

Options: --quiet, --json, --format <terminal|json>.

Terminal window
npx xtarterize@latest undo

restore

Section titled “restore”

Restore one file from a previous backup. If several backups exist, xtarterize prompts for one; --yes restores the latest.

Options: --yes, --quiet, --json, --format <terminal|json>.

Terminal window
npx xtarterize@latest restore tsconfig.json

list

Section titled “list”

List available tasks grouped by category, with their current status.

Options: --quiet, --json.

query

Section titled “query”

Search tasks by natural language query. Options: --limit <n> (default 20), --threshold <n> (default 0.1), --json. See the query command page.

Terminal window
npx xtarterize@latest query "strict typescript"

Task statuses

Section titled “Task statuses”

new means the config does not exist yet; patch means it needs updates; skip means it is conformant; conflict means it is incompatible and needs a decision.

Backups

Section titled “Backups”

Before modifying a file, xtarterize writes a timestamped backup under .xtarterize/backups/ and records the run in last-run.json. The .xtarterize/ directory is added to .gitignore. Use undo to revert a whole run, or restore <file> for one file.

See the conformance tasks and the configuration guide.