---
name: fluigcli
description: >-
  Use ao desenvolver ou implantar em servidores TOTVS Fluig com a CLI `fluigcli`:
  datasets, formulários, eventos globais, mecanismos de atribuição, scripts de
  eventos de processo e widgets. A CLI é não-interativa e feita para agentes
  (saída `--json` com envelope estável e exit codes 0–7). Ative quando o projeto
  tiver pasta `.fluigcli/`, `datasets/`, `forms/`, `events/`, `mechanisms/`,
  `workflow/` ou `wcm/`, ou quando o pedido envolver Fluig / fluigcli.
---

# fluigcli para agentes

`fluigcli` é uma CLI **não oficial** e de código aberto para desenvolvimento
TOTVS Fluig. Ela foi desenhada para uso não-interativo: você a dirige por flags,
lê um envelope JSON e decide pelo **exit code** — não pelo texto.

## Regras de ouro

1. **Sempre** passe `--json` e `--non-interactive` nos comandos que **você**
   executa. Nunca dependa de prompt. Exceção única: comando que você **escreve
   para a pessoa rodar à mão** — ver [Comandos para execução manual](#comandos-para-execução-manual).
2. **Decida pelo exit code**, não pela mensagem (que é humana e em pt-BR):

   | código | significado | o que fazer |
   |---|---|---|
   | 0 | sucesso | seguir |
   | 2 | uso incorreto | corrigir o comando/flags |
   | 3 | autenticação/sessão | conferir credenciais (ver Autenticação) |
   | 4 | recurso não encontrado | conferir o id/nome |
   | 5 | erro do servidor Fluig | ler `error.message`; pode ser transitório |
   | 6 | falha parcial (lote) | inspecionar `data` item a item |
   | 7 | dependência ausente no servidor | rodar `fluigcli server install-helper` |

   Tabela completa e formato do envelope: [`reference/contract.md`](reference/contract.md).
3. **Nunca** ponha senha em argumento de linha de comando (vaza em `ps`/histórico).
   Use `FLUIGCLI_PASSWORD` ou `--password-stdin`. Ver Autenticação.
4. **Direção dos verbos** (importante, é o contrário de "git"):
   `import` = servidor → local · `export` = local → servidor.

## Autenticação (não-interativa)

A CLI cadastra servidores (metadados, **sem senha**) e resolve a senha nesta
ordem: `--password-stdin` → `FLUIGCLI_PASSWORD` → keyring do SO → prompt. Em
agente/CI use uma das duas primeiras. A **sessão é reaproveitada entre execuções**
(cache em disco), então normalmente a senha só é usada no primeiro comando.

Num projeto compartilhado, o `.fluigcli/servers.json` (versionável) guarda só a
conexão — o **usuário** vem do overlay pessoal `.fluigcli/servers.local.json`
(git-ignorado). Se ele não existe (ex.: repo recém-clonado no CI), defina
`FLUIGCLI_USERNAME` para não travar em modo não-interativo.

```sh
# 1) cadastrar o servidor uma vez (metadados; senha vai para o keyring se houver)
echo "$SENHA" | fluigcli server add --name homolog \
  --host fluig.empresa.com.br --port 443 --ssl \
  --username deploy --company-id 1 --password-stdin --json

# 2) validar o acesso
echo "$SENHA" | fluigcli server test homolog --password-stdin --json

# 3) nos demais comandos, aponte o servidor e forneça a senha por env var
export FLUIGCLI_SERVER=homolog FLUIGCLI_PASSWORD="$SENHA"
fluigcli dataset list --json
```

## Descobrindo comandos

O mapa de comandos e receitas prontas (subir um dataset, exportar um script de
processo, baixar um formulário) está em [`reference/commands.md`](reference/commands.md).

Cada comando tem ajuda detalhada em pt-BR — **prefira consultá-la** a assumir
flags:

```sh
fluigcli --help
fluigcli dataset --help
fluigcli dataset export --help
```

## Fluxo típico de deploy

1. `fluigcli server test <name> --json` → confirmar acesso (exit 0).
2. Editar os artefatos nas pastas convencionais do projeto (`datasets/`,
   `forms/`…). Para criar um artefato **do zero**, use o scaffold do grupo
   (`dataset new`, `form new`, `event new`, `mechanism new`, `widget new`,
   `workflow new-script <pid> <evento>`) — gera o esqueleto local correto,
   sem tocar o servidor. Ao escrever o código JS, as **assinaturas exatas**
   das APIs do Fluig (server-side: `hAPI`, `getValue`/variáveis `WK*`,
   `DatasetBuilder`/`DatasetFactory`, `docAPI`, SDK `com.fluig.sdk.*`;
   client-side: `form.*`, `FLUIGC`, `WCMAPI`, `wdkAddChild`) estão em
   [`reference/fluig.d.ts`](reference/fluig.d.ts) — **consulte-o via grep**
   (é grande) em vez de adivinhar método ou variável. O `fluigcli audit`
   valida as chamadas contra essa mesma referência (regras FL*, typos com
   sugestão do nome certo).
3. Em formulário ou widget: **escreva já conforme o Style Guide 2.0**
   ([`reference/styleguide.md`](reference/styleguide.md): variáveis do tema,
   substituições comuns, FLUIGC) e confira com `fluigcli audit <path> --json`
   (exit 1 = reprovado; corrija pelas `suggestion`/`fix` dos
   `data.findings[]` — ou `audit --fix` para as determinísticas — e repita
   até exit 0). Formulário de processo com seções por etapa (`activity-N`):
   rode também `fluigcli audit --process <id> --json` — ele cruza as seções
   com as etapas reais do processo e pega o número de etapa errado, que
   nenhum outro comando acusa.
4. `fluigcli <recurso> export <arquivo|pasta> --json` → publicar (local → servidor).
5. Conferir `ok`/exit code; em lote, tratar exit 6 (parcial) olhando `data`.

## Comandos para execução manual

Às vezes você não executa o passo. Você **escreve a linha de comando para a
pessoa rodar no terminal dela**. O caso mais comum é a publicação em produção.

Nesse caso, e **somente nesse caso**, sugira o comando no **modo interativo**:

- Use `--server <nome>` **no próprio comando**. Não instrua
  `export FLUIGCLI_SERVER=...`: a variável exportada continua valendo nos
  comandos seguintes daquele terminal e leva a publicar em produção sem querer.
- **Não** ponha `--json` nem `--non-interactive`. A saída humana é tabela em
  pt-BR e é mais fácil de conferir na hora.
- **Não** ponha `--yes`. A trava de produção precisa pedir a confirmação — é a
  última checagem antes da escrita.
- **Não** peça `FLUIGCLI_PASSWORD` nem senha na linha. O keyring, a sessão em
  cache ou o prompt resolvem.
- **Mantenha** as flags que mudam o QUE o comando faz (`--new`, `--no-audit`,
  `--events`, `--build`). Elas são parte da decisão, não da forma de execução.

Não sugira assim:

```sh
export FLUIGCLI_SERVER=producao
fluigcli dataset export datasets/ds_glb_nat_fin.js --json --non-interactive
fluigcli form export forms/frm_fin_adiantamento_pagar --no-audit --json --non-interactive
```

Sugira assim:

```sh
fluigcli dataset export datasets/ds_glb_nat_fin.js --server producao
fluigcli form export forms/frm_fin_adiantamento_pagar --no-audit --server producao
```

Quando **você** roda o comando, vale a regra de ouro 1: `--json` e
`--non-interactive`, mais `--yes` em servidor `prod`.

## Limites

- Scripts de evento de processo (`workflow export`) e `widget list|import`
  exigem o **componente auxiliar** (fluigcliHelper) no servidor. Exit 7 → rode
  `fluigcli server install-helper <name>` (uma vez por servidor).
- ⚠️ `request start`/`move` e `form records create`/`update` **não executam os
  eventos do formulário** (`displayFields`, `validateForm`) — a plataforma não
  os roda no caminho REST. Uma solicitação com os campos obrigatórios vazios é
  aceita sem crítica. **Não use esses comandos para testar a validação do
  formulário**: o teste passa e a conclusão sai errada. Valide no navegador ou
  no `fluigcli dev`. Os eventos de **processo** rodam normalmente.
- HTTP (`--ssl=false`) trafega senha e cookies em texto claro; prefira HTTPS.