Skip to content

Référence CLI ​

Référence complète de l'interface en ligne de commande Bear Craft.


Installation NPX ​

La méthode recommandée pour installer Bear Craft est via NPX :

bash
npx @the-bearded-bear/bear-craft [commande] [options]

Commandes Disponibles ​

CommandeDescription
installInstaller Bear Craft dans un projet
flattenGénérer un contexte aplati du codebase
(aucune commande)Assistant d'installation interactif

Assistant Interactif ​

Exécutez sans arguments pour l'assistant interactif :

bash
npx @the-bearded-bear/bear-craft

L'assistant vous guidera à travers :

  1. Répertoire cible - Où installer
  2. Stack technologique - Quel(s) framework(s) utiliser
  3. Langue - Langue de la documentation (en, fr, es, de, pt)
  4. Options - Sauvegarde, écrasement forcé, etc.

Commande Install ​

Usage de Base ​

bash
npx @the-bearded-bear/bear-craft install <répertoire-cible> [options]

Options ​

OptionRaccourciDescription
--tech=<technologie>-tStack technologique à installer
--lang=<langue>-lLangue de la documentation
--force-fÉcraser les fichiers existants
--backup-bCréer une sauvegarde avant installation
--dry-run-dSimuler sans effectuer de changements
--preserve-configConserver le CLAUDE.md existant

Options de Technologie ​

ValeurDescription
symfonyBackend Symfony/PHP
flutterMobile Flutter/Dart
reactFrontend React
reactnativeMobile React Native
pythonBackend Python
angularFrontend Angular
csharpBackend C#/.NET
laravelBackend Laravel/PHP
vuejsFrontend Vue.js
phpPHP Clean Architecture
commonRègles communes uniquement
allToutes les technologies

Options de Langue ​

ValeurLangue
enAnglais (défaut)
frFrançais
esEspagnol
deAllemand
ptPortugais

Exemples ​

bash
# Installer les règles Symfony en français
npx @the-bearded-bear/bear-craft install ~/mon-projet --tech=symfony --lang=fr

# Installer plusieurs technologies
npx @the-bearded-bear/bear-craft install . --tech=react
npx @the-bearded-bear/bear-craft install . --tech=python

# Forcer la réinstallation avec sauvegarde
npx @the-bearded-bear/bear-craft install ~/app --tech=flutter --force --backup

# Dry run pour prévisualiser les changements
npx @the-bearded-bear/bear-craft install . --tech=angular --dry-run

# Installer toutes les technologies
npx @the-bearded-bear/bear-craft install ~/projet --tech=all --lang=fr

Commande Flatten ​

Génère un résumé aplati de votre codebase pour les assistants IA.

Usage ​

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

Options ​

OptionDescription
--output=<fichier>Nom du fichier de sortie (défaut : CODEBASE.md)
--max-tokens=<n>Tokens maximum avant fragmentation
--exclude=<patterns>Patterns additionnels à exclure

Exemples ​

bash
# Générer le codebase aplati
npx @the-bearded-bear/bear-craft flatten

# Fichier de sortie personnalisé
npx @the-bearded-bear/bear-craft flatten --output=CONTEXT.md

# Limiter le nombre de tokens (active la fragmentation pour les grands projets)
npx @the-bearded-bear/bear-craft flatten --max-tokens=50000

# Exclure des répertoires additionnels
npx @the-bearded-bear/bear-craft flatten --exclude="*.test.ts,*.spec.ts"

Sortie ​

La commande flatten génère :

  • Structure de l'arborescence des fichiers
  • Contenu des fichiers par ordre de priorité
  • Estimation des tokens
  • Fragmentation automatique pour les grands projets

Commandes Makefile ​

Quand vous clonez le dépôt, vous pouvez utiliser Make pour l'installation.

Commandes d'Installation ​

bash
# Installer une technologie spécifique
make install-symfony TARGET=~/projet
make install-flutter TARGET=~/projet RULES_LANG=fr
make install-react TARGET=~/projet OPTIONS="--force"

# Installer des presets
make install-all TARGET=~/projet         # Tout
make install-common TARGET=~/projet      # Règles communes uniquement
make install-web TARGET=~/projet         # React
make install-backend TARGET=~/projet     # Symfony + Python
make install-mobile TARGET=~/projet      # Flutter + React Native

# Installer les outils
make install-tools                        # Tous les outils
make install-statusline                   # Ligne de statut personnalisée
make install-multiaccount                 # Gestionnaire multi-comptes
make install-projectconfig                # Gestionnaire de config projet

Commandes Dry Run ​

bash
make dry-run-all TARGET=~/projet
make dry-run-symfony TARGET=~/projet
make dry-run-flutter TARGET=~/projet

Commandes de Configuration ​

bash
make config-list                          # Lister les projets dans la config YAML
make config-validate                      # Valider la config YAML
make config-install PROJECT=mon-projet    # Installer depuis la config
make config-install-all                   # Installer tout depuis la config
make config-dry-run PROJECT=mon-projet    # Dry run depuis la config

Commandes Utilitaires ​

bash
make help                                 # Afficher toutes les commandes disponibles
make list                                 # Lister les composants disponibles
make list-agents                          # Lister tous les agents
make list-commands                        # Lister toutes les commandes
make stats                                # Afficher les statistiques
make tree                                 # Afficher la structure du projet
make fix-permissions                      # Corriger les permissions des scripts

Commandes de Migration ​

bash
make migrate-check                        # Vérifier le statut de migration

Export Plugin ​

bash
make plugin-export-all                     # marketplaces/<lang>/plugins/bear-<ns>/ (generated)
make plugin-check                          # marketplaces/ in sync with the installers

Exécution Directe des Scripts ​

Pour un contrôle avancé, exécutez les scripts d'installation directement.

Syntaxe ​

bash
./Dev/scripts/install-{tech}-rules.sh [options] <répertoire-cible>

Scripts Disponibles ​

ScriptTechnologie
install-common-rules.shCommun/transversal
install-symfony-rules.shSymfony
install-flutter-rules.shFlutter
install-react-rules.shReact
install-reactnative-rules.shReact Native
install-python-rules.shPython
install-angular-rules.shAngular
install-csharp-rules.shC#/.NET
install-laravel-rules.shLaravel
install-vuejs-rules.shVue.js
install-php-rules.shPHP

Options des Scripts ​

OptionDescription
--installInstallation fraîche (défaut)
--updateMettre à jour les fichiers existants uniquement
--forceÉcraser tous les fichiers
--preserve-configConserver CLAUDE.md et contexte projet
--dry-runSimuler sans changements
--backupCréer une sauvegarde avant changements
--interactiveInstallation guidée
--lang=XXDéfinir la langue (en, fr, es, de, pt)
--agents-onlyInstaller uniquement les agents
--commands-onlyInstaller uniquement les commandes
--rules-onlyInstaller uniquement les règles
--templates-onlyInstaller uniquement les templates
--checklists-onlyInstaller uniquement les checklists

Exemples ​

bash
# Installation de base
./Dev/scripts/install-symfony-rules.sh --lang=fr ~/mon-projet

# Mettre à jour une installation existante
./Dev/scripts/install-flutter-rules.sh --update ~/mon-app

# Forcer la réinstallation avec sauvegarde
./Dev/scripts/install-python-rules.sh --force --backup ~/api

# Mode interactif
./Dev/scripts/install-react-rules.sh --interactive ~/frontend

# Installer uniquement les agents
./Dev/scripts/install-symfony-rules.sh --agents-only ~/projet

Ralph Wiggum CLI ​

Exécute Claude en boucle continue jusqu'à l'achèvement de la tâche.

Usage ​

bash
npx @the-bearded-bear/bear-craft ralph "description de la tâche"

Options ​

OptionDescription
--fullActiver tous les validateurs DoD
--max-iterations=<n>Nombre maximum d'itérations (défaut : 10)
--dod=<fichier>Fichier de configuration DoD personnalisé

Exemples ​

bash
# Tâche de base
npx @the-bearded-bear/bear-craft ralph "Implémenter l'authentification utilisateur"

# Avec toutes les vérifications DoD
npx @the-bearded-bear/bear-craft ralph --full "Corriger le bug de connexion"

# Limite d'itérations personnalisée
npx @the-bearded-bear/bear-craft ralph --max-iterations=20 "Refactorer le module de paiement"

Commande Kanban ​

Lance une interface web locale pour visualiser et gérer le backlog et les sprints BMAD v6 sous forme de tableau Scrum / Kanban. Le serveur écoute exclusivement sur 127.0.0.1 et ne sollicite jamais Internet.

Utilisation ​

bash
npx @the-bearded-bear/bear-craft kanban [chemin] [options]

Le chemin est par défaut le répertoire courant. La cible doit contenir un sous-dossier project-management/ (généré par /bear-workflow:plan ou /bear-workflow:start).

Options ​

OptionDescription
--port=<n>Port HTTP, de 1024 à 65535 (défaut : 3737). La forme avec = est obligatoire : --port 4000 (avec une espace) est refusé avec un message d'usage
--openOuvre automatiquement le navigateur
--readonlyDésactive toute écriture : le serveur répond 403 readonly à chaque PATCH, PUT, POST et DELETE, et le tableau n'offre aucun contrôle de déplacement
--no-watchDésactive le watcher de fichiers (pas de rechargement lors des modifications externes)
--user=<nom>Auteur inscrit dans l'history des modifications faites depuis le tableau (kanban:<nom>). Par défaut : BEAR_CRAFT_USER, puis git config user.name, puis l'utilisateur du système, puis kanban

Vues ​

Six vues, listées dans la barre de navigation.

  • Board — 6 colonnes (backlog, ready-for-dev, in-progress, review, done, blocked). Une carte se déplace par glisser-déposer ou avec le menu « Déplacer » de la carte, qui ne propose que les colonnes autorisées (alternative au clavier et au pointeur unique). Les gates (INVEST ou points, tâches complètes, phase TDD) sont validés côté serveur. L'en-tête de colonne affiche le nombre de cartes, ou nombre/limite lorsqu'une limite WIP est définie.
  • Backlog — arbre des epics avec la progression de chacun. On sélectionne une ou plusieurs stories pour les ajouter à un sprint, ou les remettre au backlog ; une barre de capacité compare les points engagés à la capacité du sprint cible.
  • Sprints — tous les sprints (planifiés, actif, clos) avec objectif, dates, points, stories et tâches dépliables, ainsi que leurs notes de revue et de rétrospective. On y crée, démarre et clôture les sprints.
  • Burndown — courbes idéale et réelle du sprint actif, indicateur on-track / at-risk / behind. Le graphique de vélocité (points engagés et livrés des sprints clos, moyenne des trois derniers, prévision du nombre de sprints restants) est accompagné d'un tableau équivalent.
  • Dependencies — graphe orienté des dépendances entre stories, cycles en évidence, et tableau équivalent (story, dépend de, bloque, statut, cycle).
  • Docs — visualiseur markdown de prd.md, tech-spec.md, personas.md, architecture/*.md et des documents d'epics, de stories et de sprints. Les identifiants US-XXX du texte renvoient à la story.

Ce que l'on peut faire depuis le tableau ​

  • Déplacer une story entre colonnes. Les transitions autorisées figurent dans Machine d'états ; bloquer une story demande une raison.
  • Créer, modifier et supprimer une story (« Nouvelle story » dans les vues Board et Backlog ; le formulaire se trouve dans le détail de la story). Champs modifiables : titre, epic, points, priorité, assigné, sprint, phase TDD et dépendances ; persona à la création. La suppression demande confirmation et déplace le fichier dans project-management/backlog/user-stories/.trash/ (récupérable en le remettant en place). Une story en cours ou en revue exige une confirmation explicite, et une story dont d'autres dépendent ne peut pas être supprimée (409 has_dependents).
  • Ajouter, renommer, supprimer des tâches et changer leur statut (to-do, in-progress, done, blocked) depuis le détail de la story (une tâche se renomme sur place : Entrée enregistre, Échap annule ; la suppression demande une seule confirmation) ; le nombre de tâches terminées est recalculé. Une story ne passe en revue qu'une fois qu'elle a des tâches, toutes terminées. Pour une story qui n'avait qu'un compteur de tâches, la première modification enregistre un statut par tâche (les premières tâches, autant que le compteur en indiquait, comptent comme terminées).
  • Planifier un sprint : sélectionner des stories dans la vue Backlog et les ajouter à un sprint planifié ou actif.
  • Créer, démarrer et clôturer un sprint. La création (nom, dates de début et de fin, objectif, capacité) écrit sprints/sprint-<N>-<slug>/sprint-goal.md ; le sprint est « planifié ». Le démarrer en fait le sprint actif (refusé tant qu'un autre sprint est actif). La clôture archive les stories done sous archived_sprints et permet de choisir la destination des stories non terminées : retour au backlog ou report dans un sprint planifié.
  • Régler les limites WIP par colonne dans le panneau Réglages. Elles sont indicatives : un dépassement affiche un avertissement et ne bloque jamais un déplacement. Une colonne compte les stories du sprint actif, comme le tableau les affiche.
  • Saisie non enregistrée protégée : fermer un formulaire (Échap, Annuler, clic hors de la fenêtre) ou changer d'URL (retour arrière, lien vers une story) alors qu'un formulaire de story ou de sprint contient des modifications demande confirmation avant de les abandonner.
  • Rechercher, filtrer et trier : la zone de recherche (Ctrl+K ou /) filtre les vues Board et Backlog ; les filtres de priorité, d'assigné et d'epic ainsi que le tri sont conservés dans l'URL, par exemple #/kanban?q=auth&prio=must,should&who=alice&epic=E4&sort=priority&dir=desc. ?story=US-E4-03 ouvre une story depuis n'importe quelle vue, et #/docs/<chemin> ouvre un document.
  • Langue de l'interface : anglais, français, espagnol, allemand ou portugais, choisie automatiquement d'après le navigateur ou dans le panneau Réglages. Les titres de stories et les documents restent tels qu'écrits.

Les commandes /bear-workflow:* et /bear-project:* restent valables et écrivent les mêmes fichiers.

Où les données sont écrites ​

DonnéeFichier
Statut, appartenance à un sprint, tâches, points, assigné, priorité, historique.bmad/sprint-status.yaml
Contenu d'une story (description, critères d'acceptation, persona)project-management/backlog/user-stories/US-*.md
Objectif d'un nouveau sprintproject-management/sprints/sprint-<N>-<slug>/sprint-goal.md
Limites WIP.bmad/kanban.yaml
Stories suppriméesproject-management/backlog/user-stories/.trash/

Les fichiers markdown ne reçoivent jamais de ligne de statut. Les clés optionnelles stories.<id>.sprint_id et metadata.closed_date sont décrites dans Project/i18n/fr/templates/sprint-status.md.

Concurrence ​

  • Les écritures dans .bmad/sprint-status.yaml prennent le même verrou que les scripts .bmad/lib/ (status-lock.sh). Tant qu'un script le détient, le tableau répond 423 locked ; un verrou laissé par un processus interrompu est repris au bout de 10 secondes.
  • Les conflits sont détectés story par story : chaque story porte une révision, renvoyée dans If-Match. Une story modifiée ailleurs entre-temps est refusée avec 409 conflict, et l'interface propose de la recharger.
  • Le fichier est réécrit après revalidation, commentaires, ordre des clés et mise en forme préservés. Un fichier qui ne valide pas n'est jamais écrasé (409 sprint_status_invalid).

Sécurité ​

  • Écoute exclusivement sur 127.0.0.1, jamais 0.0.0.0 ni le réseau local.
  • L'en-tête Host doit être l'adresse de bouclage et le port servi (protection contre le DNS rebinding) ; l'Origin est vérifié à chaque écriture, et les écritures inter-origines sont refusées (403).
  • Corps de requête limités à 64 Ko (512 Ko pour le corps d'une story).
  • --readonly bloque toute écriture.
  • Traversée de chemin bloquée sur le point d'accès aux documents ; les réponses d'erreur ne contiennent aucun chemin du système de fichiers.
  • Écritures atomiques (verrou, fichier temporaire, renommage).
  • CSP stricte (script-src 'self', connect-src 'self'), aucun eval, aucune exécution de shell, aucun appel sortant.

Machine d'états ​

Transitions autorisées (toutes les autres sont refusées avec 409 invalid_transition et la liste des cibles permises) :

backlog       -> ready-for-dev (invest_score >= 6 s'il existe, sinon story_points > 0) | blocked
ready-for-dev -> in-progress | backlog | blocked
in-progress   -> review (toutes les tâches terminées) | blocked
review        -> done (toutes les tâches + tdd_phase parmi green|refactor|done) | in-progress | blocked
blocked       -> previous_status (déblocage uniquement)
done          -> (terminal)

Source sprint-status BMAD v6 ​

Les stories viennent de .bmad/sprint-status.yaml (écrit par /bear-workflow:* et /bear-project:backlog) et des fichiers markdown de project-management/. Quand une story est suivie dans la YAML, la YAML l'emporte pour le statut, le titre, les points, la priorité, l'assigné, l'epic, les tâches et le sprint ; le markdown garde le contenu. Le tableau est mis à jour en direct dès que l'une des sources change. Les stories d'un sprint clos (archived_sprints) sont en lecture seule.

Si le tableau est vide ou qu'une story manque, le bandeau de diagnostics liste les fichiers illisibles ; la même liste est renvoyée par GET /api/diagnostics. Voir le dépannage.

Routes HTTP ​

Lectures (GET) : /api/health (ok, readonly, user, wip_limits), /api/diagnostics, /api/stories, /api/stories/:id, /api/dependencies, /api/docs, /api/docs/<chemin>, /api/sprints, /api/sprints/:id, /api/sprints/current, /api/velocity, /api/events (évènements serveur).

Écritures :

RouteRôleErreurs propres
PATCH /api/stories/:id/statusDéplacer une story (status, blocked_reason?, reason?)409 invalid_transition, archived, read_only_source, conflict
PATCH /api/stories/:idModifier titre, points, assigné, priorité, phase TDD, epic, sprint (null = backlog), dépendances400 invalid_payload ; 409 archived, sprint_not_found, conflict
PUT /api/stories/:id/bodyRemplacer le corps markdown (markdown, expected_mtime)409 no_backing_file, conflict ; 422 status_line_forbidden
POST /api/storiesCréer une story (title, epic_id?, story_points?, priority?, persona?, sprint_id?)409 sprint_status_missing, sprint_status_invalid, sprint_not_found
DELETE /api/stories/:id[?force=1]Déplacer une story dans .trash/409 story_active, has_dependents, archived
PATCH /api/stories/:id/tasks/:taskIdChanger le statut d'une tâche et/ou la renommer (status?, title?, au moins un ; 1 à 200 caractères)400 invalid_payload ; 404 task_not_found ; 409 task_exists (nom d'une autre tâche), conflict
DELETE /api/stories/:id/tasks/:taskIdRetirer une tâche (total et completed sont recalculés)404 task_not_found ; 409 conflict
POST /api/stories/:id/tasksAjouter une tâche à faire (title)409 task_exists
POST /api/sprintsCréer un sprint planifié409 sprint_exists
POST /api/sprints/:id/startDémarrer un sprint409 sprint_already_active, sprint_closed, conflict
POST /api/sprints/:id/closeClôturer un sprint (carry_over : backlog ou un identifiant de sprint)409 not_active, sprint_not_found, conflict
PUT /api/settings/wipDéfinir les limites WIP (statut → 1..99 ou null)400 invalid_payload

:taskId est le nom actuel de la tâche, encodé pour l'URL (encodeURIComponent) : les noms contenant /, %, #, des espaces ou des caractères non ASCII sont pris en charge.

POST /api/stories, POST /api/stories/:id/tasks et POST /api/sprints acceptent un en-tête Idempotency-Key (chaîne opaque de 8 à 128 caractères ASCII visibles ; le board envoie un crypto.randomUUID() neuf à chaque ouverture de formulaire). Une seconde requête sur la même route avec la même clé dans les 5 minutes reçoit la réponse de la première (même statut, même corps, plus Idempotent-Replayed: true) et ne crée rien ; les requêtes refusées (statut 400 et plus) ne sont pas mémorisées, un nouvel essai est donc évalué de nouveau. La mémoire est celle du processus serveur, bornée à 500 clés. Une clé mal formée donne 400 invalid_idempotency_key.

Erreurs communes à toutes les écritures : 400 invalid_json / invalid_payload, 403 forbidden / readonly, 404 not_found, 413 payload_too_large, 423 locked, 500 write_failed. Les modifications sont poussées aux navigateurs ouverts par /api/events.

Raccourcis clavier (Board) ​

ToucheAction
↑ ↓Naviguer entre les cartes
← →Changer de colonne
Alt+MOuvrir le menu de déplacement de la carte active
1-6Déplacer la carte vers cette colonne (menu ouvert)
EntréeOuvrir le détail de la story
ÉchapFermer le menu ou la fenêtre
Ctrl+K (⌘+K) ou /Rechercher une story

Les raccourcis sont facultatifs : toutes les actions restent accessibles avec Tab et les boutons natifs.

Exemples ​

bash
# Lance sur le projet courant et ouvre le navigateur
npx @the-bearded-bear/bear-craft kanban --open

# Mode lecture seule
npx @the-bearded-bear/bear-craft kanban --readonly --port=4040

Fichier de Configuration ​

Configuration YAML ​

Pour les monorepos et configurations multi-projets, utilisez claude-projects.yaml :

yaml
settings:
  default_lang: "fr"

projects:
  - name: "mon-monorepo"
    description: "Mon application fullstack"
    root: "~/Projets/mon-monorepo"
    lang: "fr"
    common: true
    modules:
      - path: "frontend"
        tech: react
      - path: "backend"
        tech: symfony
      - path: "mobile"
        tech: flutter
      - path: "api"
        tech: [python, react]  # Technologies multiples

Variables d'Environnement ​

VariableDescriptionDéfaut
BEAR_CRAFT_LANGLangue par défauten
BEAR_CRAFT_TARGETRépertoire cible par défaut.
BEAR_CRAFT_CONFIGChemin du fichier de configclaude-projects.yaml

Codes de Sortie ​

CodeSignification
0Succès
1Erreur générale
2Arguments invalides
3Prérequis manquants
4Répertoire cible non trouvé
5Permission refusée

Dépannage ​

Problèmes de cache NPX ​

bash
# Vider le cache NPX
npx clear-npx-cache
# ou
rm -rf ~/.npm/_npx

Script non exécutable ​

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

Mauvaise version de yq ​

bash
# Bear Craft nécessite yq v4 (version de Mike Farah)
yq --version
# Doit afficher : yq (https://github.com/mikefarah/yq/) version v4.x.x

Optimisation des Tokens (RTK) ​

Configuration Automatique ​

bash
# Dans Claude Code, configurez toutes les optimisations en une commande
/bear-common:setup-rtk

Commandes RTK ​

CommandeDescription
rtk gainAfficher les économies de tokens
rtk gain --historyHistorique des commandes avec économies
rtk discoverAnalyser l'historique pour les opportunités manquées
rtk proxy <cmd>Exécuter une commande sans filtrage (debug)
rtk --versionVérifier la version installée

Commandes de Contexte Claude Code ​

CommandeDescription
/effort low|medium|highAjuster le niveau d'effort du modèle
/contextSuggestions d'optimisation du contexte
/compactCompacter proactivement le contexte
/clearNettoyer entre tâches non liées
/memoryApprentissages persistants (v2.1.59+)
/loop <intervalle> <cmd>Tâches récurrentes (v2.1.71+)
/model haiku|sonnet|opusChanger de modèle en session

Voir Aussi ​