Referência da CLI

dataforge init [pasta]

Escreve o manifesto, a pasta src/ com um main.df e a tests/.
Sem argumento, usa a pasta atual.

dataforge init                                       # aqui mesmo
dataforge init meu-app                               # numa pasta nova

dataforge api <arquivo.df> [--formato]

As rotas sao a fonte da verdade: o arquivo e executado
para que elas se registrem, e o resultado sai do que
esta la — nao de uma descricao escrita a mao, que
divergiria na primeira semana.

Aponte para o modulo que MONTA o servidor ('app.df'), e
nao para o que sobe ('main.df').

dataforge api src/app.df                             # a tabela de rotas
dataforge api src/app.df --openapi -o=openapi.json
dataforge api src/app.df --insomnia -o=insomnia.json

dataforge converter <arquivo.py|pasta>

Le com o 'ast' do Python, e nao com expressao regular.
O que nao tem equivalente honesto vira um comentario
'TODO(converter)' com o codigo original ao lado — um
conversor que erra em silencio e pior que um que aponta
onde errou.

O relatorio no fim conta as duas coisas: o que saiu pronto
e o que precisa de voce.

dataforge converter app.py                           # grava app.df ao lado
dataforge converter src/                             # a pasta inteira, recursiva
dataforge converter app.py --seco                    # so mostra

dataforge new [modelo] [nome]

10 modelos, e todos produzem um projeto que RODA e
passa nos proprios testes — nao um esqueleto com TODOs:

  cli      Lê argumentos, imprime tabela colorida, tem --help
  api      Servidor com rotas, JSON, 404/405 e testes sem socket
  web      Templates HTML, arquivos estáticos e escape automático
  data     Banco, estatística e exportação para Excel
  lib      Um pacote com relay, testes e pronto para publicar
  oop      Blueprints, traits, propriedades e operadores
  script   Arquivos, JSON, datas e processos do sistema
  painel   Um dashboard: métricas, gráficos, filtros e testes
  bot      Comandos, botões, conversa com estado e testes sem rede
  test     Como testar em DataForge: asserts, erros e cobertura

Sem argumento, pergunta na tela.

dataforge new                                        # escolhe na tela
dataforge new api                                    # usa o modelo, pergunta o nome
dataforge new api minha-api                          # direto ao ponto
dataforge new --list                                 # so os modelos

dataforge info

Nome, versao, entrada, scripts e dependencias declaradas.

dataforge run [arquivo.df] [-- args]

Sem arquivo, usa a entrada declarada no forge.toml.
O que vier depois de '--' chega ao programa em OS.argv().

dataforge run ola.df
dataforge run                                        # usa a entrada do forge.toml
dataforge run app.df -- --porta 8080                 # passa argumentos ao programa

dataforge eval '<codigo>'

Para experimentar sem criar arquivo. Multiplas instrucoes
podem ser separadas por ponto e virgula ou quebra de linha.

dataforge eval 'out 2 ** 10'
dataforge eval 'out [1,2,3] >> morph n: n * 2'

dataforge watch [arquivo.df]

Fica observando e roda de novo quando voce salva.
Ctrl+C para sair.

dataforge watch src/main.df
dataforge watch --test                               # TDD: a suite a cada save

dataforge repl

Comandos internos: :type <expr>, :ast <expr>, :check <expr>,
:load <arquivo>, :vars, :help, :quit.

dataforge check [alvo]

Aceita arquivo, pasta ou padrao. Sem alvo, analisa a pasta atual.
Sai com codigo 1 se houver erro — serve na esteira de CI.

dataforge check .                                    # o projeto inteiro
dataforge check src/ --strict                        # avisos viram erros
dataforge check . --formato=github                   # no CI do GitHub

dataforge test [alvo]

Descobre *_test.df e a pasta tests/. Cada acao que comeca
com 'test_' vira um caso.

dataforge test
dataforge test tests/ -v
dataforge test --cobertura                           # com o relatorio
dataforge test --minimo=80                           # exige 80% no CI
dataforge test --filter=soma                         # so o que casa

dataforge fmt [alvo]

Idempotente: formatar duas vezes da o mesmo resultado.

dataforge fmt .                                      # reescreve
dataforge fmt . --check                              # para a esteira de CI

dataforge lint [alvo]

Treze regras: nome fora do padrao, variavel escrita e nunca
lida, ramo redundante, e outras.

dataforge seguranca [alvo]

Duas varreduras sobre cada arquivo. A primeira acha SEGREDO pelo
formato — chave da AWS, token do GitHub, 'sk_live' da Stripe,
bloco de chave privada, token do PyPI —, e por isso acha o que
voce esqueceu, que e o unico tipo que importa. A segunda aplica
dez regras sintaticas: SQL concatenado, shell com interpolacao,
MD5 para assinatura, senha sem derivacao, verificacao desligada.

Ela le TEXTO, e nao a arvore, de proposito: um analisador de
seguranca que tenta provar fluxo de dado erra nos dois sentidos,
e o que se faz com o alarme errado e desligar tudo.

Alem de '.df', ela le '.env', '.json', '.toml', '.yml', '.sh' e
'.ts' — um segredo vaza do arquivo de configuracao muito mais do
que do codigo.

'// df: permitir <regra>' na linha, ou na de cima, silencia ali.

dataforge seguranca .                                # o projeto inteiro
dataforge seguranca src/ --strict                    # reprova o CI
dataforge seguranca . --json                         # para outra ferramenta

dataforge bench <arquivo.df>

Roda varias vezes e mostra minimo, mediana e desvio.
Descarta as primeiras execucoes, que aquecem o cache.

dataforge bench algoritmo.df
dataforge bench alg.df --runs=50

dataforge add <pacote>[@versao] …

Sem faixa, grava '^' da versao mais recente. Aceita tambem
caminho local, git+URL e URL de tarball.

dataforge add validador
dataforge add tabela@^2.0                            # faixa de versoes
dataforge add ../lib-interna                         # pasta local

dataforge remove <pacote> …

dataforge install

O comando que se roda depois de clonar um projeto.

Ele HONRA o forge.lock: a versao travada vence enquanto
couber na faixa do forge.toml. Duas pessoas que clonam o
mesmo projeto em dias diferentes recebem o mesmo codigo,
e o sha256 do lock e conferido contra o que chegou.

Para MOVER as versoes, 'dataforge update'.

dataforge update [pacote …]

Resolve de novo dentro das faixas declaradas. Sem nome,
atualiza tudo; com nomes, so eles — o resto continua
travado, que e o que torna a atualizacao controlada.

Sair da faixa exige mudar o forge.toml: 'dataforge
outdated' mostra os dois casos separados.

dataforge update                                     # tudo, dentro das faixas
dataforge update tabela                              # so este pacote

dataforge list

Marca as transitivas e o que sumiu do disco.

dataforge tree

Mostra quem trouxe cada pacote, e onde ha versao compartilhada.

dataforge why <pacote>

Mostra a cadeia desde o forge.toml ate ele.

dataforge why tabela

dataforge outdated

Separa o que cabe na faixa declarada do que exigiria
mudar o forge.toml — os primeiros sobem com
'dataforge update'.

dataforge search <termo>

Busca no nome, na descricao e nas tags.

dataforge search cpf
dataforge search ""                                  # lista tudo

dataforge pack

Gera dist/<nome>-<versao>.tar.gz com o sha256.
Reprodutivel: mesma fonte, mesmo hash.

dataforge publish --registry=<pasta>

Dois destinos, e eles resolvem problemas diferentes:

  --registry=<pasta>  um indice estatico, para um registro
                      interno de empresa — espera um PR
  --remoto            o registro da comunidade, por chamada
                      autenticada, e o pacote entra na fila
                      de revisao

O tarball NAO sobe: o que se envia e o endereco dele e o
sha256. Hospedar binario exige cota, expiracao e politica de
abuso; um release do GitHub ja faz isso melhor, e o hash e o
que torna a origem irrelevante.

dataforge publish --registry=../registro             # interno
dataforge publish --remoto                           # a comunidade

dataforge versions

Cada versao mora numa venv propria em
'~/.dataforge/versoes/<versao>'. A escolha global fica no
arquivo 'atual'; a do projeto, no campo 'dataforge' do
forge.toml — o mesmo que o manifesto ja lia.

dataforge use <versao> [--global]

Sem '--global', escreve 'dataforge = "<versao>"' na secao
[project] do forge.toml — e o arquivo e reescrito LINHA A
LINHA, para nao apagar comentarios nem reordenar campos.

E o pino VALE: 'dataforge run' num projeto que exige outra
versao entrega a execucao a ela, quando ela esta instalada.
Quando nao esta, recusa e diz como instalar — rodar na
versao errada e o que o pino existe para impedir.

'DATAFORGE_SEM_TROCA=1' desliga a troca.

dataforge use 1.0.0                                  # fixa no projeto
dataforge use 1.0.0 --global                         # fixa para a maquina

dataforge upgrade [versao]

Sem versao, pergunta ao site qual e a mais nova. A instalacao
e uma venv propria: a versao que ja roda nao e tocada, e por
isso um upgrade que falha no meio nao deixa a maquina sem
DataForge.

dataforge upgrade                                    # a mais nova publicada
dataforge upgrade 1.0.0 --check                      # so diz o que faria

dataforge workspace [pasta]

Cada pacote tem o seu forge.toml, e a unica forma de saber se
dois deles pedem faixas incompativeis do mesmo terceiro era
instalar os dois e esperar o erro — que aparece na maquina de
quem consome.

Ele LE e relata: nao instala nada. Sai com 2 quando ha
conflito, porque instalar duas copias em versoes diferentes
gera bug irreproduzivel.

dataforge workspace                                  # a arvore daqui para baixo
dataforge workspace --json                           # para o CI ler

dataforge login [token]

O token e criado no painel do site e aparece UMA vez. Ele
fica em '~/.dataforge/credenciais.json', com modo 600: num
arquivo do projeto ele acabaria commitado, que e a forma
mais comum de vazar credencial de registro que existe.

O 'login' CONFERE o token antes de gravar — sem isso o erro
so apareceria no primeiro 'publish', longe da causa.

dataforge login                                      # pede o token e confere
dataforge login df_pat_…                             # sem perguntar

dataforge logout

dataforge whoami

dataforge stats [alvo]

Nao e 'linhas de codigo' como metrica de produtividade — e o
inventario: quantas acoes, quantos blueprints, o arquivo mais
longo, a acao mais longa.

Serve para achar o que cresceu demais sem ninguem notar. Uma
acao acima de 50 linhas costuma fazer mais de uma coisa.

dataforge stats                                      # o projeto inteiro
dataforge stats src/                                 # so uma pasta

dataforge profile <arquivo>

Um 'bench' diz que esta lento; um 'profile' diz ONDE.
Mede cada acao: quantas chamadas, tempo acumulado e por
chamada, ordenado pelo que mais custa.

Meca antes de otimizar. A acao que voce acha que e o gargalo
quase nunca e.

dataforge profile src/main.df

dataforge fix [alvo]

Roda o formatador e, em seguida, o linter — arrumando o que da
para arrumar sozinho e listando o resto.

O que exige julgamento nao e 'consertado' automaticamente:
uma ferramenta que muda o codigo precisa ser previsivel.

dataforge fix                                        # o projeto inteiro
dataforge fix --dry-run                              # so o relatorio

dataforge devops <init|docker|ci|k8s|doctor|…>

Dockerfile, compose, pipeline de CI, manifestos do
Kubernetes, chart do Helm, nginx, Prometheus, SBOM.

O que ele gera nao e esboco: e o que se poria em
producao — usuario sem privilegio, limite de recurso,
sonda de saude e segredo fora do repositorio.

Os artefatos saem conforme o que o projeto ADOTA: quem
nao usa banco nao ganha um Postgres no compose.

Arquivo que ja existe e PULADO, nao sobrescrito.

dataforge devops init                                # tudo o que faz sentido
dataforge devops docker                              # Dockerfile e compose
dataforge devops k8s --dominio=app.exemplo.br
dataforge devops doctor                              # o que falta para subir
dataforge devops secrets                             # o que nao pode ir ao repo

dataforge telegram <new|run|doctor|webhook|off>

O token vem de $TELEGRAM_TOKEN — nunca do código. 'doctor' pergunta ao próprio Telegram por que o bot está calado: token, webhook brigando com o polling, privacidade de grupo ligada.

dataforge telegram new meubot                        # cria o projeto
dataforge telegram doctor                            # por que ele não responde
dataforge telegram run                               # sobe em long polling
dataforge telegram webhook https://x.dev             # registra o webhook

dataforge vitrine <run|dev|doctor|new>

Um programa de cima para baixo vira uma pagina web. 'dev'
recarrega ao salvar; 'doctor' diz por que ela nao sobe.

Nao ha 'build': nao existe bundler nem transpilacao — o
que roda e o proprio .df.

dataforge vitrine dev                                # sobe recarregando ao salvar
dataforge vitrine doctor                             # o que falta para subir
dataforge vitrine new meupainel                      # cria o projeto

dataforge editor [status|remove]

Copia a extensao para o VS Code, Insiders, Cursor, VSCodium e
Windsurf — todos os que encontrar. Depois disso, todo arquivo
.df abre com as palavras reservadas coloridas, 23 snippets e a
indentacao de 4 espacos que a linguagem exige.

O instalador ja faz isso; use este comando para reinstalar
depois de atualizar o DataForge ou de instalar um editor novo.

dataforge editor                                     # instala em todos
dataforge editor status                              # so confere

dataforge debug <arquivo.df>

Para, mostra o que esta valendo e deixa andar de uma
instrucao por vez. Dentro dele: 'p' passo, 'n' proximo,
'f' sai da acao, 'c' continua, 'vars' lista o escopo,
'pilha' mostra quem chamou quem, e qualquer expressao e
avaliada no quadro onde voce parou.

Sem '--parar', ele para na primeira instrucao.

dataforge debug conta.df                             # para no comeco
dataforge debug conta.df --parar=42                  # so na linha 42
dataforge debug conta.df --vigiar=saldo              # para quando 'saldo' mudar
dataforge debug conta.df --vigiar-leitura=saldo      # para quando 'saldo' for lido

dataforge dap

Fala o Debug Adapter Protocol por stdin/stdout. E o que poe
os breakpoints na margem do editor, a pilha de chamadas no
painel, as variaveis em arvore e o console de avaliacao —
com 'entrar', 'passar por cima' e 'sair da acao'.

Voce nao o roda a mao: a extensao do VS Code o inicia
sozinha ao apertar F5. Este comando existe para outros
editores que perguntam qual adaptador iniciar.

Para depurar no terminal — por ssh, sem interface
grafica — use 'dataforge debug'.

dataforge dap                                        # o que o editor executa

dataforge lsp

Fala o Language Server Protocol por stdin/stdout. E o que da
ao editor autocompletar sensivel a contexto, erro sublinhado
enquanto se digita, ir-para-definicao, renomear com seguranca,
o esquema do arquivo e ajuda de assinatura.

Voce nao o roda a mao: a extensao do VS Code o inicia
sozinha. Este comando existe para outros editores — Neovim,
Helix, Emacs — que perguntam qual comando iniciar.

dataforge lsp                                        # o que o editor executa
dataforge lsp --log=/tmp/lsp.log                     # com registro

dataforge explain <codigo>

Todo erro do DataForge tem um codigo estavel, como DF0601.
Este comando diz o que ele significa e como resolver.

dataforge explain DF0601
dataforge explain 0401                               # o prefixo e opcional
dataforge explain KeyError                           # o nome da classe tambem

dataforge crucible [alvo]

Descobre os arquivos, carrega as suites e roda tudo junto.
Sem alvo, procura em tests/, testes/ e *_crucible.df.

dataforge crucible                                   # roda tudo
dataforge crucible --tag=rapido                      # so os rapidos
dataforge crucible --formato=junit --out=r.xml       # para o CI

dataforge big-o [alvo]

Le a arvore e conta estrutura: lacos aninhados, recursao,
e o custo das funcoes embutidas que aparecem. Diz a classe
E o porque — 'O(n^2)' sozinho nao ajuda a melhorar nada.

dataforge big-o src/ -v
dataforge big-o --escala                             # a tabela de referencia

dataforge oop [alvo]

Mede cada blueprint sem rodar: WMC, DIT, NOC, CBO, RFC, LCOM,
fan-in, fan-out, instabilidade e indice de manutenibilidade.

Cada limite ultrapassado vira um cheiro com o principio que
ele fere e o que fazer: god blueprint (SRP), contrato gordo
(ISP), switch de tipo (OCP), sobrescrita que recusa (LSP),
dependencia concreta (DIP), heranca funda, baixa coesao,
modelo anemico, inveja de recurso e dependencia circular.

dataforge oop src/                                   # metricas e cheiros
dataforge oop src/ --diagrama > classes.mmd          # o diagrama para o README

dataforge custo [alvo]

Uma linha de import nao parece cara. Um modulo de 200
simbolos entra inteiro no processo.

dataforge custo src/

dataforge gramatica [grupo|producao]

Cada producao traz o EBNF, um exemplo e a nota do que mais
engana. Os exemplos passam pelo lexer e pelo parser de verdade
a cada execucao da suite — a gramatica nao tem como descrever
uma sintaxe que o parser ja nao aceita.

dataforge gramatica                                  # os grupos
dataforge gramatica pipeline                         # uma producao
dataforge gramatica expressoes --ebnf                # o EBNF de um grupo
dataforge gramatica --precedencia                    # quem liga mais forte

dataforge palavras [termo]

Sao 113: as 81 reservadas mais as contextuais. Cada uma traz
o que faz e um exemplo que RODA — eles saem de
'exemplos_palavras.py', e ha teste executando todos.

Com termo, procura no nome e na descricao.

dataforge palavras                                   # todas
dataforge palavras cycle                             # so o que fala de laco

dataforge erros [termo]

Sao 219 codigos em 19 familias. Sem termo, lista tudo
agrupado; com termo, procura no titulo e na explicacao.

dataforge erros                                      # o catalogo inteiro
dataforge erros banco                                # so o que fala de banco

dataforge doc [alvo]

dataforge doc src/ --out=doc/API.md

dataforge deps [alvo]

Quem adota quem, e avisa sobre ciclos.

dataforge tokens <arquivo>

dataforge ast <arquivo>

dataforge abi <antes.df> <depois.df>

A superficie de um modulo e o contrato dele: o que ele
exporta, com que aridade e com que tipos. Muda-la quebra
quem depende — em silencio, no dia da atualizacao.

Sai com 1 quando ha quebra, para reprovar no CI. O veredito
e o bump de semver que a mudanca EXIGE:

  maior     alguma coisa quebrou
  menor     so acrescimos compativeis
  correcao  a superficie nao mudou

dataforge abi v1/lib.df v2/lib.df                    # o que mudou
dataforge abi a.df b.df --json                       # como dado

dataforge alvo <arquivo> [--alvo=<nome>]

Le os 'adopt' e cruza com o que cada ambiente suporta.

  servidor   maquina com sistema operacional completo
  cli        programa de linha de comando
  navegador  CPython em WebAssembly, dentro de uma aba
  wasi       WebAssembly fora do navegador
  funcao     serverless: efemero, e com o disco so de leitura
  embarcado  microcontrolador

A leitura e ESTATICA: um 'roda' quer dizer 'nao achei
impedimento por esta via', e nao 'vai funcionar'.

dataforge alvo app.df                                # a tabela de todos
dataforge alvo app.df --alvo=navegador               # um so

dataforge percurso <arquivo>

O 'ir' mostra cada fase; o 'percurso' mostra TODAS em
ordem, com o que cada uma produziu e quanto levou — que e
a pergunta quando um arquivo demora a abrir no editor.

Ele NAO executa o programa: executar e o que o programa
faz, e um arquivo de verdade abre soquete e escreve em
disco. A ultima fase e nomeada e marcada como nao
percorrida, para que a ausencia tenha lugar.

Cada fase e medida UMA vez, com os imports aquecidos:
serve para comparar as fases entre si, e nao maquinas.

dataforge percurso app.df                            # a tabela de fases
dataforge percurso app.df --desenho                  # o caminho desenhado, com as ausencias

dataforge ecossistema

O desenho do ecossistema com uma marca por componente:

  [+]  existe, com esse papel
  [~]  equivale: outra peca responde a mesma pergunta
  [-]  nao existe, e o porque esta escrito

Ele CONFERE as duas direcoes: todo caminho citado existe
no disco, e todo modulo do nucleo aparece em algum
componente. Sem a segunda, um modulo novo nasce fora do
mapa e o inventario fica incompleto em silencio.

Sai com 1 quando o mapa e o disco discordam.

dataforge ecossistema                                # o inventario inteiro
dataforge ecossistema --ausencias                    # so o que nao existe, com o motivo

dataforge principios

Cada principio carrega a frase do documento, o que ela
significa AQUI, o veredito e uma prova que RODA — duas
delas chamam o analisador e uma abre um interpretador.

O veredito nao e dez de dez de proposito: ha parciais e
ha um que nao se aplica, com o motivo.

E as TENSOES: onde dois principios se contradizem, qual
venceu, o custo aceito e o arquivo onde isso mora. Uma
lista de principios diz o que se quer; a tensao diz o que
se escolheu quando nao era possivel querer as duas coisas.

dataforge principios                                 # os dez, medidos
dataforge principios --tensoes                       # so onde dois se contradizem

dataforge ir <arquivo> [--fase=…]

As representacoes do meio, que 'tokens' e 'ast' nao mostram.

  hir       a arvore depois do acucar, e quanto dele o arquivo usa
  mir       o grafo de fluxo: bloco basico, aresta, laco, tratador
  analises  alcance, constantes, escapatoria e nome nao definido
  ssa       uma definicao por nome, com os nos phi das juncoes
  otimizado o que os passes conseguem tirar deste arquivo
  lir       o que o compilador de fechamentos compilou, e o que recuou

Nao ha fase de codigo de maquina: o backend e compilador.py, e
o 'lir' e onde isso fica visivel.

dataforge ir app.df                                  # o caminho inteiro
dataforge ir app.df --fase=mir                       # so o grafo de fluxo
dataforge ir app.df --fase=lir                       # o que compilou

dataforge completar <bash|zsh|fish>

O script sai do proprio catalogo de comandos: um comando novo
aparece no Tab no dia em que entra aqui. As opcoes sao por
comando, e depois de 'run', 'check' ou 'fmt' o Tab completa
arquivo. O script nao chama o dataforge a cada tecla.

dataforge completar bash > ~/.local/share/bash-completion/completions/dataforge # bash
dataforge completar zsh > "${fpath[1]}/_dataforge"   # zsh
dataforge completar fish > ~/.config/fish/completions/dataforge.fish # fish

dataforge clean

Remove dist/, __pycache__ e o cache de pacotes baixados.

dataforge version

dataforge help [comando]

dataforge help                                       # visao geral
dataforge help add                                   # so o 'add'