Criar CLI
Projete a superfície da CLI (sintaxe + comportamento), priorizando humanos, amigável para scripts.
Faça Isso Primeiro
- Leia
agent-scripts/skills/create-cli/references/cli-guidelines.mde aplique-o como a rubrica padrão. - Diretrizes completas/upstream: https://clig.dev/ (proponha mudanças: https://github.com/cli-guidelines/cli-guidelines)
- Faça apenas as perguntas mínimas de esclarecimento necessárias para definir a interface.
Esclareça (rápido)
Pergunte, depois siga com suposições padrão caso o usuário não tenha certeza:
- Nome do comando + propósito em uma frase.
- Usuário principal: humanos, scripts, ou ambos.
- Fontes de entrada: args vs stdin; arquivos vs URLs; segredos (nunca via flags).
- Contrato de saída: texto humano,
--json,--plain, códigos de saída. - Interatividade: prompts permitidos? precisa de
--no-input? confirmações para operações destrutivas? - Modelo de configuração: flags/env/arquivo de configuração; precedência; XDG vs local ao repositório.
- Restrições de plataforma/runtime: macOS/Linux/Windows; binário único vs runtime.
Entregáveis (o que gerar)
Ao projetar uma CLI, produza uma especificação compacta que o usuário possa implementar:
- Árvore de comandos + sinopse USAGE.
- Tabela de argumentos/flags (tipos, padrões, obrigatório/opcional, exemplos).
- Semântica de subcomandos (o que cada um faz; idempotência; mudanças de estado).
- Regras de saída: stdout vs stderr; detecção de TTY;
--json/--plain;--quiet/--verbose. - Mapa de erros + códigos de saída (principais modos de falha).
- Regras de segurança:
--dry-run, confirmações,--force,--no-input. - Regras de configuração/env + precedência (flags > env > config do projeto > config do usuário > sistema).
- História de conclusão de shell (se relevante): instalação/descoberta; comando de geração ou scripts empacotados.
- 5–10 exemplos de invocação (fluxos comuns; inclua exemplos com pipe/stdin).
Convenções Padrão (a menos que o usuário indique o contrário)
-h/--helpsempre mostra ajuda e ignora outros argumentos.--versionimprime versão no stdout.- Dados primários no stdout; diagnósticos/erros no stderr.
- Adicione
--jsonpara saída de máquina; considere--plainpara texto estável baseado em linhas. - Prompts apenas quando stdin é um TTY;
--no-inputdesabilita prompts. - Operações destrutivas: confirmação interativa + não interativo requer
--forceou--confirm=...explícito. - Respeite
NO_COLOR,TERM=dumb; forneça--no-color. - Trate Ctrl-C: saia rápido; limpeza limitada; seja crash-only quando possível.
Modelos (copie na sua resposta)
Esqueleto de especificação CLI
Preencha estas seções, remova o que for irrelevante:
- Nome:
meucomando - Frase de efeito:
... - USAGE:
meucomando [flags globais] <subcomando> [args]
- Subcomandos:
meucomando init ...meucomando run ...
- Flags globais:
-h, --help--version-q, --quiet/-v, --verbose(defina exatamente)--json/--plain(se aplicável)
- Contrato de E/S:
- stdout:
- stderr:
- Códigos de saída:
0sucesso1falha genérica2uso inválido (parsing/validação)- (adicione códigos específicos do comando apenas quando realmente úteis)
- Env/config:
- variáveis de ambiente:
- caminho do arquivo de configuração + precedência:
- Exemplos:
- …
Notas
- Prefira recomendar uma biblioteca de parsing (específica da linguagem) apenas quando solicitado; caso contrário, mantenha esta skill agnóstica à linguagem.
- Se a solicitação for "parâmetros de design", não desvie para implementação.