Crear CLI
Diseñar la superficie de la CLI (sintaxis + comportamiento), centrada en humanos y amigable para scripts.
Haz esto primero
- Lee
agent-scripts/skills/create-cli/references/cli-guidelines.mdy aplícalo como la rúbrica predeterminada. - Directrices completas/originales: https://clig.dev/ (propón cambios: https://github.com/cli-guidelines/cli-guidelines)
- Haz solo las preguntas de aclaración mínimas necesarias para fijar la interfaz.
Aclarar (rápido)
Pregunta, luego procede con valores predeterminados basados en la mejor suposición si el usuario no está seguro:
- Nombre del comando + propósito en una oración.
- Usuario principal: humanos, scripts o ambos.
- Fuentes de entrada: args vs stdin; archivos vs URLs; secretos (nunca a través de flags).
- Contrato de salida: texto humano,
--json,--plain, códigos de salida. - Interactividad: ¿se permiten avisos? ¿necesita
--no-input? ¿confirmaciones para operaciones destructivas? - Modelo de configuración: flags/env/archivo de configuración; precedencia; XDG vs local al repositorio.
- Restricciones de plataforma/ejecución: macOS/Linux/Windows; binario único vs runtime.
Entregables (qué producir)
Al diseñar una CLI, genera una especificación compacta que el usuario pueda implementar:
- Árbol de comandos + resumen de USO.
- Tabla de argumentos/banderas (tipos, valores predeterminados, obligatorio/opcional, ejemplos).
- Semántica de subcomandos (qué hace cada uno; idempotencia; cambios de estado).
- Reglas de salida: stdout vs stderr; detección de TTY;
--json/--plain;--quiet/--verbose. - Mapa de errores + códigos de salida (principales modos de fallo).
- Reglas de seguridad:
--dry-run, confirmaciones,--force,--no-input. - Reglas de configuración/env + precedencia (flags > env > configuración del proyecto > configuración del usuario > sistema).
- Historia de finalización de shell (si es relevante): instalación/descubribilidad; comando de generación o scripts empaquetados.
- 5–10 ejemplos de invocación (flujos comunes; incluye ejemplos con pipes/stdin).
Convenciones predeterminadas (a menos que el usuario diga lo contrario)
-h/--helpsiempre muestra ayuda e ignora otros argumentos.--versionimprime la versión en stdout.- Datos principales a stdout; diagnósticos/errores a stderr.
- Añade
--jsonpara salida para máquinas; considera--plainpara texto estable basado en líneas. - Avisos solo cuando stdin es una TTY;
--no-inputdesactiva los avisos. - Operaciones destructivas: confirmación interactiva + no interactivo requiere
--forceo--confirm=...explícito. - Respeta
NO_COLOR,TERM=dumb; proporciona--no-color. - Maneja Ctrl-C: salida rápida; limpieza limitada; sé lo más "crash-only" posible.
Plantillas (copia en tu respuesta)
Esqueleto de especificación CLI
Completa estas secciones, omite lo irrelevante:
- Nombre:
micomando - Descripción en una línea:
... - USO:
micomando [flags globales] <subcomando> [args]
- Subcomandos:
micomando init ...micomando run ...
- Flags globales:
-h, --help--version-q, --quiet/-v, --verbose(define exactamente)--json/--plain(si aplica)
- Contrato de E/S:
- stdout:
- stderr:
- Códigos de salida:
0éxito1fallo genérico2uso inválido (análisis/validación)- (añade códigos específicos del comando solo si realmente son útiles)
- Env/config:
- variables de entorno:
- ruta del archivo de configuración + precedencia:
- Ejemplos:
- …
Notas
- Prefiere recomendar una biblioteca de análisis (específica del lenguaje) solo cuando te lo pidan; de lo contrario, mantén esta habilidad independiente del lenguaje.
- Si la solicitud es "diseñar parámetros", no te desvíes hacia la implementación.