Créateur de CLI

Crée une véritable CLI que les threads Codex futurs peuvent exécuter par nom de commande depuis n'importe quel répertoire de travail.

Cette compétence est destinée aux outils durables, pas aux scripts ponctuels. Si un court script dans le repo actuel résout la tâche, écris le script là à la place.

Démarrage

Nomme l'outil cible, sa source et les premiers vrais travaux qu'il doit faire :

Source : docs d'API, JSON OpenAPI, docs SDK, exemples curl, app navigateur, script interne existant, article ou historique shell fonctionnel.
Travaux : lectures/écritures littérales telles que list drafts, download failed job logs, search messages, upload media, read queue schedule.
Nom d'installation : un nom de binaire court tel que ci-logs, slack-cli, sentry-cli ou buildkite-logs.

Préfère un nouveau dossier sous ~/code/clis/<tool-name> quand l'utilisateur veut un outil personnel et n'a pas nommé de repo.

Avant l'échafaudage, vérifie si la commande proposée existe déjà :

command -v <tool-name> || true

Si elle existe, choisis un nom d'installation plus clair ou demande à l'utilisateur.

Choisir le Runtime

Avant de choisir, inspecte la machine de l'utilisateur et le matériel source :

command -v cargo rustc node pnpm npm python3 uv || true

Ensuite, choisis la chaîne d'outils la moins surprenante :

Par défaut Rust pour une CLI durable que Codex doit exécuter depuis n'importe quel repo : un binaire rapide, parsing d'arguments robuste, bon traitement JSON, installation facile dans ~/.local/bin.
Utilise TypeScript/Node quand le SDK officiel, l'assistant d'authentification, la bibliothèque d'automatisation de navigateur ou l'outillage repo existant est la raison pour laquelle la CLI peut être meilleure.
Utilise Python quand la source est la science des données, les transformations de fichiers locaux, les notebooks, l'analyse SQLite/CSV/JSON ou l'outillage d'administration lourd en Python qui peut quand même être installé en tant que commande durable.

Ne choisis pas un langage qui ajoute des frictions d'installation sauf s'il améliore matériellement la CLI. Si le meilleur langage n'est pas installé, soit installe la chaîne d'outils manquante avec l'approbation de l'utilisateur, soit choisis la prochaine meilleure option installée.

Énonce le choix en une phrase avant l'échafaudage, en incluant la raison et la chaîne d'outils installée que tu as trouvée.

Contrat de Commande

Esquisse la surface de commande dans le chat avant de coder. Inclus le nom du binaire, les commandes de découverte, les commandes de résolution ou de recherche d'ID, les commandes de lecture, les commandes d'écriture, l'échappatoire brut, le choix auth/config et la commande PATH/install.

Lors de la conception de la surface de commande, lis references/agent-cli-patterns.md pour la forme CLI composable attendue.

Construis vers cette surface :

tool-name --help affiche chaque capacité majeure.
tool-name --json doctor vérifie la config, l'auth, la version, la réachabilité du endpoint et la configuration manquante.
tool-name init ... stocke la config locale quand l'auth en variables d'env uniquement est pénible.
Les commandes de découverte trouvent les comptes, projets, espaces de travail, équipes, files d'attente, canaux, repos, tableaux de bord ou autres conteneurs de haut niveau.
Les commandes de résolution transforment les noms, URLs, slugs, permaliens, entrées de clients ou liens de build en IDs stables afin que les futures commandes ne répètent pas de larges recherches.
Les commandes de lecture récupèrent les objets exacts et listent/recherchent les collections. Les listes paginées supportent un --limit borné, cursor, offset ou par défaut clairement documenté.
Les commandes d'écriture font une action nommée chacune : create, update, delete, upload, schedule, retry, comment, draft. Elles acceptent l'ID de ressource stable le plus étroit, supportent --dry-run, draft ou preview en premier quand le service le permet, et ne cachent pas les écritures à l'intérieur de larges commandes telles que fix, debug ou auto.
--json retourne une sortie stable lisible par machine.
Une échappatoire brute existe : request, tool-call, api ou le nom honnête le plus proche.

N'expose pas seulement une commande générique request. Donne à Codex des verbes de haut niveau pour les travaux répétés.

Documente la politique JSON dans le README de la CLI ou l'équivalent : pass-through d'API versus enveloppe CLI, forme de succès, forme d'erreur et un exemple pour chaque famille de commandes. Sous --json, les erreurs doivent être lisibles par machine et ne doivent pas contenir de credentials.

Auth et Config

Supporte les chemins ennuyeux d'abord, dans cet ordre de précédence :

Variable d'environnement utilisant le nom standard du service, tel que GITHUB_TOKEN.
Config utilisateur sous ~/.<tool-name>/config.toml ou un autre chemin simple documenté.
--api-key ou un flag de token spécifique à l'outil uniquement pour les tests explicites ponctuels. Préfère env/config pour l'utilisation normale car les flags peuvent fuir dans l'historique shell ou les listes de processus.

Ne jamais imprimer les tokens complets. doctor --json doit dire si un token est disponible, la catégorie de source d'auth (flag, env, config, par défaut du fournisseur ou manquant) et quelle étape de configuration manque.

Si la CLI peut s'exécuter sans réseau ou auth, rends cela explicite dans doctor --json : rapporte le mode fixture/offline, si les données de fixture ont été trouvées et si l'auth n'est pas nécessaire pour ce mode.

Pour les apps web internes sourcées de curls DevTools, crée des notes de endpoint désinfectées avant l'implémentation : nom de ressource, méthode/chemin, headers requis, mécanisme d'auth, comportement CSRF, corps de requête, champs d'ID de réponse, pagination, erreurs et une réponse d'exemple expurgée. Ne valide jamais les cookies copiés, les tokens bearer, les secrets de clients ou les payloads de production complets.

Utilise les captures d'écran pour déduire le workflow, le vocabulaire de l'interface utilisateur, les champs et les points de confirmation. Ne traite pas les captures d'écran comme des preuves d'API sauf si elles sont appariées avec une requête réseau, une exportation, une page docs ou une fixture.

Workflow de Construction

Lis la source juste assez pour inventorier les ressources, l'auth, la pagination, les IDs, les flux média/fichier, les limites de débit et les actions d'écriture dangereuses. Si les docs exposent OpenAPI, télécharge ou inspecte-la avant de nommer les commandes.
Esquisse la liste des commandes dans le chat. Garde les noms courts et shell-friendly.
Échafaude la CLI avec un README ou des instructions équivalentes face au repo.
Implémente doctor, découverte, résolution, commandes de lecture, un chemin d'écriture draft ou dry-run étroit si demandé, et l'échappatoire brute.
Installe la CLI sur PATH pour que tool-name ... fonctionne en dehors du dossier source.
Teste à froid depuis un autre repo ou /tmp, pas seulement avec cargo run ou les wrappers du gestionnaire de paquets. Exécute command -v <tool-name>, <tool-name> --help et <tool-name> --json doctor.
Exécute le format, la vérification des types/la construction, les tests unitaires pour les constructeurs de requêtes, les constructeurs de corps de requête/pagination, le doctor sans auth, la sortie d'aide et au moins un appel d'API fixture, dry-run ou en lecture seule en direct.

Si une écriture en direct est nécessaire pour la confiance, demande d'abord et rends-la réversible ou draft-only.

Quand la source est un script existant ou un historique shell, divise l'invocation fonctionnelle en phases réelles : setup, découverte, download/export, transform/index, draft, upload, poll, écriture en direct. Préserve les flags, chemins et variables d'environnement sur lesquels l'utilisateur compte déjà, puis enveloppe les phases répétables avec des IDs stables, du JSON borné et des sorties de fichiers.

Pour les échappatoires brutes, supporte d'abord les appels en lecture seule. N'exécute pas les requêtes brutes non-GET/HEAD contre un service en direct sauf si l'utilisateur a demandé cette écriture spécifique.

Pour les flux média, d'artefact ou d'upload présigné, teste chaque phase séparément : créer l'upload, transférer les octets, poll/lire l'état du traitement, puis attacher ou référencer l'ID résultant.

Pour les prototypes soutenus par fixtures, garde les fixtures dans un chemin de projet prévisible et fais localiser la CLI après l'installation. Teste à froid depuis /tmp pour attraper les binaires qui fonctionnent seulement à l'intérieur du dossier source.

Pour les CLIs orientées log, garde l'extraction de snippet déterministe séparée de l'interprétation de modèle. Préfère une commande qui émet les noms de fichiers, les numéros de lignes ou plages d'octets, les règles assorties et les courts extraits.

Défauts Rust

Lors de la construction en Rust, utilise les crates établies au lieu des parseurs personnalisés :

clap pour les commandes et l'aide
reqwest pour HTTP
serde / serde_json pour les payloads
toml pour les petits fichiers de config
anyhow pour le contexte d'erreur en forme de CLI

Ajoute une cible Makefile telle que make install-local qui construit la release et installe le binaire dans ~/.local/bin.

Défauts TypeScript/Node

Lors de la construction en TypeScript/Node, garde la CLI installable en tant que commande normale :

commander ou cac pour les commandes et l'aide
fetch natif, le SDK officiel ou l'assistant HTTP existant de l'utilisateur pour les appels d'API
zod uniquement où la validation de payload externe empêche la vraie cassure
entrée package.json bin pour la commande installée
tsup, tsx ou tsc utilisant la convention existante du repo

Ajoute un chemin d'installation tel que pnpm install, pnpm build et pnpm link --global, ou une cible Makefile qui installe un petit wrapper dans ~/.local/bin.

Défauts Python

Lors de la construction en Python, préfère les pièces ennuyeuses de la stdlib sauf si le workflow en a besoin de plus :

argparse pour les commandes et l'aide, ou typer quand les sous-commandes seraient autrement confuses
urllib.request / urllib.parse, requests ou httpx pour HTTP, correspondant à ce qui est déjà installé ou déjà utilisé à proximité
json, csv, sqlite3, pathlib et subprocess pour les fichiers locaux, les exportations, les bases de données et les scripts existants
script console pyproject.toml ou un petit wrapper exécutable pour la commande installée
uv ou un virtualenv uniquement quand les dépendances sont réellement nécessaires

Ajoute une cible Makefile telle que make install-local qui installe la commande sur PATH et documente si elle dépend de uv, un virtualenv ou seulement Python système.

Compétence Compagnon

Après que la CLI fonctionne, crée ou mets à jour une petite compétence pour elle. Utilise $skill-creator quand elle est disponible. Utilise $CODEX_HOME/skills/<tool-name>/SKILL.md pour une compétence compagnon personnelle sauf si l'utilisateur nomme un chemin repo-local .codex/skills/... ou un autre repo de compétences.

Écris la compétence compagnon dans l'ordre qu'un thread Codex futur doit utiliser la CLI, pas comme une visite de chaque fonctionnalité. Explique :

Comment vérifier que la commande installée existe.
Quelle commande exécuter en premier.
Comment l'auth est configurée.
Quelle commande de découverte trouve l'ID courant.
Le chemin de lecture sûr.
Le chemin d'écriture/draft prévu.
L'échappatoire brute.
Ce qu'il ne faut pas faire sans approbation explicite de l'utilisateur.
Trois exemples de commande copiables-collables.

Garde les détails de référence d'API dans la docs CLI ou un fichier de référence de compétence. Garde la compétence focalisée sur l'ordonnancement, la sécurité et les exemples que les threads Codex futurs devraient réellement exécuter.