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-craftThe wizard will guide you through:
- Target directory - Where to install
- Technology stack - Which framework(s) to use
- Language - Documentation language (en, fr, es, de, pt)
- 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=enCheck 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-projectList 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-projectDoctor 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-projectUpdate 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 optimizerDry Run Commands
make dry-run-all TARGET=~/project
make dry-run-symfony TARGET=~/project
make dry-run-flutter TARGET=~/projectConfiguration 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 configUtility 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 permissionsMigration Commands
make migrate-check # Check migration statusPlugin Export
make plugin-export # Export as Claude Code plugin
make plugin-export-all # Export all technologiesDirect 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 ~/projectRalph 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"Kanban Command
Launch a local web UI to visualize the BMAD v6 project-management/ directory as a Scrum / Kanban board. The server binds to 127.0.0.1 only and never reaches out to the internet.
Usage
npx @the-bearded-bear/claude-craft kanban [path] [options]path defaults to the current working directory. The target must contain a project-management/ subdirectory (generated by /workflow:plan or /sprint:start).
Options
| Option | Description |
|---|---|
--port=<n> | HTTP port (default: 3737) |
--open | Open the default browser automatically |
--readonly | Disable all mutations (server blocks every PATCH with 403) |
--no-watch | Disable the file watcher (no live reload on external edits) |
Views
- Kanban — 6 columns (backlog, ready-for-dev, in-progress, review, done, blocked). Drag a card to transition a story. Gates (INVEST 6/6, DoD, task completion) are enforced server-side.
- Backlog — Epic tree (read-only) with per-epic progress.
- Burndown — ideal vs actual curve for the active sprint, on-track / at-risk / behind indicator.
- Dependencies — directed graph of inter-story dependencies, cycles highlighted in red.
- Docs — markdown viewer for
prd.md,tech-spec.md,personas.md,architecture/*.md. Inline[US-XXX]links jump to the corresponding card.
Examples
# Launch on the current project, open browser
npx @the-bearded-bear/claude-craft kanban --open
# Read-only mode for a demo or code review
npx @the-bearded-bear/claude-craft kanban --readonly --port=4040
# Against another project
npx @the-bearded-bear/claude-craft kanban ~/work/my-projectSecurity
- Bound to
127.0.0.1exclusively. No0.0.0.0, no LAN exposure. - CSRF-like same-origin check (Origin/Referer) on every PATCH — cross-origin mutations are rejected with 403.
- Path traversal blocked on the docs endpoint.
- File writes are atomic (exclusive lock + backup + rollback) with an ETag-like mtime check to avoid overwriting external edits.
- Strict CSP (
script-src 'self',connect-src 'self') on the served HTML. - No
eval, no shell execution, no outbound network.
State machine
Allowed transitions (all others rejected with 409):
backlog -> ready-for-dev (requires invest_score == 6) | blocked
ready-for-dev -> in-progress | backlog | blocked
in-progress -> review (all tasks completed) | blocked
review -> done (all tasks + tdd_phase in green|refactor|done) | in-progress | blocked
blocked -> previous_status (unblock only)
done -> (terminal)BMAD v6 sprint-status source (v8.11.0+)
When .bmad/sprint-status.yaml is present in the project root, the Kanban board ingests it as a read-only story source alongside the project-management/ directory.
| Behaviour | Detail |
|---|---|
| Source | .bmad/sprint-status.yaml — written by /workflow:* and /sprint:* commands |
| Display | Stories from the YAML appear with a 🔒 lock icon in all Kanban views |
| Mutability | Read-only. Any PATCH on a YAML-sourced story returns 409 Conflict |
| Coexistence | YAML stories and project-management/US-*.md stories coexist on the same board |
| Refresh | The file watcher (chokidar) triggers a live reload when the YAML is updated externally |
This design lets teams running the BMAD v6 workflow (which does not write individual US-*.md files) still benefit from the Kanban visualisation without any write risk to the sprint state managed by the AI workflow.
Claude Code Slash Commands
The following slash commands are available in Claude Code (v2.1.105+).
/btw
Quick questions without context switching, using minimal context and low effort.
Usage
/btw <question>Description
Ask a quick question without polluting the main conversation context. Uses minimal context window and low effort mode for fast responses. Ideal for simple lookups, factual questions, or quick clarifications that don't require full conversation history.
Examples
/btw What's the difference between bcrypt and argon2?
/btw How do I check my Node.js version?
/btw What does the --force flag do?/hooks
Interactive hook management interface.
Usage
/hooksDescription
Launch an interactive TUI for managing Claude Code hooks. Allows you to:
- View all installed hooks
- Enable/disable hooks
- Test hook execution
- Debug hook issues
- View hook output and errors
Examples
# Open hook management interface
/hooks/reload-plugins
Manually reload all Claude Code plugins.
Usage
/reload-pluginsDescription
Force a reload of all installed plugins without restarting Claude Code. Useful after:
- Installing new plugins
- Updating plugin configurations
- Debugging plugin issues
- Making changes to plugin files
Examples
# Reload all plugins
/reload-plugins/reload-skills
Re-scan all Claude Code skills without restarting the session (v2.1.157+).
Usage
/reload-skillsDescription
Force a re-scan of all installed skills (.claude/skills/) without restarting Claude Code. Distinct from /reload-plugins which reloads code intelligence plugins. Useful after:
- Adding a new skill to
.claude/skills/ - Modifying an existing skill file
- Installing Claude Craft updates that include new skills
SessionStart hook: A
SessionStarthook can returnreloadSkills: trueto make newly-installed skills available in the same session without user intervention.
Examples
# Reload all skills
/reload-skills/loop
Run a prompt or slash command repeatedly until you stop it — the time-based member of Claude Code's four loop types.
The four loop types (Anthropic taxonomy)
| Type | Trigger | Stops when | Best for |
|---|---|---|---|
| Turn-based | your prompt | Claude finishes or needs input | short, one-off tasks |
Goal-based (/goal) | your prompt | goal condition holds or max turns | tasks with a verifiable exit criterion |
Time-based (/loop, /schedule) | an interval | you cancel / work is done | recurring work, monitoring external systems |
| Proactive | event or schedule, no human in the loop | routine disabled | well-defined recurring streams (triage, migrations) |
Usage
/loop [interval] [prompt-or-command]- Interval mode:
/loop 5m …re-runs every 5 minutes (s/m/hsuffixes). Runs locally — the session must stay open. - Self-paced (dynamic) mode: omit the interval and Claude schedules its own next wake-up (
ScheduleWakeup), picking a delay matched to what it is waiting on. Ideal when the right cadence is not fixed. - Customisation: a
loop.mdfile lets you tune loop behaviour per project. - Combine with
/goalto give the loop a hard completion condition, and monitor cost/turns with/usage,/goal,/workflows.
Examples
# Fixed cadence: address review comments and fix CI every 5 min
/loop 5m check my PR, address review comments, and fix failing CI
# Self-paced: watch a deploy, waking when it makes sense
/loop watch the staging deploy and report when it is healthy or failed/schedule
Move a recurring job to the cloud as a Routine — it keeps running on a cron/event trigger after you close the session (unlike /loop, which is local). Use it for unattended nightly work: @qa:recette regression runs, /common:ralph-run-style completion loops, dependency-upgrade sweeps, PR triage. Pair with /goal (exit criteria), skills, and dynamic workflows for fully autonomous operation. Route judgement-heavy steps to capable models and mechanical steps to smaller/faster ones to control token cost.
/schedule # create / list / manage cloud routines/proactive
Alias for /loop - run a command on a recurring interval.
Usage
/proactive [interval] [command]Description
Execute a command or prompt repeatedly on a specified interval. This is an alias for the /loop command. If no interval is provided, the model will self-pace the iterations.
Examples
# Check deployment status every 5 minutes
/proactive 5m /status
# Run tests continuously with auto-pacing
/proactive npm test
# Monitor PR reviews every 10 minutes
/proactive 10m Check if there are new PR reviews/ultrareview
Parallel multi-agent code review of the current branch or a GitHub PR (available in Claude Code v2.1.111+).
Usage
/ultrareview # Review current branch
/ultrareview <PR#> # Review a GitHub PRDescription
Spawns multiple reviewer agents (security, architecture, performance, style) in parallel and aggregates findings. Cloud-based, billed separately. Requires a git repository (offer git init if not in one).
/goal (v2.1.139+)
Set a persistent session goal that Claude tracks until completion. A Stop hook activates and prevents Claude from stopping until the condition is met.
Usage
/goal <description>
/goal clearDescription
Defines an objective Claude must complete before the session ends. Useful for long-running tasks (audits, migrations, multi-file refactors) where you want Claude to self-direct until done. The goal is shown in the status line. Use /goal clear to remove it early.
Examples
/goal Write unit tests for all files in src/services/
/goal Migrate all Axios calls to the fetch API across the codebase
/goal clear/usage (v2.1.143+)
Display token usage statistics for the current session — input tokens, output tokens, cache reads, and estimated cost.
Usage
/usageDescription
Shows a breakdown of token consumption since session start: input tokens, cache read tokens, output tokens, and an estimated cost in USD. Since v2.1.149 the breakdown also attributes consumption per component — skill, subagent, plugin, and MCP server — so you can spot the costliest driver before deciding to delegate or /clear. Use before /clear to decide whether compaction is worth it.
/workflows (v2.1.154+)
Show the live progress tree for the current Dynamic Workflow run (ultracode mode).
Usage
/workflowsDescription
Displays a real-time view of all agents spawned by an active workflow, their phase assignments, completion status, and timing. Only meaningful when a Workflow tool call is in progress.
/tui
Switch the session to the terminal UI mode (available in v2.1.110+).
Usage
/tuiToggle via the tui setting in settings.json.
/recap
Summarize the current session progress (v2.1.108+). Useful before /clear to capture state.
Usage
/recap/undo
Alias for /rewind (v2.1.108+). Reverts the last change in the session.
Usage
/undo/effort
Interactive effort level slider (v2.1.111+). Pick the thinking depth: low, medium, high, xhigh (Opus 4.8, extended thinking), ultracode (v2.1.154+, Dynamic Workflows).
Usage
/effort # Interactive picker
/effort high # Set directly
/effort ultracode # Dynamic Workflows — max code throughput (trigger keyword: ultracode)Default for Pro/Max subscribers on Opus 4.8/Sonnet 4.6 is high since v2.1.111 (previously medium). Opus 4.8 supports the xhigh and ultracode tiers.
| Niveau | Modèle | Usage |
|---|---|---|
low | Haiku 4.5 (claude-haiku-4-5-20251001) | Tâches simples, lookups, classification |
medium | Sonnet 5 (claude-sonnet-5) | Implémentation standard |
high | Opus 4.8 (claude-opus-4-8) | Raisonnement complexe, architecture |
xhigh | Opus 4.8 (extended thinking, v2.1.111+) | Décisions critiques, migrations complexes, ADR |
ultracode | Opus 4.8 (v2.1.154+, Dynamic Workflows) | Mode débit code maximal — pipelines automatisés, génération massive |
⚠️ Note Fable 5 / Mythos 5 : ces modèles sont suspendus depuis le 2026-06-12 (directive export-control US, toujours offline). Ne pas configurer
CLAUDE_CODE_SUBAGENT_MODEL=claude-fable-5. Pour les agents créatifs/narratifs, utiliser Opus 4.8 (claude-opus-4-8) ou Sonnet 5 (claude-sonnet-5) en attendant une éventuelle restauration.
Claude Code Native Features (v2.1.108+)
Native CLI Binary (v2.1.113+)
Starting in v2.1.113, Claude Code spawns a native compiled binary instead of the bundled JavaScript. Faster startup, lower RAM footprint. No user action required — automatic when you update.
Forked Subagents (v2.1.117+)
Set CLAUDE_CODE_FORK_SUBAGENT=1 to run each subagent in an isolated, forked context. Prevents context pollution between parallel investigations.
export CLAUDE_CODE_FORK_SUBAGENT=1Prompt Caching Env Vars (v2.1.108+)
Fine-tune prompt caching behavior:
| Variable | Effect |
|---|---|
ENABLE_PROMPT_CACHING_1H | Use the 1-hour cache tier (vs 5-minute default) |
FORCE_PROMPT_CACHING_5M | Force the 5-minute tier even if 1h is available |
Use ENABLE_PROMPT_CACHING_1H=1 for long-running sessions with a stable context (e.g., architecture reviews that span hours).
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 technologiesEnvironment 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 |
CLAUDE_CODE_FORK_SUBAGENT | Fork each subagent in isolated context (v2.1.117+) | unset |
ENABLE_PROMPT_CACHING_1H | Use 1-hour prompt cache tier (v2.1.108+) | unset |
FORCE_PROMPT_CACHING_5M | Force 5-minute cache tier (v2.1.108+) | unset |
CLAUDE_CODE_SUBAGENT_MODEL | Model for subagents (e.g. claude-sonnet-5) | unset |
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/_npxScript not executable
chmod +x Dev/scripts/*.sh
# or
make fix-permissionsWrong 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