CLI Usage.fr

Utilisation CLI

La CLI de WorkPilot AI permet un usage sans interface graphique : serveurs headless, automatisation CI/CD, workflows terminal. Pour la plupart des utilisateurs, l'application de bureau offre une meilleure expérience — la CLI est conçue pour les cas avancés.

---

🎯 Quand utiliser la CLI ?

• Vous préférez le terminal
• Vous exécutez WorkPilot AI sur un serveur sans interface
• Vous intégrez WorkPilot AI dans des scripts ou une pipeline CI/CD
• Vous automatisez la gestion de nombreux projets

---

✅ Prérequis

• Python 3.12+
• Claude Code CLI : pnpm add -g @anthropic-ai/claude-code
• Git (dépôt initialisé sur le projet cible)

Installer Python

Windows

winget install Python.Python.3.12

macOS

brew install python@3.12

Linux (Ubuntu/Debian)

sudo apt install python3.12 python3.12-venv

Linux (Fedora)

sudo dnf install python3.12

---

⚙️ Setup

1. Se placer dans le backend

cd apps/backend

2. Préparer l'environnement Python

# Avec uv (recommandé)
uv venv && uv pip install -r requirements.txt

# Ou avec Python standard
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

3. Configurer l'environnement

cp .env-files/.env.example .env-files/.env

# Obtenir votre token OAuth
claude setup-token

# Ajouter dans .env-files/.env
# CLAUDE_CODE_OAUTH_TOKEN=votre-token

---

📝 Créer des specs

Toutes les commandes s'exécutent depuis apps/backend/ avec l'environnement virtuel activé.

source .venv/bin/activate

# Spec interactive
python runners/spec_runner.py --interactive

# Spec depuis une description
python runners/spec_runner.py --task "Ajouter l'authentification OAuth"

# Forcer un tier de complexité
python runners/spec_runner.py --task "Fix couleur bouton" --complexity simple

# Reprendre une spec interrompue
python runners/spec_runner.py --continue 001-feature

Tiers de complexité

Tier	Phases	Cas d'usage
SIMPLE	3	1-2 fichiers, aucune intégration
STANDARD	6	3-10 fichiers, 1-2 services
COMPLEX	8	10+ fichiers, multi-services, intégrations externes

---

🏃 Lancer des builds

# Lister toutes les specs et leur statut
python run.py --list

# Exécuter une spec spécifique
python run.py --spec 001
python run.py --spec 001-feature-name

# Limiter les itérations (tests)
python run.py --spec 001 --max-iterations 5

---

🧪 Validation QA

La validation QA se lance automatiquement après l'implémentation. Pour la contrôler :

# Skipper la QA automatique
python run.py --spec 001 --skip-qa

# Lancer la QA manuellement
python run.py --spec 001 --qa

# Voir le statut QA
python run.py --spec 001 --qa-status

Boucle de validation

1. QA Reviewer vérifie les critères d'acceptation
2. En cas d'échec → crée QA_FIX_REQUEST.md
3. QA Fixer applique les corrections
4. Boucle jusqu'à approbation (max 50 itérations)

---

🌳 Gestion des worktrees

WorkPilot AI utilise des git worktrees isolés :

# Tester la feature dans le worktree isolé
cd .worktrees/workpilot-ai/
npm run dev   # ou la commande de votre projet

# Revenir au backend pour commandes de gestion
cd apps/backend

# Voir les changements
python run.py --spec 001 --review

# Fusionner dans votre projet
python run.py --spec 001 --merge

# Jeter si ça ne convient pas
python run.py --spec 001 --discard

---

⏯ Contrôles interactifs

Pendant qu'un agent tourne :

# Pause + ajout d'instruction
Ctrl+C  (une fois)

# Sortie immédiate
Ctrl+C  (deux fois)

Alternative par fichier

# Créer un fichier PAUSE pour pauser après la session courante
touch specs/001-name/PAUSE

# Ajouter des instructions
echo "Focus d'abord sur le bug de login" > specs/001-name/HUMAN_INPUT.md

---

🔍 Validation de spec

python validate_spec.py --spec-dir specs/001-feature --checkpoint all

Vérifie :

• Critères d'acceptation mesurables
• Fichiers référencés existent
• Plan cohérent

---

🌍 Variables d'environnement

Copiez .env-files/.env.example vers .env-files/.env et configurez selon vos besoins.

Core

Variable	Requis	Description
CLAUDE_CODE_OAUTH_TOKEN	Oui	Token OAuth depuis claude setup-token
AUTO_BUILD_MODEL	Non	Modèle override (défaut : claude-opus-4-5-20251101)
DEFAULT_BRANCH	Non	Branche base pour worktrees (auto-détecte main/master)
DEBUG	Non	Active les logs debug (défaut : false)

Intégrations

Variable	Requis	Description
LINEAR_API_KEY	Non	API key Linear
GITLAB_TOKEN	Non	Personal Access Token GitLab
GITLAB_INSTANCE_URL	Non	URL instance GitLab (défaut : gitlab.com)

Mémoire (Graphiti)

Variable	Requis	Description
GRAPHITI_ENABLED	Non	Active la mémoire (défaut : true)
GRAPHITI_LLM_PROVIDER	Non	openai, anthropic, ollama, google, openrouter
GRAPHITI_EMBEDDER_PROVIDER	Non	openai, voyage, ollama, google, openrouter

Voir .env-files/.env.example pour la liste complète.

---

🤖 Intégration CI/CD

Exemple d'usage dans GitHub Actions :

name: Auto-Fix Issue

on:
  issues:
    types: [labeled]

jobs:
  autofix:
    if: github.event.label.name == 'auto-fix'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install WorkPilot AI
        run: |
          cd apps/backend
          pip install -r requirements.txt

      - name: Run WorkPilot AI
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_OAUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cd apps/backend
          python runners/spec_runner.py --task "${{ github.event.issue.body }}"
          python run.py --spec-latest
          python run.py --spec-latest --merge --create-pr

---

🧭 Commandes courantes récapitulatives

# Création
python runners/spec_runner.py --interactive
python runners/spec_runner.py --task "description"
python runners/spec_runner.py --continue 001-feature

# Exécution
python run.py --list
python run.py --spec 001
python run.py --spec 001 --max-iterations 5

# QA
python run.py --spec 001 --skip-qa
python run.py --spec 001 --qa
python run.py --spec 001 --qa-status

# Workspace
python run.py --spec 001 --review
python run.py --spec 001 --merge
python run.py --spec 001 --discard

# Validation
python validate_spec.py --spec-dir specs/001-feature --checkpoint all

---

Prochaine étape

➡️ Sécurité et isolation