Usar em scripts e automação

A ferramenta foi feita para ser chamada por outra coisa além de uma pessoa: um script, um job de CI, um agente de IA.

Códigos de saída

Código	Significado
0	deu certo. Avisos não mudam isso
1	erro — modelo inválido, falta de credencial, recusa da plataforma
2	uso errado do comando

--json

Todo comando de consulta e todo comando que escreve aceitam --json.

Nos comandos de escrita, a saída diz o que mudou — ou traz o erro com um código estável, que é o que permite um script reagir ao motivo em vez de ao texto da mensagem.

cfour element list --json | jq -r '.[].id'
cfour check --json
cfour diagram show containers --resolved --json
cfour keys --json
cfour status --json

--no-input

Sem terminal, a ferramenta nunca pergunta. Com terminal, ela pode perguntar — e --no-input desliga isso explicitamente:

cfour push --no-input

Todo campo tem uma opção, então nada é impossível de fazer sem responder a uma pergunta. Quando falta algo, a recusa diz qual campo é.

--dry-run

Em qualquer comando que escreve, mostra o patch e não grava. Em cfour push, diz o destino e não envia nada.

Vale como verificação num pull request: rodar o comando com --dry-run e comparar a saída é uma forma barata de revisar uma automação antes de soltá-la.

O inventário do modelo

cfour check --inventory

Devolve JSON com o resultado da validação e um inventário: as contagens por tipo, os projetos, os níveis, o vocabulário encontrado. É o que um agente lê para saber o tamanho e a forma do que está prestes a editar, sem carregar o modelo inteiro no contexto.

A árvore de comandos, em JSON

cfour help --output json

Devolve a árvore inteira: cada comando, com argumentos, opções, se cada opção é repetível, e exemplos. É a mesma declaração que despacha os comandos — então ela não pode divergir do que a ferramenta faz.

É a forma correta de um agente descobrir a superfície da ferramenta em vez de adivinhar as opções.

As regras do formato, sem rede

cfour help formato
cfour help formato --output json

Imprime a anatomia dos arquivos, a derivação dos níveis, a resolução de referências, a diferença entre selecionar e listar, as duas formas de um documento e as garantias de escrita.

Variáveis de ambiente

Variável	Para quê
CFOUR_KEY	a chave de publicação. Vence o arquivo de credenciais
CFOUR_ENDPOINT	outra instalação da plataforma
CFOUR_CONFIG_HOME	onde gravar a chave
C4_MODELAGEM	qual modelagem abrir
C4_ROOT	uma árvore avulsa; vence tudo

Nenhum arquivo .env é lido automaticamente — não há dotenv, de propósito, para a precedência de CFOUR_KEY sobre o arquivo de credenciais não ser surpreendente. Para carregar um:

set -a; . .env; set +a

A referência completa está em Variáveis de ambiente.

Autocompletar

cfour completion bash    # ou zsh, fish

Publicar de um job de CI

Veja Publicar a partir do CI — é o caso de automação mais comum, e tem uma página própria.