Escrever no modelo

Você pode editar o YAML à mão a qualquer momento; ele continua sendo a fonte da verdade. Os comandos existem porque escrever por comando é mais rápido, não esquece um campo obrigatório e recusa uma alteração que quebraria o modelo.

As quatro garantias

O diff é pequeno. Nada é reserializado: a ferramenta acha o ponto e emenda o texto. Comentários, alinhamento, aspas e fim de linha ficam como estavam.

Nada é escrito se o resultado não carregar. A validação roda depois da gravação, e qualquer erro novo desfaz tudo.

Remover recusa quando alguém depende. E lista quem.

--dry-run mostra o patch sem gravar, em qualquer comando que escreve:

cfour element add api --name "API de Reservas" --parent reservas --shape api --dry-run

reservas/reservas ainda nao tem filhos; fica na pasta dele:
--- /dev/null
+++ reservas/containers.yaml
@@ -0,0 +1,5 @@
+elements:
+  - id: api
+    name: API de Reservas
+    shape: api
+    parent: reservas
--dry-run: nada foi escrito.

Repare que ele também diz onde vai escrever e por quê. Para forçar outro arquivo, use --file.

Caixas

cfour element add api --name "API de Reservas" --parent reservas --shape api \
  --technology "Node.js" --description "Regras de reserva." \
  --tag nucleo --meta dominio=reservas

cfour element list --level container
cfour element show api
cfour element set api --technology "Node.js 22" --tag pci --meta-rm dominio
cfour element mv api api-de-reservas       # renomeia, e conserta quem apontava
cfour element rm api

Não existe --level. Quem decide o nível é --parent, e mover uma caixa na árvore (element set <ref> --parent <outra>) é o que muda o nível dela.

element mv renomeia e conserta todas as referências — pais, setas, escopos, seletores, participantes de fluxo, alvos de nota.

element rm recusa quando alguém aponta para a caixa. --cascade passa por cima; --yes dispensa a confirmação.

Setas

cfour relation add painel api --kind sync --label "Chama" --meta protocolo=REST
cfour relation list --from painel
cfour relation show painel api
cfour relation set painel api --label "Chama a API"
cfour relation mv painel api async         # troca o tipo
cfour relation rm painel api

Quando há mais de uma seta entre as mesmas caixas, --kind desempata.

--inline escreve a seta dentro do documento da origem, com o from implícito.

Diagramas

cfour diagram add containers --title "Reserva de Salas — Containers" \
  --scope reservas --level container --neighbors 1 --relations auto

cfour diagram list
cfour diagram show containers
cfour diagram show containers --resolved     # o que ele MOSTRA, e por quê
cfour diagram set containers --include tag:nucleo --exclude-rm ref:legado
cfour diagram mv containers containers-v2    # renomeia, e move o layout junto
cfour diagram rm containers

Na linha de comando, um critério se escreve <chave>:<valor>. Não há ambiguidade com um identificador porque identificador não aceita dois-pontos:

--include level:context          --include tag:nucleo
--include children:reservas      --include descendants:reservas:2
--include shape:queue            --include project:shared
--include meta:dominio=reservas  --where level:container

Grupos

cfour group add containers dados --name Dados --match-shape database --match-shape queue
cfour group add containers experiencia --name "Experiencia" --orientation row --include painel
cfour group add containers replicas --parent dados --match-tag replica
cfour group list containers
cfour group set containers dados --name "Persistencia"
cfour group rm containers dados --cascade

Vários --match-* do mesmo tipo combinam com ou; de tipos diferentes, com e. Não há negação.

Fluxos, passos e caminhos

cfour flow add reservar colaborador painel --title "Reservar uma sala" \
  --scope reservas --label "Escolhe sala e horario"

cfour flow step reservar api --label "Pede a reserva"
cfour step add reservar servico-de-reserva --label "Confirma a reserva"
cfour step set reservar --n 3 --label "Confirma"
cfour step mv reservar --n 4 --after 2
cfour step rm reservar --n 4

cfour path add reservar ocupada servico-de-reserva --name "Sala ocupada" \
  --outcome failure --from conflito --label "Ja existe reserva nesse horario"
cfour path list reservar

cfour flow show reservar

cfour flow step é apelido de cfour step add. Um passo é endereçado pelo número que cfour flow show mostra (--n) ou pelo identificador dele (--id), quando tem um. --path <id> mexe num caminho alternativo em vez do principal.

Notas

cfour note add api "Ponto unico de falha para confirmar uma reserva." --kind risk
cfour note add banco "Vale separar a replica?" --kind question --scope containers
cfour note add containers "Congelado para a revisao de 2026-Q1"
cfour note list --target api
cfour note set api --text "..." --match "Ponto unico"
cfour note rm api --match "Ponto unico"

O primeiro argumento é o alvo: uma caixa, ou um diagrama. Quando o mesmo identificador nomeia as duas coisas, --target e --scope desfazem a ambiguidade. --match <trecho> escolhe entre várias notas do mesmo alvo.

Projetos

cfour project add portaria --name "Controle de Portaria" --order 20
cfour project list
cfour project set portaria --name "Portaria"
cfour project rm portaria --cascade      # apaga a pasta, mesmo com conteúdo

Configuração da aparência

cfour config show
cfour config title "Reserva de Salas"
cfour config set noteKinds decisao --label Decisao --color "#0f766e" --char D
cfour config set shapes lambda --primitive box --stereotype Function --palette container
cfour config rm noteKinds decisao

cfour config show lista os valores que de fato valem naquela modelagem — os padrões do motor com o workspace.yaml por cima. É a resposta para “quais formas eu posso usar aqui?”.

O registro e as modelagens

cfour modelagem list
cfour modelagem add portaria --path ./portaria --name "Portaria" --ativa
cfour modelagem set portaria --status reference --federacao predio
cfour modelagem use portaria
cfour modelagem show portaria
cfour modelagem rm portaria           # tira do registro; nunca apaga arquivo

A referência completa

Cada comando, com todo argumento e toda opção: Comandos do cfour.