Créer CLI
Concevoir la surface d'une CLI (syntaxe + comportement), priorité à l'humain, adaptée aux scripts.
À faire en premier
- Lire
agent-scripts/skills/create-cli/references/cli-guidelines.mdet l'appliquer comme référentiel par défaut. - Références complètes : https://clig.dev/ (proposer des modifications : https://github.com/cli-guidelines/cli-guidelines)
- Poser uniquement le minimum de questions de clarification nécessaires pour figer l'interface.
Clarifier (rapidement)
Demander, puis utiliser les valeurs par défaut les plus probables si l'utilisateur n'est pas sûr :
- Nom de la commande + objectif en une phrase.
- Utilisateur principal : humains, scripts, ou les deux.
- Sources d'entrée : arguments vs stdin ; fichiers vs URLs ; secrets (jamais via les drapeaux).
- Contrat de sortie : texte lisible,
--json,--plain, codes de sortie. - Interactivité : invites autorisées ? besoin de
--no-input? confirmations pour les opérations destructrices ? - Modèle de configuration : drapeaux/env/fichier de config ; précédence ; XDG vs local au dépôt.
- Contraintes de plateforme/environnement d'exécution : macOS/Linux/Windows ; binaire unique vs environnement.
Livrables (quoi produire)
Lors de la conception d'une CLI, produire un cahier des charges compact que l'utilisateur peut implémenter :
- Arborescence des commandes + synopsis USAGE.
- Tableau des arguments/drapeaux (types, valeurs par défaut, obligatoires/optionnels, exemples).
- Sémantique des sous-commandes (ce que chacune fait ; idempotence ; changements d'état).
- Règles de sortie : stdout vs stderr ; détection TTY ;
--json/--plain;--quiet/--verbose. - Carte des erreurs + codes de sortie (principaux modes de défaillance).
- Règles de sécurité :
--dry-run, confirmations,--force,--no-input. - Règles de configuration/env + précédence (drapeaux > env > config projet > config utilisateur > système).
- Histoire de complétion shell (si pertinent) : installation/découvrabilité ; commande de génération ou scripts fournis.
- 5 à 10 exemples d'invocations (flux courants ; inclure des exemples avec pipe/stdin).
Conventions par défaut (sauf indication contraire de l'utilisateur)
-h/--helpaffiche toujours l'aide et ignore les autres arguments.--versionaffiche la version sur stdout.- Données principales sur stdout ; diagnostics/erreurs sur stderr.
- Ajouter
--jsonpour la sortie machine ; envisager--plainpour un texte stable basé sur des lignes. - Invites uniquement lorsque stdin est un TTY ;
--no-inputdésactive les invites. - Opérations destructrices : confirmation interactive + en mode non interactif nécessite
--forceou--confirm=...explicite. - Respecter
NO_COLOR,TERM=dumb; fournir--no-color. - Gérer Ctrl-C : sortie rapide ; nettoyage limité ; être crash-only si possible.
Modèles (copier dans votre réponse)
Squelette de spécification CLI
Remplir ces sections, supprimer ce qui est sans pertinence :
- Nom :
macommande - Phrase d'accroche :
... - USAGE :
macommande [drapeaux globaux] <sous-commande> [args]
- Sous-commandes :
macommande init ...macommande executer ...
- Drapeaux globaux :
-h, --help--version-q, --quiet/-v, --verbose(définir exactement)--json/--plain(si applicable)
- Contrat d'E/S :
- stdout :
- stderr :
- Codes de sortie :
0succès1échec générique2utilisation invalide (analyse/validation)- (ajouter des codes spécifiques à la commande uniquement si réellement utiles)
- Env/config :
- variables d'environnement :
- chemin du fichier de configuration + précédence :
- Exemples :
- …
Notes
- Privilégier la recommandation d'une bibliothèque d'analyse (spécifique à un langage) uniquement si demandé ; sinon, garder cette compétence indépendante du langage.
- Si la demande est "paramètres de conception", ne pas dériver vers l'implémentation.