CLI Reference

Complete reference for the Claude Craft command-line interface.

---

NPX Installation

The recommended way to install Claude Craft is via NPX:

npx @the-bearded-bear/claude-craft [command] [options]

Available Commands

Command	Description
install	Install Claude Craft to a project
init	Initialize workflow (shows instructions)
flatten	Generate flattened codebase context
ralph	Run Ralph Wiggum continuous loop
check	Verify claude-craft installation structure
list	Detailed component inventory
doctor	Environment diagnostics & health check
update	Refresh existing installation
help	Show help message
(no command)	Interactive installation wizard

---

Interactive Wizard

Run without arguments for the interactive wizard:

npx @the-bearded-bear/claude-craft

The wizard will guide you through:

1. Target directory - Where to install
2. Technology stack - Which framework(s) to use
3. Language - Documentation language (en, fr, es, de, pt)
4. Options - Backup, force overwrite, etc.

---

Install Command

Basic Usage

npx @the-bearded-bear/claude-craft install <target-directory> [options]

Options

Option	Short	Description
--tech=<technology>	-t	Technology stack to install
--lang=<language>	-l	Documentation language
--force	-f	Overwrite existing files
--backup	-b	Create backup before install
--dry-run	-d	Simulate without making changes
--preserve-config		Keep existing CLAUDE.md

Technology Options

Value	Description
symfony	Symfony/PHP backend
flutter	Flutter/Dart mobile
react	React frontend
reactnative	React Native mobile
python	Python backend
angular	Angular frontend
csharp	C#/.NET backend
laravel	Laravel/PHP backend
vuejs	Vue.js frontend
php	PHP Clean Architecture
common	Common rules only
all	All technologies

Language Options

Value	Language
en	English (default)
fr	French
es	Spanish
de	German
pt	Portuguese

Examples

# Install Symfony rules in French
npx @the-bearded-bear/claude-craft install ~/my-project --tech=symfony --lang=fr

# Install multiple technologies
npx @the-bearded-bear/claude-craft install . --tech=react
npx @the-bearded-bear/claude-craft install . --tech=python

# Force reinstall with backup
npx @the-bearded-bear/claude-craft install ~/app --tech=flutter --force --backup

# Dry run to preview changes
npx @the-bearded-bear/claude-craft install . --tech=angular --dry-run

# Install all technologies
npx @the-bearded-bear/claude-craft install ~/project --tech=all --lang=en

---

Check Command

Verify the structure of a claude-craft installation.

Usage

npx @the-bearded-bear/claude-craft check [target-directory]

Description

Scans the .claude/ directory and reports a summary of installed components: commands (by namespace), agents, references, skills, checklists, and templates.

Examples

# Check current directory
npx @the-bearded-bear/claude-craft check

# Check a specific project
npx @the-bearded-bear/claude-craft check ~/my-project

---

List Command

Display a detailed inventory of all installed claude-craft components.

Usage

npx @the-bearded-bear/claude-craft list [target-directory]

Description

Lists every installed component grouped by category (commands, agents, skills, references, checklists, templates) with counts and names. Useful for verifying what was installed and comparing across projects.

Examples

# List components in current directory
npx @the-bearded-bear/claude-craft list

# List components in a project
npx @the-bearded-bear/claude-craft list ~/my-project

---

Doctor Command

Run environment diagnostics and installation health checks.

Usage

npx @the-bearded-bear/claude-craft doctor [target-directory]

Description

Checks the development environment for required and recommended tools:

Check	Status
Node.js >= 20	[OK] / [FAIL]
npm	[OK] / [FAIL]
Claude Code	[OK] / [WARN]
git	[OK] / [FAIL]
yq	[OK] / [WARN]
.claude/ structure	[OK] / [WARN]
Shell script permissions	[OK] / [WARN]
i18n directories	[OK] / [WARN]

Examples

# Check current project
npx @the-bearded-bear/claude-craft doctor

# Check a specific project
npx @the-bearded-bear/claude-craft doctor ~/my-project

---

Update Command

Refresh an existing claude-craft installation by re-running install scripts.

Usage

npx @the-bearded-bear/claude-craft update [target-directory] [options]

Options

Option	Description
--tech=<technology>	Specific technology to update (if omitted, auto-detects from installed references)
--lang=<language>	Language override (default: en)

Description

Re-runs install scripts with --force to refresh all files. Common rules are always refreshed first, then tech-specific rules. If --tech is omitted, the command auto-detects installed technologies from .claude/references/.

Examples

# Update all detected technologies
npx @the-bearded-bear/claude-craft update ~/my-project

# Update only React rules in French
npx @the-bearded-bear/claude-craft update ~/my-project --tech=react --lang=fr

# Update current directory
npx @the-bearded-bear/claude-craft update .

---

Flatten Command

Generate a flattened summary of your codebase for AI assistants.

Usage

npx @the-bearded-bear/claude-craft flatten [options]

Options

Option	Description
--output=<file>	Output filename (default: CODEBASE.md)
--max-tokens=<n>	Maximum tokens before sharding
--exclude=<patterns>	Additional patterns to exclude

Examples

# Generate flattened codebase
npx @the-bearded-bear/claude-craft flatten

# Custom output file
npx @the-bearded-bear/claude-craft flatten --output=CONTEXT.md

# Limit token count (enables sharding for large codebases)
npx @the-bearded-bear/claude-craft flatten --max-tokens=50000

# Exclude additional directories
npx @the-bearded-bear/claude-craft flatten --exclude="*.test.ts,*.spec.ts"

Output

The flatten command generates:

• File tree structure
• Priority-ordered file contents
• Token estimation
• Automatic sharding for large projects

---

Makefile Commands

When you clone the repository, you can use Make for installation.

Installation Commands

# Install specific technology
make install-symfony TARGET=~/project
make install-flutter TARGET=~/project RULES_LANG=fr
make install-react TARGET=~/project OPTIONS="--force"

# Install presets
make install-all TARGET=~/project         # Everything
make install-common TARGET=~/project      # Common rules only
make install-web TARGET=~/project         # React
make install-backend TARGET=~/project     # Symfony + Python
make install-mobile TARGET=~/project      # Flutter + React Native

# Install tools
make install-tools                         # All tools
make install-statusline                    # Custom status line
make install-multiaccount                  # Multi-account manager
make install-projectconfig                 # Project config manager
make install-rtk                           # RTK token optimizer

Dry Run Commands

make dry-run-all TARGET=~/project
make dry-run-symfony TARGET=~/project
make dry-run-flutter TARGET=~/project

Configuration Commands

make config-list                           # List projects in YAML config
make config-validate                       # Validate YAML config
make config-install PROJECT=my-project     # Install from config
make config-install-all                    # Install all from config
make config-dry-run PROJECT=my-project     # Dry run from config

Utility Commands

make help                                  # Show all available commands
make list                                  # List available components
make list-agents                           # List all agents
make list-commands                         # List all commands
make stats                                 # Show statistics
make tree                                  # Show project structure
make fix-permissions                       # Fix script permissions

Migration Commands

make migrate-check                         # Check migration status

Plugin Export

make plugin-export                         # Export as Claude Code plugin
make plugin-export-all                     # Export all technologies

---

Direct Script Execution

For advanced control, run installation scripts directly.

Syntax

./Dev/scripts/install-{tech}-rules.sh [options] <target-directory>

Available Scripts

Script	Technology
install-common-rules.sh	Common/transversal
install-symfony-rules.sh	Symfony
install-flutter-rules.sh	Flutter
install-react-rules.sh	React
install-reactnative-rules.sh	React Native
install-python-rules.sh	Python
install-angular-rules.sh	Angular
install-csharp-rules.sh	C#/.NET
install-laravel-rules.sh	Laravel
install-vuejs-rules.sh	Vue.js
install-php-rules.sh	PHP

Script Options

Option	Description
--install	Fresh installation (default)
--update	Update existing files only
--force	Overwrite all files
--preserve-config	Keep CLAUDE.md and project context
--dry-run	Simulate without changes
--backup	Create backup before changes
--interactive	Guided installation
--lang=XX	Set language (en, fr, es, de, pt)
--agents-only	Install only agents
--commands-only	Install only commands
--rules-only	Install only rules
--templates-only	Install only templates
--checklists-only	Install only checklists

Examples

# Basic installation
./Dev/scripts/install-symfony-rules.sh --lang=fr ~/my-project

# Update existing installation
./Dev/scripts/install-flutter-rules.sh --update ~/my-app

# Force reinstall with backup
./Dev/scripts/install-python-rules.sh --force --backup ~/api

# Interactive mode
./Dev/scripts/install-react-rules.sh --interactive ~/frontend

# Install only agents
./Dev/scripts/install-symfony-rules.sh --agents-only ~/project

---

Ralph Wiggum CLI

Run Claude in a continuous loop until task completion.

Usage

npx @the-bearded-bear/claude-craft ralph "task description" [options]

Options

Option	Description
--full	Enable all DoD validators
--max-iterations=<n>	Maximum iterations (default: 10)
--dod=<file>	Custom DoD configuration file

Examples

# Basic task
npx @the-bearded-bear/claude-craft ralph "Implement user authentication"

# With full DoD checks
npx @the-bearded-bear/claude-craft ralph --full "Fix the login bug"

# Custom iteration limit
npx @the-bearded-bear/claude-craft ralph --max-iterations=20 "Refactor the payment module"

---

Configuration File

YAML Configuration

For monorepos and multi-project setups, use claude-projects.yaml:

settings:
  default_lang: "en"

projects:
  - name: "my-monorepo"
    description: "My fullstack application"
    root: "~/Projects/my-monorepo"
    lang: "fr"
    common: true
    modules:
      - path: "frontend"
        tech: react
      - path: "backend"
        tech: symfony
      - path: "mobile"
        tech: flutter
      - path: "api"
        tech: [python, react]  # Multiple technologies

Environment Variables

Variable	Description	Default
CLAUDE_CRAFT_LANG	Default language	en
CLAUDE_CRAFT_TARGET	Default target directory	.
CLAUDE_CRAFT_CONFIG	Config file path	claude-projects.yaml

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Missing prerequisites
4	Target directory not found
5	Permission denied

---

Troubleshooting

NPX cache issues

# Clear NPX cache
npx clear-npx-cache
# or
rm -rf ~/.npm/_npx

Script not executable

chmod +x Dev/scripts/*.sh
# or
make fix-permissions

Wrong yq version

# Claude Craft requires yq v4 (Mike Farah's version)
yq --version
# Should show: yq (https://github.com/mikefarah/yq/) version v4.x.x

---

See Also

• Quickstart Guide
• Prerequisites
• Installation Guide
• Commands Reference