CLI Creator

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

Cette skill 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à plutôt.

Start

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

• Source : docs API, JSON OpenAPI, docs SDK, exemples curl, app navigateur, script interne existant, article ou historique shell fonctionnel.
• Jobs : lectures/écritures littérales telles que list drafts, download failed job logs, search messages, upload media, read queue schedule.
• Install name : un court nom binaire 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 de scaffolder, vérifie que la commande proposée n'existe pas déjà :

command -v <tool-name> || true

Si elle existe, choisis un install name plus clair ou demande à l'utilisateur.

Choose the 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

Puis choisis la toolchain la moins surprenante :

• Défaut à Rust pour une CLI durable que Codex doit exécuter depuis n'importe quel repo : un binaire rapide, un argument parsing fort, une bonne gestion JSON, facile à copier/installer dans ~/.local/bin.
• Utilise TypeScript/Node quand le SDK officiel, l'helper d'auth, la librairie d'automation navigateur, ou la tooling repo existante est la raison pour laquelle la CLI peut être meilleure.
• Utilise Python quand la source est data science, transformations fichiers locaux, notebooks, analyse SQLite/CSV/JSON, ou tooling admin lourd en Python qui peut quand même être installé comme commande durable.

Ne choisis pas un langage qui ajoute de la friction setup sauf s'il améliore matériellement la CLI. Si le meilleur langage n'est pas installé, installe la toolchain manquante avec l'approbation de l'utilisateur ou choisis la meilleure option installée suivante.

Énonce le choix en une phrase avant de scaffolder, incluant la raison et la toolchain installée que tu as trouvée.

Command Contract

Esquisses la surface de commande en chat avant de coder. Inclus le nom binaire, commandes de discovery, commandes resolve ou ID-lookup, commandes read, commandes write, échappatoire brut, choix auth/config, et commande PATH/install.

Quand tu conçois 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 config, auth, version, réachabilité endpoint et setup manquant.
• tool-name init ... stocke la config locale quand l'auth env-only est pénible.
• Les commandes Discovery trouvent des comptes, projets, espaces de travail, équipes, files, canaux, repos, dashboards, ou autres conteneurs top-level.
• Les commandes Resolve transforment noms, URLs, slugs, permalinks, entrée client, ou liens build en IDs stables pour que les futures commandes ne répètent pas de larges recherches.
• Les commandes Read récupèrent des objets exacts et listent/recherchent des collections. Les listes paginées supportent un --limit borné, curseur, offset, ou défaut clairement documenté.
• Les commandes Write font chaque action nommée : create, update, delete, upload, schedule, retry, comment, draft. Elles acceptent l'ID ressource stables le plus étroit, supportent --dry-run, draft, ou preview d'abord quand le service l'autorise, et ne cachent pas les writes dans des commandes larges 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 le plus honnête.

N'expose pas seulement une commande request générique. Donne à Codex des verbes high-level pour les jobs répétés.

Documente la JSON policy dans la CLI README ou équivalent : API pass-through versus enveloppe CLI, success shape, error shape, 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 and Config

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

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

Ne jamais affiche de tokens complets. doctor --json devrait dire si un token est disponible, la catégorie source d'auth (flag, env, config, défaut provider, ou missing), et quelle étape setup manque.

Si la CLI peut s'exécuter sans réseau ou auth, rend cela explicite dans doctor --json : rapporte le mode fixture/offline, si fixture data a été trouvé, et si l'auth n'est pas requise pour ce mode.

Pour les apps web internes sourcées depuis curls DevTools, crée des notes d'endpoint sanitisées avant d'implémenter : nom ressource, method/path, headers requis, mécanisme auth, comportement CSRF, request body, champs ID de réponse, pagination, erreurs, et un sample de réponse redacté. Ne commets jamais les cookies copiés, bearer tokens, secrets client, ou pleins payloads production.

Utilise les screenshots pour inférer workflow, vocabulaire UI, champs, et points de confirmation. Ne traite pas les screenshots comme preuve API sauf s'ils sont appairés avec une network request, export, page docs, ou fixture.

Build Workflow

1. Lis la source juste assez pour inventorier ressources, auth, pagination, IDs, flux media/fichiers, rate limits, et actions write dangereuses. Si les docs exposent OpenAPI, télécharge ou inspecte avant de nommer les commandes.
2. Esquisse la liste de commandes en chat. Garde les noms courts et shell-friendly.
3. Scaffold la CLI avec un README ou instructions équivalentes repo-facing.
4. Implémente doctor, discovery, resolve, commandes read, un chemin write draft ou dry-run étroit si demandé, et l'échappatoire brute.
5. Installe la CLI sur PATH pour que tool-name ... fonctionne en dehors du dossier source.
6. Smoke test depuis un autre repo ou /tmp, pas seulement avec cargo run ou package-manager wrappers. Exécute command -v <tool-name>, <tool-name> --help, et <tool-name> --json doctor.
7. Exécute format, typecheck/build, unit tests pour request builders, pagination/request-body builders, doctor no-auth, help output, et au moins un fixture, dry-run, ou live read-only API call.

Si un live write est nécessaire pour la confiance, demande d'abord et rends-le réversible ou draft-only.

Quand la source est un script existant ou historique shell, divise l'invocation fonctionnelle en vraies phases : setup, discovery, download/export, transform/index, draft, upload, poll, live write. Préserve les flags, chemins, et variables d'environnement sur lesquels l'utilisateur s'appuie déjà, puis enveloppe les phases répétables avec des IDs stables, JSON borné, et sorties fichier.

Pour les échappatoires brutes, supporte d'abord les appels read-only. N'exécute pas de requêtes brutes non-GET/HEAD contre un service live sauf si l'utilisateur a demandé cette write spécifique.

Pour les flux media, artifact, ou presigned upload, teste chaque phase séparément : create upload, transfer bytes, poll/read processing status, puis attache ou référence l'ID résultant.

Pour les prototypes fixture-backed, garde les fixtures dans un chemin projet prévisible et fais la CLI les localiser après installation. Smoke-test depuis /tmp pour attraper les binaires qui fonctionnent seulement dans le dossier source.

Pour les CLIs log-oriented, garde l'extraction snippet déterministe séparée de l'interprétation modèle. Préfère une commande qui émet noms fichiers, numéros de lignes ou byte ranges, matched rules, et courts extraits.

Rust Defaults

Lors de la construction en Rust, utilise des crates établies plutôt que des parsers custom :

• clap pour commandes et help
• reqwest pour HTTP
• serde / serde_json pour payloads
• toml pour petits fichiers config
• anyhow pour contexte erreur CLI-shaped

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

TypeScript/Node Defaults

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

• commander ou cac pour commandes et help
• native fetch, le SDK officiel, ou l'HTTP helper existant de l'utilisateur pour appels API
• zod seulement où la validation payload externe prévient la vraie rupture
• entrée bin package.json pour la commande installée
• tsup, tsx, ou tsc utilisant la convention existante du repo

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

Python Defaults

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

• argparse pour commandes et help, ou typer quand les subcommandes seraient sinon compliquées
• urllib.request / urllib.parse, requests, ou httpx pour HTTP, matchant ce qui est déjà installé ou déjà utilisé à proximité
• json, csv, sqlite3, pathlib, et subprocess pour fichiers locaux, exports, bases de données, et scripts existants
• pyproject.toml console script ou un petit wrapper exécutable pour la commande installée
• uv ou virtualenv seulement quand les dépendances sont vraiment 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, virtualenv, ou seulement Python système.

Companion Skill

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

Écris la companion skill dans l'ordre qu'un futur thread Codex devrait utiliser la CLI, pas comme une visite de chaque feature. Explique :

• Comment vérifier que la commande installée existe.
• Quelle commande exécuter en premier.
• Comment l'auth est configurée.
• Quelle commande discovery trouve l'ID commun.
• Le chemin read sûr.
• Le chemin draft/write prévu.
• L'échappatoire brute.
• Ce qu'il ne faut pas faire sans approbation explicite de l'utilisateur.
• Trois exemples de commande copy-pasteable.

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