Commands

The two CLIs mirror each other. Where they differ, both columns are shown. JSON output uses snake_case in chisel and camelCase in chisel-js.

check

Scan a project for architectural violations. Non-zero exit on any ERROR-level violation.

Option	chisel	chisel-js
[path] default .	✅	✅
--json	✅	✅
--strict / --no-strict (default strict)	✅	❌ (project-structure rules always on)

Python

chisel check ./your-backend
chisel check ./your-backend --strict
chisel check ./your-backend --no-strict --json

TypeScript

chisel-js check ./your-frontend
chisel-js check ./your-frontend --json

Exit codes: 0 when no ERROR violations; non-zero otherwise. WARNINGs also block unless suppressed with a reason (see Turn off a rule for a file).

rules

List all rules grouped by category.

Option	chisel	chisel-js
--json	✅	✅

Python

chisel rules
chisel rules --json

TypeScript

chisel-js rules
chisel-js rules --json

explain

Print description + fix guidance for one rule, or every rule in a category.

Argument	Description
<rule-id>	e.g. structural:isinstance-banned
<category>	e.g. structural: expands to every rule in that category

Option	chisel	chisel-js
--json	✅	✅

Python

chisel explain structural:isinstance-banned
chisel explain structural

TypeScript

chisel-js explain component-enforcement:raw-button
chisel-js explain component-enforcement

init (TypeScript only)

Detect the project topology and write chisel.config.json. Run this once, before the first check.

Option	Description
[path] default .	Project to initialise
--mode <sveltekit-standalone|sveltekit-bff>	Set the mode instead of detecting it
--overwrite	Replace an existing chisel.config.json
--dry-run	Print the config that would be written
--json	Machine-readable output

chisel-js init
chisel-js init ./your-frontend --mode sveltekit-bff
chisel-js init --dry-run --json

Detection is a one-time step. check reads the mode from the file and never re-derives it, so adding a dependency can’t quietly change which rules run. If the signals conflict, init says so and picks sveltekit-standalone; pass --mode to settle it.

Without a config file check still works — it detects a mode, warns, and suggests running init.

chisel.config.json

Key	Description
mode	sveltekit-standalone or sveltekit-bff
tsconfig	Path to the tsconfig whose paths define the aliases. Default tsconfig.json
ignore	Extra globs to exclude from discovery
designSystem.allowIn	Folders exempt from the native-HTML ban — where vendored and generated components live

There are no rule toggles, by design. The config carries facts about the project, not decisions about which rules apply; an unknown key is an error rather than being silently ignored. If you need different rules, fork.

setup (Python only)

Install bundled skills into a repo. One target per run.

Option	Description
[path] default .	Project to install into
--target <codex|claude|opencode>	Destination directory
--skill <name> (repeatable)	Install only the named skills
--overwrite	Re-install over existing skills
--dry-run	Print what would change without writing
--json	Machine-readable output

chisel setup --target codex
chisel setup --target claude --skill qa --skill building-python-backend
chisel setup --target opencode --dry-run --json

The TypeScript CLI uses update skills for the same job; see below.

update skills

Overwrite installed skills with bundled copies. Same flags on both CLIs except --overwrite (Python only; update skills always overwrites).

Option	chisel	chisel-js
[path] default .	✅	✅
--target <codex|claude|opencode>	✅	✅
--skill <name> (repeatable)	✅	✅
-y / --yes	✅	✅
--dry-run	✅	✅
--json	✅	✅
--overwrite	✅	❌ (always overwrites)

Python

chisel update skills --target codex
chisel update skills --target claude -y --json

TypeScript

chisel-js update skills --target codex
chisel-js update skills --target claude -y --json

update self

Upgrade the installed CLI package.

Option	chisel	chisel-js
--manager <auto|pip|pipx|uv>	✅	❌
--manager <auto|npm|bun>	❌	✅
--dry-run	✅	✅

Python

chisel update self
chisel update self --manager uv --dry-run

TypeScript

chisel-js update self
chisel-js update self --manager bun --dry-run

JSON output shape

Python (`snake_case`)

{
  "violations": [
    { "file": "...", "line": 12, "rule_id": "...", "message_ref": "..." }
  ],
  "messages": [
    { "ref": "...", "rule_id": "...", "text": "...", "skill_name": "building-python-backend" }
  ]
}

TypeScript (`camelCase`)

{
  "violations": [
    { "file": "...", "line": 12, "ruleId": "...", "messageRef": "..." }
  ],
  "messages": [
    { "ref": "...", "ruleId": "...", "text": "...", "skillName": "building-sveltekit-frontend" }
  ]
}