Visão geral do cfour

cfour é a ferramenta de linha de comando do cfourdev. Ela é publicada no npm como cfour-cli — veja Instalação.

Ela faz cinco coisas:

valida	cfour check diz se o modelo carrega, e o que está errado
escreve	element, relation, diagram, flow, note, group, step, path, project, config
consulta	find, refs, e os list e show de cada família
desenha	cfour serve abre o leitor na sua máquina
publica	login, push, status, keys

O que ela nunca faz

Não reserializa o seu YAML. Todo comando que escreve acha o ponto exato e emenda o texto. Comentários, alinhamento, aspas e fim de linha ficam como estavam — porque num repositório em que o YAML é a fonte legível da verdade, formatação não é detalhe, é o produto.

Não grava um resultado que não carrega. A validação roda depois da gravação, e qualquer erro novo desfaz tudo.

Não remove algo de que alguém depende. Um rm que quebraria referências recusa e lista quem aponta para lá. --cascade passa por cima, e --yes dispensa a confirmação.

As convenções comuns

Estas valem em todo comando que escreve:

Opção	O que faz
--dry-run	mostra o patch que seria aplicado, e não escreve nada
--json	saída em JSON: o que mudou, ou o erro com código estável
--no-input	nunca pergunta, mesmo num terminal. Recusa dizendo qual campo falta
--modelagem <id>	em qual modelagem mexer, quando há mais de uma
--file <caminho>	força o arquivo de destino, dentro do projeto

E estas valem na edição de qualquer coisa que já existe:

Opção	O que faz
--<campo> <valor>	define aquele campo
--clear <campo>	apaga aquele campo. Repetível
--tag / --tag-rm	acrescenta ou tira uma etiqueta, sem reescrever o conjunto
--meta / --meta-rm	o mesmo, para metadados

A última linha é o que dispensa ler o valor atual antes de mudar uma parte dele — e uma leitura desatualizada apagaria trabalho de outra pessoa.

Escolher a modelagem

Quando há mais de uma modelagem registrada, a ordem de decisão é:

--modelagem <id>          na linha de comando
C4_MODELAGEM              no ambiente
active:                   no cfour.yaml
a única que existe

Sem nada disso, e com mais de uma, o comando recusa e lista os identificadores.

A ajuda embutida

cfour help                  # a árvore inteira
cfour help element add      # um comando só
cfour help formato          # as regras do formato, sem precisar de rede
cfour help --output json    # a árvore inteira em JSON, para um agente

cfour help formato é a resposta curta para “como isso funciona mesmo?”: ele imprime a anatomia dos arquivos, a derivação de níveis, a resolução de referências, a diferença entre selecionar e listar, e as garantias de escrita.

As páginas desta seção

• Escrever no modelo — criar, alterar, mover e remover
• Consultar o modelo — achar coisas e entender o que existe
• Validar — cfour check, e o que ele reprova
• Ver os diagramas na sua máquina — cfour serve
• Usar em scripts e automação — JSON, códigos de saída, CI

A lista completa de comandos, com toda opção, está em Comandos do cfour.